GradedInterventionTimeSeries

class causalpy.experiments.graded_intervention_its.GradedInterventionTimeSeries

Interrupted time series experiment with graded interventions and transfer functions.

This experiment class handles causal inference for time series with graded (non-binary) interventions, incorporating saturation and adstock effects. Following the standard CausalPy pattern, it takes data and an unfitted model, performs transform parameter estimation, fits the model, and provides visualization, diagnostics, and counterfactual effect estimation.

Typical workflow: 1. Create an unfitted TransferFunctionOLS model with configuration 2. Pass data + model to this experiment class 3. Experiment estimates transforms, fits model, and provides results 4. Use experiment methods for visualization and effect estimation

Fitting Procedure

The experiment uses a nested optimization approach to estimate transform parameters and fit the regression model:

Outer Loop (Transform Parameter Estimation): The experiment searches for optimal saturation and adstock parameters either via grid search (exhaustive evaluation of discrete parameter combinations) or continuous optimization (gradient-based search). For grid search with N saturation parameter combinations and M adstock parameter combinations, all N x M combinations are evaluated.

Inner Loop (Model Fitting): For each candidate set of transform parameters, the raw treatment variable is transformed by applying saturation (diminishing returns) and adstock (carryover effects). The transformed treatment is combined with baseline predictors to create a full design matrix, and an OLS or ARIMAX model is fitted. The model that achieves the lowest root mean squared error (RMSE) determines the selected parameters.

This nested approach is computationally efficient because OLS has a closed-form solution requiring only matrix operations, making each individual model fit very fast. For ARIMAX error models, numerical optimization is required for each fit, increasing computational cost but providing explicit modeling of autocorrelation structure.

type data:

DataFrame

param data:

Time series data with datetime or numeric index.

type data:

pd.DataFrame

type y_column:

str

param y_column:

Name of the outcome variable column.

type y_column:

str

type treatment_names:

List[str]

param treatment_names:

List of treatment variable names (e.g., [“comm_intensity”]).

type treatment_names:

List[str]

type base_formula:

str

param base_formula:

Patsy formula for baseline model (e.g., “1 + t + temperature”).

type base_formula:

str

type model:

TransferFunctionOLS

param model:

UNFITTED model with configuration for transform parameter estimation.

type model:

TransferFunctionOLS

data

Input data.

Type:

pd.DataFrame

y

Outcome variable values.

Type:

np.ndarray

X_baseline

Baseline design matrix.

Type:

np.ndarray

Z_treatment

Treatment design matrix.

Type:

np.ndarray

X_full

Full design matrix.

Type:

np.ndarray

predictions

Fitted values from model.

Type:

np.ndarray

residuals

Model residuals.

Type:

np.ndarray

score

R-squared of the model.

Type:

float

Examples

import causalpy as cp

# Step 1: Create UNFITTED model with configuration
model = cp.skl_models.TransferFunctionOLS(
    saturation_type="hill",
    saturation_grid={"slope": [1.0, 2.0, 3.0], "kappa": [3, 5, 7]},
    adstock_grid={"half_life": [2, 3, 4, 5]},
    estimation_method="grid",
    error_model="hac",
)

# Step 2: Pass to experiment (experiment estimates transforms and fits model)
result = cp.GradedInterventionTimeSeries(
    data=df,
    y_column="water_consumption",
    treatment_names=["comm_intensity"],
    base_formula="1 + t + temperature + rainfall",
    model=model,
)

# Step 3: Use experiment methods
result.summary()
result.plot()
result.plot_diagnostics()
effect = result.effect(window=(df.index[0], df.index[-1]), scale=0.0)

Methods

GradedInterventionTimeSeries.__init__(data, ...)	Initialize experiment with data and unfitted model (standard CausalPy pattern).
GradedInterventionTimeSeries.effect(window)	Estimate the causal effect of scaling treatment channels in a time window.
GradedInterventionTimeSeries.get_plot_data(...)	Recover the data of an experiment along with the prediction and causal impact information.
GradedInterventionTimeSeries.get_plot_data_bayesian(...)	Bayesian plot data not yet implemented.
GradedInterventionTimeSeries.get_plot_data_ols()	Get plot data for OLS results.
GradedInterventionTimeSeries.plot([round_to])	Plot the model fit and results.
GradedInterventionTimeSeries.plot_diagnostics([lags])	Display diagnostic plots and tests for model residuals.
GradedInterventionTimeSeries.plot_effect(...)	Plot counterfactual effect analysis results.
GradedInterventionTimeSeries.plot_irf(channel)	Plot the Impulse Response Function (IRF) for a treatment channel.
GradedInterventionTimeSeries.plot_transforms([...])	Plot estimated saturation and adstock transformation curves.
GradedInterventionTimeSeries.print_coefficients([...])	Ask the model to print its coefficients.
GradedInterventionTimeSeries.summary([round_to])	Print a summary of the model results.

Attributes

expt_type
idata	Return the InferenceData object of the model.
supports_bayes
supports_ols

__init__(data, y_column, treatment_names, base_formula, model=None, **kwargs)

Initialize experiment with data and unfitted model (standard CausalPy pattern).

This method: 1. Validates inputs and builds baseline design matrix 2. Estimates transform parameters for each treatment 3. Applies transforms and builds full design matrix 4. Calls model.fit(X_full, y) 5. Extracts results for visualization and analysis

Parameters:

• data (pd.DataFrame) – Time series data.

• y_column (str) – Name of outcome variable.

• treatment_names (List[str]) – List of treatment variable names (e.g., [“comm_intensity”]).

• base_formula (str) – Patsy formula for baseline model.

• model (TransferFunctionOLS) – UNFITTED model with configuration for transform estimation.

classmethod __new__(*args, **kwargs)