InterruptedTimeSeries#

class causalpy.experiments.interrupted_time_series.InterruptedTimeSeries[source]#

The class for interrupted time series analysis.

Supports both two-period (permanent intervention) and three-period (temporary intervention) designs. When treatment_end_time is provided, the analysis splits the post-intervention period into an intervention period and a post-intervention period, enabling analysis of effect persistence and decay.

Parameters:

  • data (DataFrame) – A pandas dataframe with time series data. The index should be either a DatetimeIndex or numeric (integer/float).

  • treatment_time (int | float | Timestamp) – The time when treatment occurred, should be in reference to the data index. Must match the index type (DatetimeIndex requires pd.Timestamp). INCLUSIVE: Observations at exactly treatment_time are included in the post-intervention period (uses >= comparison).

  • formula (str) – A statistical model formula using patsy syntax (e.g., “y ~ 1 + t + C(month)”).

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

  • treatment_end_time (int | float | Timestamp | None) – The time when treatment ended, enabling three-period analysis. Must be greater than treatment_time and within the data range. If None (default), the analysis assumes a permanent intervention (two-period design). INCLUSIVE: Observations at exactly treatment_end_time are included in the post-intervention period (uses >= comparison).

  • **kwargs (Any) – Additional keyword arguments passed to the model.

Examples

Two-period design (permanent intervention):

>>> import causalpy as cp
>>> df = (
...     cp.load_data("its")
...     .assign(date=lambda x: pd.to_datetime(x["date"]))
...     .set_index("date")
... )
>>> treatment_time = pd.to_datetime("2017-01-01")
>>> result = cp.InterruptedTimeSeries(
...     df,
...     treatment_time,
...     formula="y ~ 1 + t + C(month)",
...     model=cp.pymc_models.LinearRegression(
...         sample_kwargs={"random_seed": 42, "progressbar": False}
...     ),
... )

Three-period design (temporary intervention):

>>> treatment_time = pd.to_datetime("2017-01-01")
>>> treatment_end_time = pd.to_datetime("2017-06-01")
>>> result = cp.InterruptedTimeSeries(
...     df,
...     treatment_time,
...     formula="y ~ 1 + t + C(month)",
...     model=cp.pymc_models.LinearRegression(
...         sample_kwargs={"random_seed": 42, "progressbar": False}
...     ),
...     treatment_end_time=treatment_end_time,
... )
>>> # Get period-specific effect summaries
>>> intervention_summary = result.effect_summary(period="intervention")
>>> post_summary = result.effect_summary(period="post")

Notes

For Bayesian models, the causal impact is calculated using the posterior expectation (mu) rather than the posterior predictive (y_hat). This means the impact and its uncertainty represent the systematic causal effect, excluding observation-level noise. The uncertainty bands in the plots reflect parameter uncertainty and counterfactual prediction uncertainty, but not individual observation variability.

The three-period design is useful for analyzing temporary interventions such as: - Marketing campaigns with defined start and end dates - Policy trials or pilot programs - Clinical treatments with limited duration - Seasonal interventions

Use effect_summary(period="intervention") to analyze effects during the intervention, and effect_summary(period="post") to analyze effect persistence after the intervention ends.

Methods

InterruptedTimeSeries.__init__(data, ...[, ...])

InterruptedTimeSeries.algorithm()

Run the experiment algorithm: fit model, predict, and calculate causal impact.

InterruptedTimeSeries.analyze_persistence([...])

Analyze effect persistence between intervention and post-intervention periods.

InterruptedTimeSeries.effect_summary(*[, ...])

Generate a decision-ready summary of causal effects for Interrupted Time Series.

InterruptedTimeSeries.fit(*args, **kwargs)

InterruptedTimeSeries.get_plot_data(*args, ...)

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

InterruptedTimeSeries.get_plot_data_bayesian([...])

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

InterruptedTimeSeries.get_plot_data_ols()

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

InterruptedTimeSeries.input_validation(data, ...)

Validate the input data and model formula for correctness

InterruptedTimeSeries.plot(*args[, show])

Plot the model.

InterruptedTimeSeries.print_coefficients([...])

Ask the model to print its coefficients.

InterruptedTimeSeries.summary([round_to])

Print summary of main results and model coefficients.

Attributes

datapost

Data from on or after the treatment time (inclusive).

datapre

Data from before the treatment time (exclusive).

idata

Return the InferenceData object of the model.

supports_bayes

supports_ols

labels

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

None

classmethod __new__(*args, **kwargs)#