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 (pd.DataFrame) – A pandas DataFrame containing the time series data.

  • formula (str) – A patsy formula specifying the model. Must include at least one step() or ramp() term. Example: "y ~ 1 + t + step(t, 50) + ramp(t, 50)"

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

  • **kwargs (dict[str, Any]) – Additional keyword arguments passed to the model.

formula#

The patsy formula used for the model.

Type:

str

interruption_times#

List of interruption times extracted from the formula.

Type:

list

labels#

Names of all coefficients in the design matrix.

Type:

list[str]

effect#

Pointwise causal effect (observed - counterfactual).

Type:

xr.DataArray or np.ndarray

cumulative_effect#

Cumulative causal effect over time.

Type:

xr.DataArray or np.ndarray

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=...,
... )

Notes

The counterfactual is computed by setting all step/ramp terms to zero, representing what would have happened without the interventions.

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.

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.

Methods

PiecewiseITS.__init__(data, formula[, model])

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

Generate a decision-ready summary of causal effects.

PiecewiseITS.fit(*args, **kwargs)

PiecewiseITS.get_plot_data(*args, **kwargs)

Recover the data of an experiment along with the prediction and causal impact information.

PiecewiseITS.get_plot_data_bayesian([hdi_prob])

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

PiecewiseITS.get_plot_data_ols()

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

PiecewiseITS.plot(*args, **kwargs)

Plot the model.

PiecewiseITS.print_coefficients([round_to])

Ask the model to print its coefficients.

PiecewiseITS.summary([round_to])

Print summary of main results and model coefficients.

Attributes

expt_type

idata

Return the InferenceData object of the model.

supports_bayes

supports_ols

labels

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

None

classmethod __new__(*args, **kwargs)#