PiecewiseITS#

class causalpy.experiments.piecewise_its.PiecewiseITS[source]#

Piecewise Interrupted Time Series (Segmented Regression) experiment.

This class implements segmented-regression / piecewise linear models for Interrupted Time Series analysis with known interruption dates. Unlike the standard InterruptedTimeSeries which fits a model to pre-intervention data and forecasts a counterfactual, PiecewiseITS fits one model to the full time series and estimates explicit level and/or slope changes at each interruption.

The model uses patsy formulas with custom step() and ramp() transforms:

  • step(time, threshold): Creates a binary indicator (1 if time >= threshold) for level changes

  • ramp(time, threshold): Creates a ramp function (max(0, time - threshold)) for slope changes

Parameters:

  • data (NativeDataFrame) – Time series data as any eager dataframe Narwhals supports, such as pandas, Polars, or PyArrow. The time axis comes from the step() or ramp() column in the formula, not from the index, so a dataframe without an index works here. Converted to pandas internally.

  • formula (str) – A patsy formula specifying the model. Must include at least one step() or ramp() term, and all such terms must use the same time variable. Example: "y ~ 1 + t + step(t, 50) + ramp(t, 50)"

  • model (PyMCModel | RegressorMixin | None) – A PyMC (Bayesian) or sklearn (OLS) model. If None, defaults to a PyMC LinearRegression model.

formula#

The patsy formula used for the model.

Type:

str

interruption_times#

Canonicalized interruption thresholds extracted from the formula.

Type:

list

labels#

Names of all coefficients in the design matrix.

Type:

list[str]

effect#

Pointwise causal effect (fitted expectation - counterfactual expectation).

Type:

xr.DataArray or np.ndarray

cumulative_effect#

Cumulative causal effect over time.

Type:

xr.DataArray or np.ndarray

Notes

Estimate extraction

One model is fitted to the full time series. The no-intervention counterfactual is predicted after setting every step() and ramp() design-matrix column to zero, and the pointwise effect is the fitted conditional expectation minus that counterfactual expectation. Bayesian backends contrast posterior mu values, OLS contrasts point predictions, and the cumulative effect is the running sum.

The step and ramp transforms are patsy stateful transforms that handle both numeric and datetime time columns. For datetime, thresholds can be specified as strings (e.g., ‘2020-06-01’) or pd.Timestamp objects.

Bare datetime predictors are represented as continuous elapsed days. Use C(date) when date fixed effects are intended instead.

References

  • Wagner AK, et al. (2002). Segmented regression analysis of interrupted time series studies in medication use research. Journal of Clinical Pharmacy and Therapeutics.

  • Lopez Bernal J, et al. (2017). Interrupted time series regression for the evaluation of public health interventions: a tutorial. Int J Epidemiol.

Examples

>>> import causalpy as cp
>>> import pandas as pd
>>> import numpy as np
>>> # Generate simple piecewise data
>>> np.random.seed(42)
>>> t = np.arange(100)
>>> y = (
...     10
...     + 0.1 * t
...     + 5 * (t >= 50)
...     + 0.2 * np.maximum(0, t - 50)
...     + np.random.normal(0, 1, 100)
... )
>>> df = pd.DataFrame({"t": t, "y": y})
>>> result = cp.PiecewiseITS(
...     df,
...     formula="y ~ 1 + t + step(t, 50) + ramp(t, 50)",
...     model=cp.pymc_models.LinearRegression(
...         sample_kwargs={"random_seed": 42, "progressbar": False}
...     ),
... )

Different effects per intervention:

>>> # Level change only at t=50, level + slope change at t=100
>>> result = cp.PiecewiseITS(
...     df,
...     formula="y ~ 1 + t + step(t, 50) + step(t, 100) + ramp(t, 100)",
...     model=...,
... )

With datetime thresholds:

>>> df["date"] = pd.date_range("2020-01-01", periods=100, freq="D")
>>> result = cp.PiecewiseITS(
...     df,
...     formula="y ~ 1 + date + step(date, '2020-02-20') + ramp(date, '2020-02-20')",
...     model=...,
... )

Methods

PiecewiseITS.effect_summary(*[, window, ...])

Generate a decision-ready summary of PiecewiseITS causal effects.

PiecewiseITS.generate_report(*[, ...])

Generate a self-contained HTML report for this experiment.

PiecewiseITS.get_plot_data(*[, hdi_prob])

Recover the data of the experiment along with prediction and effect information.

PiecewiseITS.plot(*[, round_to, ci_prob, ...])

Plot the piecewise interrupted time-series results.

PiecewiseITS.print_coefficients([round_to])

Ask the model to print its coefficients.

PiecewiseITS.set_maketables_options(*[, ...])

Set optional maketables rendering options for this experiment.

PiecewiseITS.summary([round_to])

Print summary of main results and model coefficients.

Attributes

idata

Return fitted DataTree when the model backend supports it.

supports_bayes

supports_ols

supports_pymc_forecast

labels

data

__init__(data, formula, model=None)[source]#
Parameters:
Return type:

None

classmethod __new__(*args, **kwargs)#