PanelMMM

PanelMMM is the single retained public MMM model API in Abacus.

Import it from:

from abacus.mmm.panel import PanelMMM

For conceptual guidance, see Model Overview. For data contracts, see Data Preparation.

Constructor

PanelMMM(...) is keyword-only.

The main constructor arguments are:

Argument	Meaning
`date_column`	Name of the date column in `X`
`channel_columns`	Required media columns
`target_column`	Semantic target column name
`target_type`	`"revenue"` or `"conversion"`
`adstock`	An `AdstockTransformation` instance
`saturation`	A `SaturationTransformation` instance
`dims`	Optional panel dimensions such as `("geo",)`
`control_columns`	Optional non-media regressors
`control_impacts`	Optional directional expectations for controls
`control_sign_policy`	`"soft"` or `"strict"`
`yearly_seasonality`	Number of yearly Fourier modes
`time_varying_intercept`	`bool` or an `HSGPBase` instance
`time_varying_media`	`bool` or an `HSGPBase` instance
`use_mundlak_cre`	Add Mundlak / correlated random effects terms
`scaling`	`Scaling`, a dict, or `None`
`model_config`	Prior and likelihood configuration
`sampler_config`	Default sampler settings
`adstock_first`	Whether adstock runs before saturation

Core lifecycle methods

The most commonly used methods are:

Method	Purpose
`build_model(X, y)`	Build the PyMC graph for the current configuration
`fit(X, y, **kwargs)`	Sample the posterior and store `idata`
`approximate_fit(X, y, ...)`	Fit with variational inference instead of NUTS
`sample_prior_predictive(X, y, ...)`	Sample prior and prior predictive draws
`sample_posterior_predictive(X, ...)`	Sample posterior predictive draws
`predict(X, ...)`	Return posterior mean predictions
`predict_posterior(X, ...)`	Return posterior predictive samples for `output_var`
`save(path, **kwargs)`	Save `idata` to NetCDF
`load(path, check=True)`	Load a saved model from NetCDF
`load_from_idata(idata, check=True)`	Rebuild from an in-memory `InferenceData`

fit(...), sample_prior_predictive(...), predict(...), save(...), and the load helpers come from the shared model-builder base classes but are part of the user-facing PanelMMM surface.

Post-fit model methods

PanelMMM also exposes model-specific post-fit methods:

Method	Purpose
`add_original_scale_contribution_variable(var=[...])`	Add original-scale deterministics before fitting
`sample_saturation_curve(...)`	Sample posterior saturation curves
`sample_adstock_curve(...)`	Sample posterior adstock curves
`sample_channel_contribution_forward_pass(...)`	Sample channel contributions in scaled target space
`channel_contribution_forward_pass(...)`	Evaluate channel contributions in original target units
`get_channel_contribution_forward_pass_grid(...)`	Build a contribution grid over shared spend multipliers
`new_spend_contributions(...)`	Simulate forward contribution paths for a spend scenario
`add_lift_test_measurements(...)`	Add lift-test calibration measurements
`add_cost_per_target_calibration(...)`	Add cost-per-target calibration penalties
`add_events(df_events, prefix, effect)`	Add dated event effects before build

Bound properties

Once the model exists, these bound properties expose the retained post-fit surface:

Property	Returns
`plot`	`MMMPlotSuite`
`data`	`MMMIDataWrapper`
`summary`	`MMMSummaryFactory`
`diagnostics`	`MMMDiagnosticsFactory`
`efficiency_metric`	Default efficiency metric key for `target_type`
`efficiency_metric_label`	Display label such as `ROAS` or `CPA`

See Post-Fit Facades.

Other useful attributes

Common model attributes include:

Attribute	Meaning
`idata`	The fitted `arviz.InferenceData`
`output_var`	Output variable name used in predictive sampling (`"y"`)
`channel_columns`	Configured channel names
`control_columns`	Configured control names
`dims`	Configured panel dimensions
`mu_effects`	Additive effects attached before build

Minimal example

from abacus.mmm import GeometricAdstock, LogisticSaturation
from abacus.mmm.panel import PanelMMM

mmm = PanelMMM(
    date_column="date",
    target_column="revenue",
    channel_columns=["tv", "search", "social"],
    dims=("geo",),
    adstock=GeometricAdstock(l_max=8),
    saturation=LogisticSaturation(),
)

mmm.fit(X, y, draws=500, tune=500, chains=2, progressbar=False)
mmm.sample_posterior_predictive(X=X, progressbar=False)