HierarchicalInterruptedTimeSeries#

class causalpy.experiments.hierarchical_interrupted_time_series.HierarchicalInterruptedTimeSeries[source]#

Hierarchical ITS for multi-unit panels with unit-specific launch times.

Unlike InterruptedTimeSeries (single unit, single treatment time), this experiment accepts a long-format panel where every unit has its own launch time. Per-unit intercepts, covariate slopes and launch “lift” are partially pooled through a hierarchical PyMC model, which lets the model borrow strength across units and produces a population-level predictive distribution useful for forecasting the effect of a new unit.

Three effect parameterizations are available:

  • effect_type="instant" — a single post-launch lift per unit, lift[unit] ~ Normal(mu_lift, sigma_lift).

  • effect_type="event_study" — dynamic per-bin effects over post-launch event time (pre-launch is the implicit reference).

  • effect_type="placebo" — the event-study form extended with pre-launch “leads” used as placebos to test the no-anticipation assumption.

Parameters:

  • data (DataFrame) – Long-format panel. Must contain unit_col, time_col (numeric), treatment_time_col (numeric, same units as time_col) and any columns referenced by formula.

  • formula (str) – Patsy formula for the covariate design, e.g. "sales ~ 0 + emails + price". An intercept should not be included — the hierarchical alpha term plays that role and an intercept column will be dropped with a warning.

  • unit_col (str) – Column identifying units (e.g. product id).

  • time_col (str) – Numeric time index column (e.g. week_idx). Datetime columns are not supported directly; convert to an integer index first.

  • treatment_time_col (str) – Numeric column with each unit’s launch time (same units as time_col).

  • effect_type (Literal['instant', 'event_study', 'placebo']) – The effect parameterization.

  • bin_edges (Sequence[float] | None) – Post-launch bin edges (in units of time_col). Required for effect_type="event_study" and "placebo".

  • placebo_edges (Sequence[float] | None) – Pre-launch (negative) bin edges for effect_type="placebo". Rows with tau below the smallest edge are the implicit reference.

  • seasonality (dict | None) – Shared Fourier seasonality spec, e.g. {"period": 52, "K": 2}. If None (default), no seasonality term is included.

  • ar_residuals (bool) – If True, add hierarchical AR(1) residuals per unit via pytensor.scan. Requires a balanced panel (all units observed at the same time steps). The AR coefficient is partially pooled: rho[unit] ~ tanh(Normal(mu_rho, sigma_rho)).

  • model (PyMCModel | None) – A custom model instance. If None, a default is constructed.

Methods

HierarchicalInterruptedTimeSeries.__init__(...)

HierarchicalInterruptedTimeSeries.algorithm()

Fit model, compute observed/counterfactual predictions and impact.

HierarchicalInterruptedTimeSeries.effect_summary(*)

Return a compact summary of the population-level effect.

HierarchicalInterruptedTimeSeries.fit(*args, ...)

HierarchicalInterruptedTimeSeries.generate_report(*)

Generate a self-contained HTML report for this experiment.

HierarchicalInterruptedTimeSeries.get_plot_data(...)

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

HierarchicalInterruptedTimeSeries.get_plot_data_bayesian(...)

Return plot data for Bayesian models.

HierarchicalInterruptedTimeSeries.get_plot_data_ols(...)

Return plot data for OLS models.

HierarchicalInterruptedTimeSeries.plot(*args)

Plot the model.

HierarchicalInterruptedTimeSeries.plot_unit([...])

Plot observed vs counterfactual and causal impact for a single unit.

HierarchicalInterruptedTimeSeries.predictive_for_new_unit([...])

Draw from the population predictive distribution of a new unit's effect.

HierarchicalInterruptedTimeSeries.print_coefficients([...])

Print population-level coefficient summaries for the hierarchical model.

HierarchicalInterruptedTimeSeries.set_maketables_options(*)

Set optional maketables rendering options for this experiment.

HierarchicalInterruptedTimeSeries.summary([...])

Print a short summary of the fitted hierarchical model.

Attributes

expt_type

idata

Return the InferenceData object of the model.

supports_bayes

supports_ols

labels

data

__init__(data, formula, unit_col, time_col, treatment_time_col, effect_type='instant', bin_edges=None, placebo_edges=None, seasonality=None, ar_residuals=False, model=None, **kwargs)[source]#
Parameters:
Return type:

None

classmethod __new__(*args, **kwargs)#