Installation

These instructions assume you are working from a local checkout of the Abacus repository.

Prerequisites

Recommended setup: Conda + editable install

This is the supported local development path for the repository.

conda env create -f environment.yml
conda activate abacus-dev
python3 -m pip install -e .

This gives you:

• the repo-managed development environment from environment.yml
• an editable install, so local code changes are picked up immediately

Minimal pip install from source

If you do not want the full Conda environment, you can still install Abacus directly from the repository root.

Standard install

python3 -m pip install .

Editable install

python3 -m pip install -e .

Use the editable install if you are changing code, configs, or docs locally.

Optional extras

Abacus defines a small set of optional extras in pyproject.toml.

If you created the environment from environment.yml, most development dependencies are already present.

The statistical scenario API does not require the planner extra. New library code should import scenario objects from abacus.scenarios. The experimental abacus-dashboard application is deprecated. Use the scenario Python API or CLI; no dashboard installation is required. Legacy app-layer paths under abacus.scenario_planner remain as advisory compatibility facades. Abacus does not vendor Dash, Plotly, or Flask dependencies.

Verify the install

A quick smoke check from the repository root:

python3 -c "from abacus.mmm.panel import PanelMMM; print(PanelMMM.__name__)"

For a real end-to-end verification path, use the repo smoke target:

make smoke_mmm

If you are working on the repo itself, the main local verification commands are:

make test
make verify_local
make verify_package

Runtime defaults for restricted environments

Some local runs need writable cache directories. If you hit PyTensor compiledir or cache-permission issues, export the same defaults used by the repo verification scripts:

export PYTENSOR_FLAGS="base_compiledir=/tmp/pytensor,linker=py"
export JAX_PLATFORMS=cpu
export XDG_CACHE_HOME=/tmp

Next steps

• Read Quickstart: Python API if you want to fit a model directly from pandas data.
• Read Quickstart: YAML Builder if you want configuration-driven model construction.
• Read Quickstart: Pipeline Runner if you want a full structured run with staged artefacts.

Quickstart: Python API

This page shows the fastest direct path from a pandas dataset to a fitted PanelMMM.

If you have not prepared your dataset yet, read Data Preparation first.

Load a dataset

The repository includes bundled demo datasets under data/demo/. The timeseries bundle is the simplest starting point because it has no extra panel dimensions.

import pandas as pd

dataset = pd.read_csv("data/demo/timeseries/dataset.csv")
dataset["date"] = pd.to_datetime(dataset["date"])

X = dataset.drop(columns=["revenue"])
y = dataset["revenue"].rename("revenue")

Construct PanelMMM

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

mmm = PanelMMM(
    date_column="date",
    target_column="revenue",
    channel_columns=[
        "channel_1",
        "channel_2",
        "channel_3",
        "channel_4",
        "channel_5",
        "channel_6",
    ],
    yearly_seasonality=2,
    adstock=GeometricAdstock(l_max=4),
    saturation=LogisticSaturation(),
)

This example uses a plain timeseries. If your dataset has panel dimensions such as geo or brand, add them with dims=(...) and keep those columns in X.

Fit the model

You can call fit() directly. If the model graph has not been built yet, Abacus builds it for you.

idata = mmm.fit(
    X,
    y,
    draws=200,
    tune=200,
    chains=2,
    cores=2,
    progressbar=False,
    compute_convergence_checks=False,
    random_seed=42,
)

fit() returns an arviz.InferenceData object and also stores it on the model instance as mmm.idata.

Prior and posterior predictive checks

You can sample prior predictive draws before fitting:

prior = mmm.sample_prior_predictive(
    X=X,
    y=y,
    samples=50,
    random_seed=42,
)

After fitting, you can sample posterior predictive draws:

post = mmm.sample_posterior_predictive(
    X=X,
    progressbar=False,
    random_seed=42,
)

By default, this also stores posterior predictive draws on mmm.idata.

When to call build_model()

Call build_model(X, y) explicitly when you want to inspect or modify the PyMC graph before sampling.

For example, you might build first so that you can add stored original-scale deterministics:

mmm.build_model(X, y)
mmm.add_original_scale_contribution_variable(
    var=["channel_contribution", "y"]
)

After that, fit the already-built model:

idata = mmm.fit(
    X,
    y,
    draws=200,
    tune=200,
    chains=2,
    cores=2,
    progressbar=False,
    compute_convergence_checks=False,
    random_seed=42,
)

Reusing a built or fitted model

An existing model graph can only be fitted with the data used to construct it. This applies to both fit() and approximate_fit(), including models restored with PanelMMM.load(). Equal copies of the training inputs are accepted; changed outcomes, predictors, dates or panel units raise ValueError before inference starts. Use a fresh model instance to fit a different dataset.

Abacus checks the retained training values and coordinates, not Python object identity. Mutating the original DataFrame or array after construction does not change the recorded training data. The check also rejects fitting after an in-place update of the graph’s training data. Posterior prediction clones the PanelMMM graph by default; keep that default if you intend to fit it again.

Building explicitly and then fitting identical data preserves additions to the graph, including calibration terms and extra deterministics. Abacus does not silently rebuild the graph when fitting inputs change.

Supply the real target when constructing a graph for prior predictive checks that you intend to fit later:

mmm.sample_prior_predictive(X=X, y=y, samples=100, random_seed=42)
idata = mmm.fit(X, y, random_seed=42)

Omitting y during prior construction creates a graph with zero targets. A later fit with different target values is rejected; construct a fresh instance for that fit.

This guard does not retrospectively validate saved results. If an earlier fit reused a graph with changed inputs, rerun it from a fresh instance.

Basic outputs

After fitting, common next steps are:

mmm.save("mmm.nc")
fig, axes = mmm.plot.posterior_predictive()

You can also inspect:

• mmm.posterior
• mmm.posterior_predictive
• mmm.summary
• mmm.diagnostics

Next steps

• Read Quickstart: YAML Builder if you want to move model configuration into YAML.
• Read Model Fitting for fitting, save/load, and predictive-check workflows in more detail.

Quickstart: YAML Builder

Use the YAML builder to create an in-memory PanelMMM from a model specification. It builds the PyMC graph; you then fit and predict in Python. For staged outputs and manifests, use the Pipeline Runner.

Complete Installation first. The example below uses small synthetic data and short chains to check execution. It does not establish convergence, parameter recovery or a suitable model for real data.

Create a builder configuration

Work in a new scratch directory, such as sandbox/yaml-quickstart/ within your checkout. Save this as model.yml in that directory:

data:
  date_column: date

target:
  column: revenue
  type: revenue

estimator:
  type: time_series

media:
  channels: [tv, search]
  adstock:
    type: geometric
    l_max: 4
  saturation:
    type: logistic

fit:
  draws: 50
  tune: 50
  chains: 2
  cores: 1
  random_seed: 42
  progressbar: false

This configuration accepts X and y from Python. The bundled data/demo/timeseries/config.yml is a runner configuration: it also contains diagnostics, validation, prior_sensitivity and ai_advisor. The public builder rejects those runner-only blocks. Use the runner for that file; do not pass it directly to build_mmm_from_yaml(...).

Build from synthetic data

Run these Python blocks in order from the directory containing model.yml:

from pathlib import Path

import numpy as np
import pandas as pd

from abacus.mmm.builders.yaml import build_mmm_from_yaml

rng = np.random.default_rng(42)
X = pd.DataFrame({
    "date": pd.date_range("2025-01-06", periods=24, freq="W-MON"),
    "tv": rng.uniform(1, 10, size=24),
    "search": rng.uniform(1, 5, size=24),
})
y = pd.Series(
    100 + 3 * X["tv"] + 2 * X["search"] + rng.normal(0, 1, size=24),
    name="revenue",
)
config_path = Path("model.yml")
mmm = build_mmm_from_yaml(config_path, X=X, y=y)

The result is a PanelMMM with a built graph. Keep the same training data for fitting; changing it after construction raises a data-identity error.

Fit and predict

fit(...) uses the sampler defaults in the YAML fit block:

idata = mmm.fit(X, y)
predictions = mmm.sample_posterior_predictive(
    X=X,
    random_seed=42,
    progressbar=False,
    extend_idata=False,
)
print(dict(predictions.sizes))

With this configuration, the returned dataset has 24 dates and 100 combined posterior samples (two chains of 50 draws). Sampling warnings and divergences can occur with such short chains. Do not interpret these smoke-run estimates. Before interpreting a real model, choose adequate sampling settings and assess Diagnostics.

Override configuration from Python

model_kwargs takes precedence over the translated YAML constructor arguments. For sampler_config, provide the complete mapping you want to use: it replaces the YAML sampler mapping at this boundary.

short_model = build_mmm_from_yaml(
    config_path,
    X=X,
    y=y,
    model_kwargs={
        "sampler_config": {
            "draws": 20,
            "tune": 20,
            "chains": 2,
            "cores": 1,
            "random_seed": 42,
            "progressbar": False,
        }
    },
)
short_idata = short_model.fit(X, y)

This second fit only checks the override path. It is not a sensitivity or convergence assessment.

Load your own data

Configured relative paths resolve from the YAML file’s directory. The builder normalises the configured date column. To fit after loading a CSV, load and split that data in Python too, then pass matching X and y to fit(...). See Input Data Requirements for index, missing-data and panel rules.

Optional builder blocks

Check Choose an Estimator before adapting this example to a panel. For the Python interfaces, see Builders and Pipeline.

Quickstart: Pipeline Runner

Use the pipeline runner when you want a full staged run instead of only an in-memory model fit.

The runner writes:

• a run manifest
• copied and resolved config files
• fitted model artefacts
• posterior predictive assessment outputs
• decomposition, diagnostics, and response-curve artefacts

Full bundled demo

From the repository root, run the complete demo with:

python3 runme.py --demo timeseries

Other bundled demos are:

• timeseries_controls
• geo_fe
• geo_cre
• geo_panel
• geo_brand_panel

timeseries and timeseries_controls use the released time_series estimator preset. geo_fe and geo_cre use the released one-unit FE and CRE presets. geo_panel and geo_brand_panel use the advanced dimensions.panel surface; they are not named RE, FE, or CRE estimators. The named RE preset remains release-gated. See the demo catalogue for the exact semantics and release status of each recipe.

List them explicitly with:

python3 runme.py --list-demos

runme.py is a convenience wrapper around the structured pipeline. It resolves the demo config under data/demo/<demo_name>/config.yml and runs the pipeline for you.

Run the named panel presets with:

python3 runme.py --demo geo_fe
python3 runme.py --demo geo_cre

Read Choose an Estimator before treating either recipe as the basis for a real model.

The timeseries demo requests four chains with 2,000 tuning and 3,000 retained draws per chain for Stage 20. Its enabled validation stage separately requests four chains with 2,000 tuning and 2,000 retained draws per chain. Explicit validation.sampler settings override main-fit CLI settings for that refit. make smoke_mmm launches this full demo without reducing either budget.

Bounded software smoke

Use this synthetic example to check execution with a small, explicit budget. Run the following from the repository root in the installed Abacus environment. It creates a separate scratch configuration and dataset, leaving the bundled demos unchanged. Repeating the setup overwrites these two scratch inputs; each pipeline execution creates a new run directory.

from pathlib import Path

import numpy as np
import pandas as pd
import yaml

workspace = Path("sandbox/runner-smoke")
workspace.mkdir(parents=True, exist_ok=True)
rng = np.random.default_rng(42)
data = pd.DataFrame({
    "date": pd.date_range("2024-01-01", periods=24, freq="W-MON"),
    "tv": rng.uniform(10, 100, 24),
    "search": rng.uniform(5, 50, 24),
})
data["revenue"] = 100 + 0.4 * data["tv"] + 0.8 * data["search"] + rng.normal(0, 2, 24)
data.to_csv(workspace / "data.csv", index=False)
config = {
    "data": {"dataset_path": "data.csv", "date_column": "date"},
    "target": {"column": "revenue", "type": "revenue"},
    "estimator": {"type": "time_series"},
    "media": {
        "channels": ["tv", "search"],
        "adstock": {"type": "geometric", "l_max": 4},
        "saturation": {"type": "logistic"},
    },
    "original_scale_vars": ["y", "channel_contribution"],
    "fit": {
        "draws": 20, "tune": 20, "chains": 2, "cores": 1,
        "random_seed": 42, "progressbar": False,
    },
    "validation": {"enabled": False},
}
(workspace / "config.yml").write_text(yaml.safe_dump(config), encoding="utf-8")

Then run:

python3 -m abacus.pipeline.runner \
  --config sandbox/runner-smoke/config.yml \
  --output-dir sandbox/runner-smoke/results \
  --run-name execution_check \
  --prior-samples 5 \
  --random-seed 42 \
  --curve-samples 10 \
  --curve-points 10

Stage 20 uses two chains, each with 20 tuning and 20 retained draws, on one core. Stage 35 performs no fit: run_manifest.json must record validation as skipped, and no holdout scoring artefacts are expected. Prior sensitivity, both AI stages and optimisation are also skipped because their configuration blocks are absent. The run should complete through Stage 80’s evidence inventory. The resolved main-fit settings are in 00_run_metadata/config.resolved.yaml.

These small sampling budgets check software execution only. Warnings or retained divergences can occur; do not interpret these fitted estimates. To exercise holdout scoring, prepare a separate config with explicit budgets for both fits and follow Blocked Holdout Validation. A skipped validation stage is not evidence of predictive performance.

Run the pipeline from Python

The direct Python API below runs the bundled geo-panel model. It is separate from the bounded synthetic smoke above. Check the selected YAML’s validation budget before running it:

from pathlib import Path

from abacus.pipeline import PipelineRunConfig, run_pipeline

result = run_pipeline(
    PipelineRunConfig(
        config_path=Path("data/demo/geo_panel/config.yml"),
        output_dir=Path("results"),
        run_name="geo_panel_quickstart",
        prior_samples=10,
        draws=200,
        tune=200,
        chains=2,
        cores=2,
        random_seed=42,
        curve_samples=50,
        curve_points=50,
    )
)

print(result.run_dir)
print(result.manifest_path)

If the YAML config already contains data.dataset_path, you do not need to pass dataset_path again.

Run the thin CLI directly

The pipeline also exposes a thin CLI in abacus.pipeline.runner:

python3 -m abacus.pipeline.runner \
  --config data/demo/geo_panel/config.yml \
  --output-dir results \
  --run-name geo_panel_quickstart \
  --prior-samples 10 \
  --draws 200 \
  --tune 200 \
  --chains 2 \
  --cores 2 \
  --random-seed 42 \
  --curve-samples 50 \
  --curve-points 50

The CLI prints the final run directory and manifest when the pipeline completes. When the run manifest records them, it also prints paths to the estimator summary, diagnostics summary, and interpretation report. These paths are relative to the run directory.

Pipeline completion means that the configured stages finished. It does not mean that the fitted model passed its diagnostic gates or is suitable for interpretation. Review the listed diagnostic and interpretation artefacts before using model outputs.

Override data paths

Use one of these patterns:

Configured relative paths are resolved relative to the YAML config directory.

If you want Stage 50 to use different warn/fail cutoffs, add a runner-only diagnostics.thresholds block to the YAML. See YAML Configuration.

What you get back

run_pipeline(...) returns a PipelineRunResult with:

• run_dir
• manifest_path

The runner creates all stage directories up front, including those for skipped stages. Use the manifest to distinguish completed, skipped and failed work. See the canonical stage sequence and artefact locations, including Stage 80’s evidence inventory.

Named estimator runs also record their resolved contract in 00_run_metadata/estimator_summary.txt and 00_run_metadata/estimator_manifest.yaml. FE writes its transformed within-design screen under 10_pre_diagnostics. CRE writes structural and reference summary-basis screens under 10_pre_diagnostics, a bounded post-fit screen under 20_model_fit, and separate CRE-adjustment decomposition evidence under 40_decomposition.

60_response_curves now includes three complementary curve families:

• saturation-only transformation artefacts
• forward-pass direct contribution artefacts built from scaled observed history
• adstock carryover artefacts

When to use the runner

Choose the runner when you want:

• a reproducible run directory on disk
• structured metadata and manifest files
• staged artefacts for diagnostics and reporting
• a config-driven workflow for repeated runs

If you only need to fit a model interactively in a notebook or script, start with Quickstart: Python API or Quickstart: YAML Builder.

Input Data Requirements

Use this page together with Panel Data Layout and Scaling and Preprocessing when you prepare a dataset for PanelMMM.

Core contract

For direct Python use, PanelMMM expects:

• X as a pandas.DataFrame
• y as a row-aligned pandas.Series, or a one-dimensional NumPy array of the same length as X

X must contain the date column, all media columns, and any configured control_columns or dims columns. y carries only the target values.

X and y

When you call fit(X, y) or build_model(X, y):

• Keep the target out of X.
• Keep X and y row-aligned.
• If both are pandas objects, keep the same index on both. The shared regression builder checks index equality before fitting.
• If you pass y as a NumPy array, its length must match len(X).
• For panel models, each date_column + dims combination must appear exactly once. Duplicate rows are rejected.

Abacus uses target_column as the target name throughout the panel reshape. A Series name is normalised internally without changing the caller’s Series.

Date column

date_column is required in X.

Abacus expects calendar dates, not integer date codes. In practice:

• Use datetime64[ns] where possible.
• Parse string dates with pd.to_datetime(...) before fitting when you use the Python API.
• Do not rely on numeric date values such as 0, 1, 2. Pandas can interpret them as offsets from the Unix epoch, which is usually not what you want.

The YAML builder normalises X[date_column] with pd.to_datetime(...) after loading the dataset. Direct Python use does not add an equivalent preprocessing step for you.

Channel columns

channel_columns is a required constructor argument and must be a non-empty list.

Each listed channel:

• must be present in X
• must be fully observed for every row you pass into fit or posterior prediction; Abacus does not silently convert missing channel values to zero
• should represent the raw media variable that you want the adstock and saturation transformations to consume

Target column

target_column names the dependent variable. It defaults to "y", but you can set a different name such as "sales" or "conversions".

For direct Python use:

• pass the target as y
• keep the target fully observed; missing target values are rejected rather than zero-filled

For combined-file YAML or pipeline flows:

• keep the target column in the source dataset
• Abacus splits it out of the combined dataset before fitting

Control columns

control_columns is optional.

If you configure it, every listed control column must be present in X. Controls stay in the design matrix as separate regressors; they are not part of y.

Like channels, configured controls must be fully observed for every row passed into fit or posterior prediction.

Abacus does not automatically scale controls. See Scaling and Preprocessing.

Panel dimensions with dims

dims is optional. Use it when you want a panel model, for example by geo, brand, or market.

If you set dims=("geo", "brand"):

• X must contain geo and brand columns
• each row in X represents one date + geo + brand observation
• each new date must include every fitted panel slice when you later call posterior-predictive methods with new data

Do not use reserved internal names in dims:

• date
• channel
• control
• fourier_mode

For row layout and rectangularity guidance, see Panel Data Layout.

Supported shapes and alignment

Abacus also has an internal alignment helper that can work with a MultiIndex target Series indexed by [date_column, *dims], but that is mainly used in fit-data rebuild and load flows. For normal fitting, keep y row-aligned with X.

Python example

import pandas as pd

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

dataset = pd.DataFrame(
    {
        "date": pd.to_datetime(
            ["2025-01-06", "2025-01-06", "2025-01-13", "2025-01-13"]
        ),
        "geo": ["UK", "US", "UK", "US"],
        "tv": [120.0, 150.0, 125.0, 152.0],
        "search": [40.0, 55.0, 42.0, 58.0],
        "price_index": [1.02, 0.99, 1.01, 1.00],
        "sales": [820.0, 910.0, 835.0, 925.0],
    }
)

X = dataset.drop(columns=["sales"])
y = dataset["sales"].rename("sales")

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

mmm.fit(X, y)

YAML note

If you use a combined dataset in YAML, the file at data.dataset_path must contain every configured column:

• date_column
• every entry in channel_columns
• every entry in control_columns, if any
• every entry in dims, if any
• target_column

Example:

data:
  dataset_path: panel_dataset.csv
  date_column: date

target:
  column: sales
  type: revenue

dimensions:
  panel: [geo]

media:
  channels: [tv, search]
  controls: [price_index]
  adstock:
    type: geometric
    l_max: 8
  saturation:
    type: logistic

Target row alignment

For PanelMMM.build_model(X, y) and fitting, a one-dimensional NumPy target is positional: its length must equal len(X), and values follow X’s row order regardless of whether X uses a RangeIndex, an offset index or a DatetimeIndex. A pandas Series target must have exactly the same row index as X. Prepared observations and retained fitting provenance use the same alignment rule.

Common pitfalls

• Missing date_column, channel, control, or dimension columns in X
• Passing pandas X and y with different indexes
• Passing a NumPy y with a different length from X
• Passing duplicate panel rows or incomplete panel slices for a given date
• Passing missing observed channel, control, or target values and expecting Abacus to treat them as structural zeroes
• Expecting the YAML builder or pipeline to find a target column that is not present in the combined dataset
• Leaving date values as numeric codes instead of normalising them first

Panel Data Layout

This page explains how PanelMMM expects panel rows to be organised in X. For the column-level contract, see Input Data Requirements.

What “panel” means in Abacus

In Abacus, a panel dataset repeats the same time axis across one or more categorical dimensions in dims.

The released FE and CRE presets are more specific one-unit panel contracts. They declare estimator.type: fe or estimator.type: cre and estimator.unit: <column> instead of dimensions.panel. Both require the same date set for every unit, so their released surfaces use a balanced unit-date panel. See Choose an Estimator, Fixed-effects Estimator, and Correlated-random-effects Estimator.

Each row represents:

• one date_column value
• one combination of dims values, if any
• one set of channel and optional control values for that slice

With no extra panel dims, each date appears once. With dims=("geo",), each date appears once per geo. With dims=("geo", "brand"), each date appears once per geo + brand combination.

How dims work

Pass panel dimensions when you construct the model:

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

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

dims columns stay in X. They are not moved into y.

Abacus reserves these names for internal coordinates, so do not use them in dims:

• date
• channel
• control
• fourier_mode

No extra panel dims

If dims=(), X should have one row per date.

Internally, Abacus reshapes this into:

• channels: (date, channel)
• target: (date,)
• controls, if present: (date, control)

Single panel dim example: geo

If dims=("geo",), each date should appear once for each geo value.

Internally, Abacus reshapes this into:

• channels: (date, geo, channel)
• target: (date, geo)
• controls, if present: (date, geo, control)

For a named FE or CRE model, keep the same row layout but declare the unit through estimator.unit rather than dimensions.panel:

estimator:
  type: fe  # or cre
  unit: geo

Do not declare both estimator and dimensions.panel. Abacus rejects the mixed configuration.

Multiple panel dims example: geo and brand

If dims=("geo", "brand"), each row identifies one date, one geo, and one brand.

import pandas as pd

X = pd.DataFrame(
    {
        "date": pd.to_datetime(
            [
                "2025-01-06",
                "2025-01-06",
                "2025-01-06",
                "2025-01-06",
                "2025-01-13",
                "2025-01-13",
                "2025-01-13",
                "2025-01-13",
            ]
        ),
        "geo": ["UK", "UK", "US", "US", "UK", "UK", "US", "US"],
        "brand": ["A", "B", "A", "B", "A", "B", "A", "B"],
        "tv": [80.0, 55.0, 92.0, 60.0, 82.0, 58.0, 95.0, 63.0],
        "search": [20.0, 18.0, 24.0, 19.0, 21.0, 18.5, 25.0, 20.0],
    }
)

y = pd.Series(
    [510.0, 370.0, 590.0, 405.0, 520.0, 380.0, 605.0, 418.0],
    name="sales",
)

For a rectangular panel, the row count is:

n_dates * n_geo * n_brand

Internal reshape

Abacus converts the pandas inputs into xarray datasets before building the PyMC model.

The channel and control dimensions come from the configured column names, not from row values.

Rectangularity, duplicates, and missing rows

Abacus builds xarray coordinates from the unique values it sees in:

• date_column
• each configured dimension column
• the configured channel or control names

That has three practical consequences:

• Keep the panel rectangular. Provide one row for every expected date_column + dims combination.
• Use explicit zeroes for structural no-spend or no-activity rows.
• Keep declared channel, control, and target values observed within those rows. Abacus rejects missing metric cells instead of silently converting them to zeroes.
• Do not use missing rows to mean “unknown”. Abacus validates panel shape before reshape and raises an error if panel cells are missing.

Abacus also requires each date_column + dims combination to appear exactly once. It does not aggregate duplicates for you. If you have duplicate rows, deduplicate or aggregate them before fitting or posterior prediction.

Sorting and uniqueness

Sort your data before fitting:

• first by date_column
• then by each entry in dims

Abacus keeps dates in the order they appear in X, and time-varying features infer time resolution from adjacent rows. A sorted dataset makes the time axis deterministic and easier to reason about.

Also make sure that each date_column + dims combination appears once in the prepared table, and that every expected panel slice is present for every date.

DataFrame versus MultiIndex handling

For normal fitting:

• use a regular DataFrame for X
• keep date_column and any dims as columns in that DataFrame
• use a row-aligned Series for y

Abacus does have internal helpers that can align a MultiIndex target Series indexed by [date_column, *dims], but that is not the main user-facing data preparation pattern for fit().

Practical checklist

• One row per date_column + dims combination
• No duplicate rows for the same panel cell
• Same set of dates for every panel slice
• Explicit zeroes for true zero activity
• No missing observed channel, control, or target values
• Sorted rows before fitting
• For FE or CRE, exactly one declared unit column with at least two units and two dates
• For FE or CRE, non-zero within-unit temporal variation in the target and each estimable transformed predictor
• For CRE, enough units to estimate the active centred summaries while retaining at least two between-unit residual degrees of freedom

For scaling choices once the layout is correct, see Scaling and Preprocessing.

Scaling and Preprocessing

Abacus scales channels and the target automatically before it builds the PyMC graph for PanelMMM. This page explains what is scaled, how the Scaling configuration works, and what you still need to preprocess yourself.

What Abacus scales automatically

Abacus computes scales from the reshaped xarray dataset immediately before model construction.

Abacus stores the resulting scalers in the model as xarray data:

• _target scaler data in model.scalers["_target"]
• _channel scaler data in model.scalers["_channel"]

Default behaviour

If you do not pass scaling, PanelMMM uses:

Scaling(
    target=VariableScaling(method="max", dims=dims),
    channel=VariableScaling(method="max", dims=dims),
)

This means:

• the target is divided by the maximum over date and all configured dims
• each channel is divided by its maximum over date and all configured dims

With no extra panel dims:

• target_scale is a scalar
• channel_scale has dimension channel

With dims=("geo",) and the default scaling:

• target_scale is still a scalar, because scaling reduces over both date and geo
• channel_scale still has dimension channel, so each channel is pooled across all geos

If you want per-panel scales instead of pooled scales, set dims=() inside the relevant VariableScaling. See Dimension semantics.

Scaling and VariableScaling

Use abacus.mmm.scaling.Scaling and abacus.mmm.scaling.VariableScaling to control automatic scaling.

Rules enforced by the implementation:

• date is always assumed in the reduction and must not be listed in VariableScaling.dims.
• Duplicate scaling dims are not allowed.
• Target scaling dims must come from the model dims.
• Channel scaling dims must come from the model dims, with optional inclusion of channel.

You can pass either:

• a Scaling object
• a plain dictionary with target and channel keys

If the dictionary omits one side, Abacus fills the missing target or channel rule with the default method="max", dims=dims configuration.

Dimension semantics

VariableScaling.dims tells Abacus which dimensions to reduce across in addition to date. It does not tell Abacus which dimensions to keep.

Assume a model with dims=("geo",) so channel data has dimensions (date, geo, channel) and target data has dimensions (date, geo).

Python example

This example keeps separate scales for each geo by reducing only over date:

from abacus.mmm import GeometricAdstock, LogisticSaturation
from abacus.mmm.panel import PanelMMM
from abacus.mmm.scaling import Scaling, VariableScaling

mmm = PanelMMM(
    date_column="date",
    channel_columns=["tv", "search"],
    target_column="sales",
    dims=("geo",),
    scaling=Scaling(
        target=VariableScaling(method="mean", dims=()),
        channel=VariableScaling(method="max", dims=()),
    ),
    adstock=GeometricAdstock(l_max=8),
    saturation=LogisticSaturation(),
)

In that configuration:

• the target is divided by the per-geo mean over time
• each channel is divided by the per-geo, per-channel maximum over time

YAML example

The YAML builder accepts the same structure through a top-level scaling block:

data:
  date_column: date

target:
  column: y
  type: revenue

dimensions:
  panel: [market]

media:
  channels: [channel_1, channel_2]
  adstock:
    type: geometric
    l_max: 8
  saturation:
    type: logistic

scaling:
  target:
    method: max
    dims: []
  channels:
    method: max
    dims: [market]

In this example:

• target is scaled separately for each market
• channel is scaled across date and market, leaving one scale per channel

Original units versus model scale

The model is fit on scaled target and channel data.

That affects downstream interpretation:

• posterior likelihood and many contribution variables live in scaled target space
• channel inputs are transformed after scaling, not in raw units

If you want stored deterministics in original target units, add them explicitly after build_model(...):

mmm.add_original_scale_contribution_variable(
    var=["channel_contribution", "y"]
)

The YAML builder supports the same workflow through original_scale_vars:

original_scale_vars:
  - channel_contribution
  - y

original_scale_vars adds extra original-scale deterministic variables. It does not change how the model is fit.

What Abacus does not preprocess for you

Abacus does not automatically:

• scale controls
• impute missing data in a domain-aware way
• reinterpret missing observed channel, control, or target values as zeroes
• sort the dataset for you
• repair non-rectangular panel layouts
• tolerate duplicate panel rows or incomplete panel slices
• coerce Python-API dates to datetimes before fitting

Practical preprocessing advice

Before fitting:

• normalise date_column with pd.to_datetime(...)
• sort by date_column and then by dims
• make panel gaps explicit instead of leaving missing rows
• ensure every date_column + dims panel cell appears exactly once
• impute missing observed channel, control, and target values before fitting or posterior prediction instead of relying on implicit zero-fill
• decide whether controls should be centred, standardised, log-transformed, or otherwise prepared before they go into control_columns
• choose scaling dims deliberately instead of relying on the default when you use panel data

Common pitfalls

• Expecting the default scaling to be per-group when it actually pools across the configured panel dims
• Adding date to VariableScaling.dims; Abacus rejects this
• Forgetting that controls are left on their original scale
• Treating VariableScaling.dims as dimensions to keep rather than dimensions to reduce across
• Assuming original_scale_vars changes fitting scale rather than adding extra outputs

For the input table shape that scaling operates on, see Panel Data Layout.

Model Overview

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. Named FE and CRE presets use specialised likelihoods and restrictions; read Choose an Estimator before applying this general component description to them.

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.

What is scaled and what is not

Before the PyMC graph is built:

• channel data is scaled according to Scaling.channel
• the target is scaled according to Scaling.target
• controls are not scaled automatically

That means media and target priors operate on the model scale, not directly on the original business units. For the scaling surface, see Scaling and Preprocessing.

Model components

Abacus also adds total_media_contribution_original_scale automatically as a deterministic on the original target scale.

Media path

Each channel column goes through the configured media transform path:

1. scale channel input
2. apply adstock and saturation through forward_pass(...)
3. optionally apply a time-varying media multiplier
4. contribute the result through channel_contribution

See Adstock and Saturation and Time-Varying Parameters.

Controls

Controls enter the model as a separate additive term:

control_contribution = control_data * gamma_control

Use controls for non-media regressors such as price, macro indicators, or competitor measures. Controls are configured with control_columns and use gamma_control priors from model_config.

Panel dimensions

dims adds extra indexing axes such as geo, brand, or market.

With dims=("geo",), the model is indexed over date and geo. With dims=("geo", "brand"), it is indexed over date, geo, and brand.

Abacus does not automatically add hierarchical pooling just because dims is set. By default, parameters are indexed over the configured panel coordinates. If you want hierarchical shrinkage across those coordinates, encode it in the priors you pass to transforms or model_config.

See Panel Dimensions.

Optional components

This table describes the ordinary PanelMMM component surface. The released FE and CRE presets deliberately reject several optional components and downstream operations. Their estimator pages are authoritative for those boundaries.

What target_type changes

target_type is semantic metadata, not a different likelihood family.

It affects downstream reporting such as the default efficiency metric label:

• "revenue" -> ROAS
• "conversion" -> CPA

It does not change the fitted functional form on its own.

Python example

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

mmm = PanelMMM(
    date_column="date",
    target_column="sales",
    channel_columns=["tv", "search"],
    control_columns=["price_index"],
    dims=("geo",),
    yearly_seasonality=2,
    adstock=GeometricAdstock(l_max=8),
    saturation=LogisticSaturation(),
)

This specification gives you:

• an intercept
• transformed media contributions for tv and search
• a control contribution for price_index
• yearly Fourier seasonality
• a panel axis over geo

Next steps

• Read Adstock and Saturation for the media transform choices.
• Read Priors and Configuration for the prior surface.
• Read Choose an Estimator before choosing an aggregate time-series, FE, or CRE contract.

Adstock and Saturation

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.

Adstock options

PanelMMM accepts any AdstockTransformation. The built-in options include:

All adstock transforms also take:

• l_max: maximum lag
• normalize: whether the carryover weights are normalised
• mode: convolution mode

Saturation options

PanelMMM accepts any SaturationTransformation. Common built-ins include:

Default prior dims

When you pass a transform to PanelMMM, Abacus assigns default prior dims for any transform prior that does not already have explicit dims:

• adstock priors default to (*dims, "channel")
• saturation priors default to (*dims, "channel")

If you want a different structure, set the prior dims explicitly on the transform.

Configure transforms in Python

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

mmm = PanelMMM(
    date_column="date",
    channel_columns=["tv", "search"],
    target_column="sales",
    adstock=GeometricAdstock(l_max=8),
    saturation=LogisticSaturation(),
    adstock_first=True,
)

Example with more customised transforms:

from pymc_extras.prior import Prior

from abacus.mmm import MichaelisMentenSaturation, WeibullCDFAdstock

adstock = WeibullCDFAdstock(
    l_max=12,
    priors={
        "lam": Prior("Gamma", mu=2, sigma=1, dims=("geo", "channel")),
        "k": Prior("Gamma", mu=3, sigma=1, dims=("geo", "channel")),
    },
)

saturation = MichaelisMentenSaturation(
    priors={
        "alpha": Prior("Gamma", mu=2, sigma=1, dims=("geo", "channel")),
        "lam": Prior("HalfNormal", sigma=1, dims="geo"),
    }
)

Configure transforms in YAML

data:
  date_column: date

target:
  column: sales
  type: revenue

media:
  channels: [tv, search]
  adstock:
    type: geometric
    l_max: 8
  saturation:
    type: logistic

Override transform priors through priors

Transform priors also appear in model_config under prefixed variable names. For example:

• adstock_alpha
• adstock_lam
• adstock_k
• saturation_lam
• saturation_beta

That means you can override transform priors centrally through the top-level priors if you prefer. See Priors and Configuration.

Choose the composition order

adstock_first is part of the model specification, not a plotting choice.

The current public YAML schema does not expose adstock_first; it uses the library default. If you need to change the composition order, use the Python API.

Use adstock_first=True when you want the model to interpret carryover before diminishing returns. Use False when you want each period’s spend to saturate before the carryover step.

The code path is explicit:

• True -> saturation(adstock(x))
• False -> adstock(saturation(x))

Common pitfalls

• Forgetting that l_max is required for adstock classes
• Assuming dims automatically change transform priors even when you have already set explicit incompatible dims on the transform
• Using adstock_first=False without a substantive reason
• Treating transform priors as if they were on original business units rather than the model scale

Next steps

• Read Priors and Configuration to control the prior surface.
• Read Time-Varying Parameters if you want media contributions to vary over time.

Seasonality and Trends

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=<int> 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"].

What yearly_seasonality means

yearly_seasonality is the Fourier order passed to YearlyFourier.

It must be a positive integer. Abacus validates this at construction time.

Custom additive effects

For anything beyond built-in yearly seasonality, use mu_effects.

Each effect must add a tensor with dims:

("date", *dims)

Abacus ships three retained additive-effect types:

FourierEffect

FourierEffect wraps a FourierBase implementation such as:

• YearlyFourier
• MonthlyFourier
• WeeklyFourier

Example:

from abacus.mmm.additive_effect import FourierEffect
from abacus.mmm.fourier import WeeklyFourier

mmm.mu_effects.append(
    FourierEffect(
        fourier=WeeklyFourier(n_order=3, prefix="weekly_fourier")
    )
)

LinearTrendEffect

LinearTrendEffect wraps LinearTrend, which models piecewise linear trend changes through changepoints.

Example:

from abacus.mmm import LinearTrend
from abacus.mmm.additive_effect import LinearTrendEffect

mmm.mu_effects.append(
    LinearTrendEffect(
        trend=LinearTrend(
            n_changepoints=8,
            include_intercept=False,
            dims=("geo",),
        ),
        prefix="trend",
    )
)

Events

For events, the retained public surface on PanelMMM is add_events(...).

Example:

import pandas as pd

from pymc_extras.prior import Prior

from abacus.mmm.events import EventEffect, GaussianBasis

df_events = pd.DataFrame(
    {
        "name": ["promo", "launch"],
        "start_date": pd.to_datetime(["2025-02-01", "2025-03-10"]),
        "end_date": pd.to_datetime(["2025-02-07", "2025-03-14"]),
    }
)

effect = EventEffect(
    basis=GaussianBasis(
        priors={"sigma": Prior("Gamma", mu=7, sigma=1, dims="event")}
    ),
    effect_size=Prior("Normal", mu=0, sigma=1, dims="event"),
    dims=("event",),
)

mmm.add_events(
    df_events=df_events,
    prefix="event",
    effect=effect,
)

The event effect dims must include the event prefix plus the model dims.

When to register effects

Add custom effects before you build or fit the model.

That applies to:

• mmm.mu_effects.append(...)
• mmm.add_events(...)

If you build the model first and only then append effects, those new terms are not part of the existing graph.

YAML effects

The YAML builder supports top-level effects: entries. Example:

effects:
  - type: linear_trend
    prefix: trend
    n_changepoints: 8
    include_intercept: false
  - type: weekly_fourier
    order: 3
    prefix: weekly_fourier

The builder appends these effects before calling build_model(...).

Choosing between built-in and custom seasonality

Use yearly_seasonality when you need a compact built-in annual effect.

Use FourierEffect when you need:

• weekly seasonality
• monthly seasonality
• multiple seasonal effects together
• custom Fourier prefixes or priors

Common pitfalls

• Adding effects after the model has already been built
• Using event effect dims that do not include the required prefix
• Treating yearly_seasonality and a custom yearly Fourier effect as if they were separate concepts when they are both additive seasonal terms

Next steps

• Read Time-Varying Parameters if you want trend or media behaviour to vary smoothly over time.
• Read Calibration if you want to constrain the specification with external measurements.

Priors and Configuration

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

Default model_config

PanelMMM.default_model_config is built from the current model state.

The default keys are:

Abacus also merges in the transform-specific config exposed by the selected adstock and saturation objects.

Configure priors in Python

Use pymc_extras.prior.Prior objects when you want explicit control:

from pymc_extras.prior import Prior

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

model_config = {
    "intercept": Prior("Normal", mu=0, sigma=1, dims=("geo",)),
    "likelihood": Prior(
        "Normal",
        sigma=Prior("HalfNormal", sigma=1.5, dims=("geo",)),
        dims=("date", "geo"),
    ),
    "gamma_control": Prior("Normal", mu=0, sigma=1, dims=("geo", "control")),
    "saturation_lam": Prior("Gamma", alpha=3, beta=1, dims=("geo", "channel")),
}

mmm = PanelMMM(
    date_column="date",
    target_column="sales",
    channel_columns=["tv", "search"],
    control_columns=["price_index"],
    dims=("geo",),
    adstock=GeometricAdstock(l_max=8),
    saturation=LogisticSaturation(),
    model_config=model_config,
)

Configure priors in YAML

YAML config can express the same priors as serialised distribution mappings:

data:
  date_column: date

target:
  column: sales
  type: revenue

dimensions:
  panel: [geo]

media:
  channels: [tv, search]
  adstock:
    type: geometric
    l_max: 8
  saturation:
    type: logistic

priors:
  intercept:
    distribution: Normal
    mu: 0
    sigma: 1
    dims: ["geo"]
  likelihood:
    distribution: Normal
    sigma:
      distribution: HalfNormal
      sigma: 1.5
      dims: ["geo"]
    dims: ["date", "geo"]
  saturation_lam:
    distribution: Gamma
    alpha: 3
    beta: 1
    dims: ["geo", "channel"]

Abacus parses these mappings into runtime Prior or HSGPKwargs objects.

Transform priors and prefixed names

Transform parameters appear in the model under prefixed variable names.

Examples:

• adstock alpha -> adstock_alpha
• saturation lam -> saturation_lam
• saturation beta -> saturation_beta

So you can override transform priors in either of these ways:

1. pass priors={...} to the transform object
2. override the prefixed variable in model_config

Use one style consistently within a project if you want the configuration to be easy to read.

Directional control priors

Controls are the right place for exogenous drivers whose effect may be negative, such as competitor spend, competitor price pressure, or supply-side disruptions. By default, control coefficients remain unrestricted.

You can declare expected control directions with:

• control_impacts
• control_sign_policy

Allowed impact values:

• positive
• negative
• unrestricted

Allowed policies:

• soft: bias the prior toward the expected sign
• strict: use a sign-constrained prior

Python example

mmm = PanelMMM(
    date_column="date",
    channel_columns=["tv", "search"],
    control_columns=["competitor_spend", "price_index"],
    control_impacts={
        "competitor_spend": "negative",
        "price_index": "negative",
    },
    control_sign_policy="strict",
    adstock=GeometricAdstock(l_max=8),
    saturation=LogisticSaturation(),
)

YAML note

The current public YAML schema does not expose control_impacts or control_sign_policy. If you need directional control settings today, use the Python API for that part of the specification.

Constraints for directional controls

When control_impacts is configured, Abacus expects:

• gamma_control and gamma_control_mundlak to be Normal or TruncatedNormal
• scalar numeric mu and sigma values for those priors
• the prior dims to include "control"

If you violate those assumptions, model build fails with a validation error.

Time-varying configuration keys

When you enable a boolean time-varying effect, Abacus uses these model_config keys:

• intercept_tvp_config
• media_tvp_config

Those keys can be:

• an HSGPKwargs instance
• a dict with HSGPKwargs fields
• a dict in SoftPlusHSGP.parameterize_from_data(...) style, such as {"ls_lower": 1, "ls_upper": 10}

See Time-Varying Parameters.

Important scope note

Directional control priors apply to control_columns, not channel_columns. Media channels are modelled through the adstock and saturation path.

If you need full manual control over the control prior, override gamma_control and gamma_control_mundlak directly in model_config.

Common pitfalls

• Putting control priors on media variables instead of using transform priors
• Forgetting the prefixed transform variable names in model_config
• Assuming dims automatically create hierarchical priors
• Using directional control priors with incompatible gamma_control distributions

Next steps

• Read Adstock and Saturation for transform choices.
• Read Panel Dimensions if your priors need panel-aware dims.

Panel Dimensions

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:

• date
• geo
• channel
• optionally control

With dims=("geo", "brand"), it is indexed by:

• date
• geo
• brand
• channel
• optionally control

What changes inside the model

Setting dims changes the coordinates and parameter shapes used in the PyMC graph.

Reserved names

Do not use these names in dims:

• date
• channel
• control
• fourier_mode

Abacus rejects them because they are reserved for internal coordinates.

dims does not imply automatic pooling

This is the most important modelling point.

By default, dims gives you parameters indexed by the panel coordinates, but not automatic hierarchical shrinkage across those coordinates.

For example:

• the default intercept prior is Normal(..., dims=dims)
• transform priors default to (*dims, "channel")
• control coefficients default to (*dims, "control")

Those defaults create per-slice parameters. If you want hierarchical pooling across geo, brand, or another dimension, you need to encode that in the priors you supply.

Example: independent panel slices

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

With this specification, the default priors are geo-indexed, but not hierarchical by default.

Example: explicit hierarchical prior

If you want hierarchical structure, define it in the prior itself.

from pymc_extras.prior import Prior

model_config = {
    "intercept": Prior(
        "Normal",
        mu=0,
        sigma=Prior("HalfNormal", sigma=0.3),
        dims="geo",
    ),
}

You can do the same for transform priors and additive effects.

Legacy Mundlak adjustment and panel dimensions

use_mundlak_cre=True only makes sense when you have at least one panel dim. Abacus enforces that. This low-level surface is not the named CRE estimator preset, and its coefficients do not by themselves identify confounding or establish causal effects.

When enabled, Abacus builds extra correlated-random-effects terms from training period means:

• channel_mundlak_contribution
• control_mundlak_contribution
• mundlak_contribution

These terms live on the panel coordinates defined by dims.

Custom HSGP dims

If you use a custom SoftPlusHSGP for time-varying effects, its dims must be compatible with the panel structure.

Examples:

• no extra dims: ("date",) or ("date", "channel") for media
• dims=("geo",): ("date", "geo") or ("date", "geo", "channel") for media

See Time-Varying Parameters.

YAML example

data:
  date_column: date

target:
  column: sales
  type: revenue

dimensions:
  panel: [geo, brand]

media:
  channels: [tv, search]
  adstock:
    type: geometric
    l_max: 8
  saturation:
    type: logistic

Your dataset must then contain both geo and brand columns.

Common pitfalls

• Using reserved names in dims
• Assuming dims implies automatic partial pooling
• Enabling use_mundlak_cre with no panel dimensions
• Forgetting that every date + dims combination must be present in the data

Next steps

• Read Priors and Configuration to encode hierarchical priors explicitly.
• Read Panel Data Layout for the required input shape.

Time-Varying Parameters

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:

mmm = PanelMMM(
    date_column="date",
    target_column="sales",
    channel_columns=["tv", "search"],
    adstock=GeometricAdstock(l_max=8),
    saturation=LogisticSaturation(),
    time_varying_intercept=True,
    time_varying_media=True,
)

When you do this, Abacus builds a SoftPlusHSGP internally from:

• model_config["intercept_tvp_config"]
• model_config["media_tvp_config"]

The default config keys are HSGPKwargs with:

• m=200
• L=None
• eta_lam=1
• ls_mu=5
• ls_sigma=10
• cov_func=None

What the boolean defaults mean

With boolean mode:

• time_varying_intercept=True creates intercept_latent_process over ("date", *dims)
• time_varying_media=True creates media_temporal_latent_multiplier over ("date", *dims)

That second point matters:

boolean time_varying_media=True gives you one shared temporal multiplier per panel slice, not a different time-varying multiplier per channel

If you want channel-specific time variation, pass a custom HSGP with channel in its dims.

Custom SoftPlusHSGP

Use a custom HSGP instance when you need precise control over dims, covariance, or priors.

Example: channel-specific time-varying media in a simple timeseries model.

import numpy as np

from abacus.mmm import SoftPlusHSGP

n_dates = X["date"].nunique()

media_hsgp = SoftPlusHSGP.parameterize_from_data(
    X=np.arange(n_dates),
    dims=("date", "channel"),
    cov_func="matern32",
)

mmm = PanelMMM(
    date_column="date",
    target_column="sales",
    channel_columns=["tv", "search"],
    adstock=GeometricAdstock(l_max=8),
    saturation=LogisticSaturation(),
    time_varying_media=media_hsgp,
)

For a panel model with dims=("geo",), valid media HSGP dims include:

• ("date", "geo")
• ("date", "geo", "channel")

For the intercept, the custom dims should align with the target axes, typically ("date",) or ("date", *dims).

Supported covariance choices

For SoftPlusHSGP.parameterize_from_data(...), the supported covariance keywords are:

• "expquad"
• "matern32"
• "matern52"

Config formats for boolean mode

The *_tvp_config entries in model_config support two formats.

HSGPKwargs style

from abacus.hsgp_kwargs import HSGPKwargs

model_config = {
    "intercept_tvp_config": HSGPKwargs(
        m=50,
        L=None,
        eta_lam=1.0,
        ls_mu=5.0,
        ls_sigma=10.0,
        cov_func=None,
    )
}

Equivalent dict form is also accepted.

parameterize_from_data style

You can also pass a dict that is forwarded to SoftPlusHSGP.parameterize_from_data(...):

model_config = {
    "intercept_tvp_config": {
        "ls_lower": 1.0,
        "ls_upper": 10.0,
    }
}

Abacus preserves that dict and uses it when constructing the HSGP.

How the latent process enters the model

Time-varying intercept

Abacus creates:

intercept_contribution = intercept_baseline * intercept_latent_process

Time-varying media

Abacus first creates a baseline transformed media contribution, then multiplies it by the temporal latent process:

channel_contribution =
  baseline_channel_contribution * media_temporal_latent_multiplier

If the custom media HSGP dims include channel, the multiplier can vary by channel. Otherwise it is broadcast across channels.

Save and load

Custom SoftPlusHSGP instances round-trip through PanelMMM.save(...) and PanelMMM.load(...).

That includes custom dims such as:

• ("date",)
• ("date", "channel")
• ("date", "geo")
• ("date", "geo", "channel")

Common pitfalls

• Expecting time_varying_media=True to create channel-specific media multipliers
• Using custom HSGP dims that do not align with the model dims
• Forgetting that boolean mode uses model_config["intercept_tvp_config"] and model_config["media_tvp_config"]

Next steps

• Read Seasonality and Trends for additive trend and seasonal components.
• Read Priors and Configuration for the TVP config keys.

Calibration

Calibration lets you add external evidence to a built PanelMMM.

Both calibration methods are unavailable for the named FE, CRE and release-gated RE presets; they raise EstimatorOperationError. Check Choose an Estimator before preparing calibration data. A built graph alone does not establish support.

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.

Lift-test calibration

Use add_lift_test_measurements(...) to add external lift measurements against the modelled saturation behaviour.

df_lift_test = pd.DataFrame(
    {
        "channel": ["tv", "search"],
        "x": [100.0, 80.0],
        "delta_x": [20.0, 10.0],
        "delta_y": [15.0, 6.0],
        "sigma": [3.0, 2.0],
    }
)

mmm.build_model(X, y)
mmm.add_lift_test_measurements(df_lift_test)

Required columns for lift tests

Lift-test data always needs:

• channel
• x
• delta_x
• delta_y
• sigma

It also needs:

• every configured entry in dims
• any additional coordinate columns required by the calibrated variables

In practice, time-varying media models usually require date, because the time-varying multiplier is indexed by date.

What Abacus does

add_lift_test_measurements(...):

1. validates the mapping columns
2. scales the lift-test channel and target values to the model scale
3. maps the rows to the model coordinates
4. adds a likelihood term named lift_measurements by default

If time_varying_media is enabled, Abacus includes the media temporal multiplier in the calibrated saturation function automatically.

Practical notes

• Lift measurements must be monotonic in the sense enforced by the calibration graph helpers.
• The calibration distribution defaults to pm.Gamma.
• You can change the registered variable name with name=....

Cost-per-target calibration

Use add_cost_per_target_calibration(...) when you want soft penalties on channel cost-per-target values.

mmm.build_model(X, y)
mmm.add_original_scale_contribution_variable(var=["channel_contribution"])

calibration_data = pd.DataFrame(
    {
        "geo": ["UK", "US"],
        "channel": ["tv", "search"],
        "cost_per_target": [30.0, 45.0],
        "sigma": [2.0, 3.0],
    }
)

mmm.add_cost_per_target_calibration(
    data=X,
    calibration_data=calibration_data,
    name_prefix="cpt_calibration",
)

Required prerequisites

Before you add cost-per-target calibration:

1. build the model
2. add channel_contribution_original_scale

The second step is required because cost-per-target calibration operates against original-scale channel contribution.

Required columns for calibration_data

calibration_data must include:

• channel
• cost_per_target
• sigma
• every configured entry in dims

Requirements for data

The data argument is the spend dataset used to compute calibrated cost per target.

After Abacus reshapes it into xarray form, its coordinates must match the built model’s:

• same shape
• same coordinate labels
• same channel list

If the reshaped spend data does not match the model coordinates, Abacus raises a validation error instead of silently reordering it.

YAML calibration

The YAML builder supports calibration through a top-level calibration: list. Each step must provide an explicit method plus a params mapping.

Supported YAML calibration methods:

• add_lift_test_measurements
• add_cost_per_target_calibration

Example:

original_scale_vars:
  - channel_contribution

calibration:
  - method: add_lift_test_measurements
    params:
      df_lift_test:
        dataframe:
          data:
            channel: ["channel_1", "channel_2"]
            x: [100.0, 80.0]
            delta_x: [20.0, 10.0]
            delta_y: [15.0, 6.0]
            sigma: [3.0, 2.0]

Important YAML constraints:

• calibration steps run after build_model(...)
• original_scale_vars is applied before calibration
• only the supported calibration methods above are available in YAML
• dist is not supported in YAML yet for add_lift_test_measurements
• other calibration actions should be applied through the Python API until they have explicit YAML support

Choose the right calibration path

Use lift tests when you have measured incremental response data for a specific spend change.

Use cost-per-target calibration when you want the fitted channel contribution to stay consistent with observed cost efficiency.

For a supported estimator, you can use either or both after building the model.

Common pitfalls

• Adding calibration before build_model(...)
• Forgetting to add channel_contribution_original_scale before cost-per-target calibration
• Omitting required dims columns from calibration data
• Assuming YAML supports every Python calibration argument; dist does not currently round-trip through YAML

Next steps

• Read Model Fitting for the fit workflow once the model has been fully specified.
• Read Save and Load if you plan to keep calibrated models on disk.

Correlated-random-effects Estimator

The released cre preset fits a one-unit correlated-random-effects (CRE) marketing-mix model. It combines shared media and control slopes with a Gaussian random unit intercept and an explicit adjustment for association between persistent unit differences and the declared predictors.

Released contract

estimator:
  type: cre
  unit: geo

The v1 surface has these deliberate limits:

Use the bundled starting point at data/demo/geo_cre/config.yml.

Run it from the repository root:

python3 runme.py --demo geo_cre

Statistical meaning

For unit i and date t, CRE augments the shared-slope level equation with unit summaries of the declared regressors. The media summaries are computed from the fitted adstock-and-saturation exposure basis. They are not raw-spend means. Eligible control summaries are standardised unit means.

The residual unit intercept is integrated out. The likelihood therefore uses one exact Gaussian covariance block per unit. Pointwise log likelihood is unit-block marginal evidence, not an observation-level or future-date score.

The adjustment relaxes the naive random-effects mean-independence restriction only with respect to the declared summary basis. It does not establish causal identification or address omitted time-varying confounding, measurement error, reverse causality, or response-function misspecification.

Data and estimability requirements

The dataset must be a balanced unit-date Cartesian product with one row per unit and date. It must contain enough units to estimate the active centred media and control summaries while retaining at least two residual between-unit degrees of freedom.

Abacus rejects:

• non-finite predictors or targets;
• media with no within-unit temporal variation;
• an exactly rank-deficient transformed between-summary design; and
• insufficient between-unit residual degrees of freedom.

It warns about low transformed within-unit variation, high variance inflation factors, and a high condition number. These thresholds are configurable under estimator.estimability. A pass means that the implemented screen found no declared defect. It is not proof of global, posterior-wide, or causal identification.

After fitting, inspect posterior convergence, effective sample size, sampler pathologies, prior sensitivity, the post-fit summary-basis diagnostics, and predictive checks. A CRE coefficient interval containing zero does not prove that a simpler random-effects model is adequate.

Pipeline evidence

A structured CRE run records:

• the resolved estimator contract in 00_run_metadata/estimator_summary.txt and 00_run_metadata/estimator_manifest.yaml;
• the raw structural screen in 10_pre_diagnostics/cre_structural_estimability.json;
• the transformed reference-basis screen in 10_pre_diagnostics/cre_reference_estimability.json and 10_pre_diagnostics/cre_reference_estimability_features.csv;
• the bounded posterior-draw screen in 20_model_fit/cre_postfit_estimability.json; and
• the CRE adjustment and reconciliation outputs under 40_decomposition.

The run manifest is the machine-readable index of these files. A completed pipeline only means that every required stage ran. Review the diagnostic status before interpreting the posterior.

Prediction and persistence

Prediction is conditional on the fitted unit history. Every prediction request must supply all fitted units. Row order may vary, but unseen units and fitted-unit subsets are rejected. Save and load preserve the fitted CRE summary state and validate its unit coordinates before prediction.

Historical and manual scenarios use the same fitted-unit restriction. Manual spend changes the nonlinear media-response path, but Abacus does not recompute the fitted training-period Mundlak media or control summaries. This preserves the fitted CRE adjustment rather than redefining confounding context from the planned spend. Scenario outputs are posterior media-contribution estimates, not total-outcome forecasts or causal effects.

Use the YAML and Python examples under data/demo/geo_cre/. Fixed-budget optimisation remains outside the released CRE scenario contract.

Evidence boundary

The release verifies the declared graph, configuration restrictions, estimability evidence, fitted-unit prediction contract and persistence path. It does not promise a fixed point-estimate accuracy, causal validity, or general robustness for arbitrary data. Treat each fitted model as a separate statistical assessment.

For a direct comparison with FE and the aggregate time-series preset, see Choose an Estimator.

Choose an Estimator

PanelMMM provides three released named estimator presets:

• time_series for one aggregate time series
• fe for a one-unit fixed-effects panel
• cre for a one-unit correlated-random-effects panel

The re declaration is typed but release-gated. It is not a runnable estimator.

Release support matrix

The support status is a software release boundary, not evidence that a preset is appropriate for a particular dataset or causal question.

Compare the released presets

All three presets combine likelihood information with the declared priors. None of them turns observational marketing data into a causal design.

Use the time-series preset

Use time_series when the modelling unit is one aggregate market, brand, or business series and each date occurs once.

estimator:
  type: time_series

Do not use it to disguise panel observations as independent aggregate rows. Aggregate the data deliberately or use a panel estimator.

Use FE

Use fe when the target question concerns changes within units over time and you want time-invariant unit characteristics removed from the shared-slope likelihood.

estimator:
  type: fe
  unit: geo

FE is appropriate only when the transformed media and controls have enough within-unit temporal variation. It cannot estimate coefficients for predictors that are constant within every unit. It also does not remove time-varying confounding or common shocks.

See Fixed-effects Estimator for the exact likelihood and estimability checks.

Use CRE

Use cre when persistent unit differences may be associated with the declared predictors and you need an explicit within-between panel specification.

estimator:
  type: cre
  unit: geo