YAML builder quickstart

Use the YAML builder when you want the model specification to live in a config file instead of Python code.

The builder entry point is:

from abacus.mmm.builders.yaml import build_mmm_from_yaml

Smallest useful workflow

Run this example from the repository root. It uses the bundled dataset and an in-memory YAML mapping. raw_cfg supplies that mapping to the builder; config_path only supplies the base directory for relative paths in this case.

The bundled demo configuration also contains runner-only sections. Pass that file to the pipeline runner. The direct builder rejects runner-only roots such as diagnostics, validation, prior_sensitivity and ai_advisor.

import pandas as pd
import yaml

from abacus.mmm.builders.yaml import build_mmm_from_yaml

builder_config = yaml.safe_load("""
data:
  date_column: date
target:
  column: revenue
  type: revenue
media:
  channels: [channel_1, channel_2, channel_3, channel_4, channel_5, channel_6]
  adstock:
    type: geometric
    l_max: 4
  saturation:
    type: logistic
""")

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")

mmm = build_mmm_from_yaml(
    "data/demo/timeseries/config.yml",
    raw_cfg=builder_config,
    X=X,
    y=y,
)

build_mmm_from_yaml(...) returns a PanelMMM instance with the PyMC graph already built.

Minimal config structure

For a file-based workflow, save a model configuration beside its dataset. The following structure illustrates the required blocks; replace the dataset path and channel names with your inputs. Omit raw_cfg when loading that file.

data:
  dataset_path: dataset.csv
  date_column: date

target:
  column: revenue
  type: revenue

media:
  channels:
    - channel_1
    - channel_2
    - channel_3
  adstock:
    type: geometric
    l_max: 4
  saturation:
    type: logistic

fit:
  draws: 1000
  tune: 1000
  chains: 4
  random_seed: 42

How data loading works

The builder supports two data-loading patterns.

If you use data.dataset_path, the target column must be present in that file. The builder splits it out into X and y before building the model.

The builder also normalises X[date_column] with pd.to_datetime(...) after loading the data.

Configured relative paths are resolved relative to the YAML file location.

Fit after building

The builder does not fit the model for you. Fit it in the usual way:

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

If you rely on data.dataset_path, either split the combined dataset in Python before fitting, or load it once in Python and pass the same X and y into both build_mmm_from_yaml(...) and fit(...).

Optional top-level YAML blocks

The builder recognises several optional top-level sections in addition to data, target, and media.

Override config values from Python

Use model_kwargs when you want to keep most settings in YAML but override a subset from Python.

Continuing the in-memory example above, override the sampler settings with:

mmm = build_mmm_from_yaml(
    "data/demo/timeseries/config.yml",
    raw_cfg=builder_config,
    X=X,
    y=y,
    model_kwargs={
        "sampler_config": {
            "draws": 200,
            "tune": 200,
            "chains": 2,
            "cores": 2,
            "progressbar": False,
            "compute_convergence_checks": False,
            "random_seed": 42,
        }
    },
)

model_kwargs takes precedence over the YAML defaults.

Next steps

• Read Quickstart: Pipeline Runner if you want staged artefacts and manifests instead of an in-memory fit only.
• Read Data Preparation for dataset column and layout requirements.