InterruptedTimeSeries

class causalpy.experiments.interrupted_time_series.InterruptedTimeSeries

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 (pd.DataFrame) – A pandas dataframe with time series data. The index should be either a DatetimeIndex or numeric (integer/float).

• treatment_time (Union[int, float, pd.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 (Union[PyMCModel, RegressorMixin], optional) – A PyMC (Bayesian) or sklearn (OLS) model. If None, defaults to a PyMC LinearRegression model.

• treatment_end_time (Union[int, float, pd.Timestamp], optional) – 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 (dict) – 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.analyze_persistence([...])	Analyze effect persistence between intervention and post-intervention periods.
InterruptedTimeSeries.effect_summary([...])	Generate a decision-ready summary of causal effects.
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, **kwargs)	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

expt_type
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)

Parameters:

• data (DataFrame)

• treatment_time (int | float | Timestamp)

• formula (str)

• model (PyMCModel | RegressorMixin | None)

• treatment_end_time (int | float | Timestamp | None)

• kwargs (dict)

Return type:

None

classmethod __new__(*args, **kwargs)