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.