Model Specification — Abacus Documentation

Model Overview

Mon, 01 Jan 0001 00:00:00 +0000

PanelMMM is an additive Bayesian marketing mix model built in PyMC. This page describes the model structure that Abacus actually builds. For input layout, see Data Preparation. For individual configuration surfaces, see the other pages in this section. Core structure At fit time, Abacus builds the model mean in scaled target space as: mu = intercept_contribution + sum(channel_contribution over channel) + sum(control_contribution over control), if control_columns are configured + mundlak_contribution, if use_mundlak_cre=True + yearly_seasonality_contribution, if yearly_seasonality is enabled + any additional mu_effects The observed target is then attached through the configured likelihood distribution with mu=mu.

Adstock and Saturation

Mon, 01 Jan 0001 00:00:00 +0000

PanelMMM requires one adstock transform and one saturation transform. Abacus applies them inside the model graph rather than as a fixed preprocessing step. For the econometrics framing of these transforms, see Adstock and Saturation for Econometricians. How the transform path works Abacus combines the two transforms through forward_pass(...): if adstock_first=True, the order is adstock then saturation if adstock_first=False, the order is saturation then adstock The transformed result becomes channel_contribution on the model scale.

Seasonality and Trends

Mon, 01 Jan 0001 00:00:00 +0000

Abacus supports one built-in seasonality switch on PanelMMM and a broader additive-effect mechanism for custom seasonality, trend, and event terms. Built-in yearly seasonality Set yearly_seasonality= to add a yearly Fourier term directly to the main model specification. mmm = PanelMMM( date_column="date", target_column="sales", channel_columns=["tv", "search"], yearly_seasonality=3, adstock=GeometricAdstock(l_max=8), saturation=LogisticSaturation(), ) This creates: fourier_contribution as the unsummed Fourier basis contribution yearly_seasonality_contribution as the additive contribution to mu The prior for this built-in seasonality comes from model_config["gamma_fourier"].

Priors and Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Abacus uses model_config to control priors on the underlying PyMC variables. Transform priors can be configured either on the transform objects themselves or through their prefixed variable names in model_config. Where configuration lives Surface Use it for model_config Intercept, likelihood, controls, seasonality, Mundlak terms, time-varying config, and prefixed transform priors adstock=... and saturation=... Transform choice plus direct transform-prior overrides control_impacts and control_sign_policy Directional expectations for controls Default model_config PanelMMM.default_model_config is built from the current model state.

Panel Dimensions

Mon, 01 Jan 0001 00:00:00 +0000

Use dims when your dataset is a panel rather than a single timeseries. Examples of useful panel dimensions: geo brand market country For the input row layout, see Panel Data Layout. What dims does dims tells PanelMMM which extra categorical axes exist alongside date. With no extra dims, the model is indexed by: date channel optionally control With dims=("geo",), the model is indexed by:

Time-Varying Parameters

Mon, 01 Jan 0001 00:00:00 +0000

Abacus supports time-varying intercept and media effects through SoftPlusHSGP, a Hilbert Space Gaussian Process approximation. Two ways to enable time variation For both time_varying_intercept and time_varying_media, you can pass: True to use the config-driven default path a custom HSGPBase instance such as SoftPlusHSGP(...) Boolean mode The simplest entry point is a boolean flag:

Calibration

Mon, 01 Jan 0001 00:00:00 +0000

Calibration lets you add external evidence to a built PanelMMM. Abacus currently supports two retained calibration paths: lift-test measurements through add_lift_test_measurements(...) cost-per-target calibration through add_cost_per_target_calibration(...) General rule Both calibration methods operate on a built model, not a bare constructor. Typical sequence: mmm.build_model(X, y) # optional calibration step(s) here idata = mmm.fit(X, y) If you try to add calibration before the model graph exists, Abacus raises an error.