run_experiment#

pymc_marketing.mmm.experiment.run_experiment(experiment_type, data, **kwargs)[source]#

Run a CausalPy experiment and return a wrapped result.

This is the main entry point for running causal experiments that can be used to calibrate an MMM via lift tests.

Parameters:

experiment_typestr or ExperimentType

The type of experiment to run. Accepts string aliases ("its", "sc", "did", "rd") or ExperimentType enum values.

datapd.DataFrame

The experiment data to pass to CausalPy.

**kwargs

Additional keyword arguments passed directly to the CausalPy experiment constructor. Common arguments include:

treatment_time: When the treatment/intervention started.
formula: Patsy formula for the model.
model: A CausalPy model instance (e.g. cp.pymc_models.LinearRegression()).
For Synthetic Control: control_units, treated_units.
For DiD: time_variable_name, group_variable_name.
For RD: treatment_threshold, running_variable_name.

Returns:

ExperimentResult: A wrapped result with methods for summarizing, plotting, and converting to lift test format.

Raises:

ImportError: If causalpy is not installed.
ValueError: If experiment_type is not a valid type.

Examples

Run an Interrupted Time Series experiment:

import causalpy as cp
from pymc_marketing.mmm.experiment import run_experiment

result = run_experiment(
    experiment_type="its",
    data=df,
    treatment_time=pd.Timestamp("2024-01-01"),
    formula="y ~ 1 + t",
    model=cp.pymc_models.LinearRegression(),
)

result.summary()
fig, ax = result.plot()

Run a Synthetic Control experiment:

result = run_experiment(
    experiment_type="sc",
    data=df,
    treatment_time=70,
    formula="actual ~ 0 + a + b + c",
    model=cp.pymc_models.WeightedSumFitter(),
)

df_lift = result.to_lift_test(channel="tv", x=1000.0, delta_x=200.0)