Runner Overview

Use the pipeline runner when you want a full disk-backed PanelMMM run instead of only an in-memory fit.

The runner loads a YAML config and a CSV dataset, builds the model, executes a fixed stage sequence, and writes each stage’s artefacts into a structured run directory. When validation is enabled, the runner performs a second train-window fit for the blocked holdout stage, so the run takes longer than a pure full-sample fit.

If you want a quick first run, start with Quickstart: Pipeline Runner.

Public entry points

The public Python API is:

• abacus.pipeline.PipelineRunConfig
• abacus.pipeline.run_pipeline
• abacus.pipeline.PipelineRunResult

The thin CLI wraps the same code path:

python -m abacus.pipeline.runner --config path/to/config.yml

Basic Python example

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_baseline",
        prior_samples=10,
        draws=500,
        tune=500,
        chains=2,
        cores=2,
        random_seed=42,
        curve_samples=100,
        curve_points=100,
    )
)

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

PipelineRunResult contains:

What the runner does

run_pipeline(...) performs these steps:

1. Load the YAML config with load_yaml_config(...).
2. Load X and y from CSV using load_pipeline_data(...).
3. Merge CLI sampler overrides with YAML fit through build_model_kwargs(...).
4. Create the output directory tree and initialise run_manifest.json.
5. Run the retained stages in order, updating the manifest after every stage.

The model is built in Stage 00 by build_mmm_from_yaml(...), then stored in the shared PipelineContext for the remaining stages. Runner-only roots such as diagnostics and validation stay on the pipeline context and are stripped before the public MMM builder validates the model YAML.

Stage order

The runner uses a fixed stage list.

The validation stage is marked skipped when the YAML config does not contain validation or it is disabled. The optimisation stage is also optional; it returns None and is marked skipped when the YAML config does not contain an optimization block.

See Output Directory Schema for the stage folders and artefact layout.

Data and model assumptions

The retained runner is designed around PanelMMM.

• The flow-oriented public YAML is expected to describe a PanelMMM.
• The data loader reads CSV only.
• Later stages call PanelMMM plotting, summary, diagnostics, and optimisation methods directly.

If you need the exact YAML keys, see YAML Configuration.

PipelineRunConfig

PipelineRunConfig controls runtime settings that sit outside the YAML model specification.

Only sampler settings are merged into model construction. Other overrides are used by the runner itself during data loading, holiday resolution, diagnostics reporting, and output setup.

Run directory naming

The runner creates the run directory as:

<output_dir>/<effective_run_name>_<YYYYMMDD_HHMMSS>

The timestamp is generated in UTC.

All stage directories are created up front, even if a later stage is skipped or the run aborts.

Failure and skip behaviour

If a stage raises an exception:

• the current stage is marked failed
• the run manifest is marked failed
• all still-pending later stages are marked not_reached
• run_pipeline(...) re-raises the exception

If a stage returns None:

• the stage is marked skipped
• the manifest warning records that no configuration was supplied for that optional stage

Reporter hook

run_pipeline(...) accepts an optional reporter that implements the PipelineReporter protocol.

The reporter can observe:

• pipeline start
• stage start
• stage end
• pipeline end
• pipeline failure

See Extending the Runner for the callback contract.

YAML Configuration

The pipeline runner reads the same YAML model specification used by build_mmm_from_yaml(...), then adds a small set of runner-specific conventions for data loading, optional blocked holdout validation, and Stage 70 optimisation.

This page documents the keys that the runner actually consumes.

Root keys

Minimal runner config

data:
  dataset_path: dataset.csv
  date_column: date

target:
  column: revenue
  type: revenue

dimensions:
  panel: [geo]

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

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

Relative paths in YAML are resolved relative to the YAML file’s directory.

diagnostics is runner-only. The structured pipeline reads it, but build_mmm_from_yaml(...) still validates only the public MMM model schema.

validation is also runner-only. The structured pipeline reads it for Stage 35 blocked holdout scoring, but the public MMM YAML builder never sees it.

Core modeling blocks

The runner always builds a PanelMMM, so the public YAML no longer exposes a model.class field. Instead, it reads:

• data.date_column
• target.column
• target.type
• media.channels
• media.controls, if any
• dimensions.panel, if any
• media.adstock
• media.saturation
• fit

data

The runner loads data before building the model. It supports two CSV layouts.

Combined dataset

data:
  dataset_path: "dataset.csv"

The runner reads the CSV, removes the target column from X, and uses that column as y.

Separate feature and target files

data:
  x_path: "X.csv"
  y_path: "y.csv"

When loading y_path:

• if the configured target column exists, the runner uses that column
• otherwise, if the file has exactly one column, the runner uses that column and renames it to the target name

Target column resolution

The runner resolves the target column in this order:

1. PipelineRunConfig.target_column or CLI --target-column
2. target.column
3. "y"

Use the CLI override only when you want to change how the runner reads the CSV. Keep it consistent with target.column in YAML.

fit

fit controls Stage 20 fitting because the fit stage calls:

context.model.fit(X=context.X, y=context.y, progressbar=False)

The runner merges these CLI or PipelineRunConfig overrides onto the YAML fit block when they are provided:

• draws
• tune
• chains
• cores
• random_seed

The public YAML schema currently supports these fit keys:

• draws
• tune
• chains
• cores
• random_seed
• target_accept
• progressbar
• compute_convergence_checks

Unknown fit keys are rejected when the YAML is loaded.

effects

effects is an optional list of additive effect specifications:

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

The builder appends each effect to model.mu_effects in YAML order before calling build_model(...).

holidays

The holidays block is optional.

Supported keys used by the builder include:

Example:

holidays:
  path: "holidays.csv"
  prefix: "holiday"

The CLI or PipelineRunConfig.holidays_path overrides holidays.path.

If you omit both path and the override but still configure holidays, Abacus falls back to the bundled abacus.data:holidays.csv.

original_scale_vars

Use original_scale_vars when you want specific contribution variables to be available on the original target scale:

original_scale_vars:
  - channel_contribution
  - y

The builder applies these through model.add_original_scale_contribution_variable(...) before fitting.

inference_data

inference_data.path is passed through to the YAML builder. If the file exists, Abacus attaches that InferenceData to the built model during Stage 00.

Important: the structured runner still executes Stage 20 and fits the model again. inference_data.path does not currently skip fitting.

optimization

Add an optimization block when you want Stage 70 to run. If this block is absent, Stage 70 is marked skipped.

The YAML builder validates this block when the config is loaded. The required scalar fields below must be present, and unknown top-level optimization keys are rejected.

Required keys:

optimization:
  start_date: "2024-11-11"
  end_date: "2025-01-27"
  total_budget: 1289000000.0

Optional keys read by Stage 70:

Important budget-unit note

In the structured pipeline, optimization.total_budget is passed straight to PanelBudgetOptimizerWrapper.optimize_budget(...).

That means Stage 70 uses the wrapper’s per-period spend contract, not the scenario planner’s total-horizon spend contract.

See Budget Optimisation.

Xarray-like optimisation values in YAML

For panel bounds or time distributions, use the xarray-like mapping shape that Stage 70 expects:

optimization:
  start_date: "2025-02-03"
  end_date: "2025-02-24"
  total_budget: 100000.0
  budget_distribution_over_period:
    values:
      - [[0.25, 0.25], [0.25, 0.25]]
      - [[0.25, 0.25], [0.25, 0.25]]
      - [[0.25, 0.25], [0.25, 0.25]]
      - [[0.25, 0.25], [0.25, 0.25]]
    dims: ["date", "geo", "channel"]
    coords:
      date: [0, 1, 2, 3]
      geo: ["UK", "FR"]
      channel: ["channel_1", "channel_2"]

The same shape works for budget_bounds, but with an additional "bound" dimension containing "lower" and "upper".

diagnostics

Use the optional diagnostics block when you want Stage 50 to use different warn/fail thresholds than the retained defaults.

diagnostics:
  thresholds:
    design_max_vif:
      warn: 8.0
      fail: 12.0
    mcmc_max_rhat:
      warn: 1.02
      fail: 1.08

Supported threshold keys:

• design_max_vif
• design_condition_number
• mcmc_divergence_count
• mcmc_max_rhat
• mcmc_min_ess_bulk
• mcmc_bfmi_min
• predictive_nrmse
• residual_ljung_box_p
• residual_max_abs_acf

Validation rules:

• upper-bound checks require warn <= fail
• lower-bound checks require warn >= fail
• omit the block entirely to use the built-in defaults

This block affects only the structured runner. It is stripped before Stage 00 model build so the public MMM YAML schema remains unchanged.

validation

Use the optional validation block when you want Stage 35 blocked holdout scoring.

validation:
  enabled: true
  holdout_observations: 8
  include_last_observations: true
  coverage_levels: [0.5, 0.8, 0.94]
  sampler:
    draws: 500
    tune: 500
    chains: 2
    cores: 2
    random_seed: 42

Supported keys:

Phase 10 reports coverage as coverage_50, coverage_80, and coverage_94. Keep those defaults unless the implementation and tests are updated together.

The validation stage builds a clean train-window model for holdout scoring and ignores inference_data.path so the refit does not inherit attached posterior state from Stage 00.

Override precedence

For the runner, precedence is:

Common pitfalls

• Using Parquet paths in the pipeline data block. The runner data loader reads CSV only.
• Providing only one of data.x_path or data.y_path.
• Treating optimization.total_budget as total horizon spend instead of per-period spend.
• Assuming diagnostics is part of the public MMM builder schema. It is a runner-only block.
• Assuming inference_data.path skips Stage 20 fitting. It does not.
• Forgetting that relative paths are resolved from the YAML file directory, not from the shell working directory.

Output Directory Schema

Each pipeline run creates a timestamped directory under the configured output_dir:

<output_dir>/<run_name>_<YYYYMMDD_HHMMSS>

The timestamp is generated in UTC. The runner creates every stage directory up front, then updates run_manifest.json as stages start, complete, skip, or fail.

Directory tree

results/
  geo_panel_baseline_20260308_153000/
    run_manifest.json
    00_run_metadata/
    10_pre_diagnostics/
    20_model_fit/
    30_model_assessment/
    35_holdout_validation/
    40_decomposition/
    50_diagnostics/
    60_response_curves/
    70_optimisation/

Stage directories

See Runner Overview for the stage order and optionality.

Main artefacts by stage

00_run_metadata

Main files:

• a copy of the original config under its source filename
• config.original.yaml
• config.resolved.yaml
• session_info.txt
• dataset_metadata.json
• model_metadata.json
• data_dictionary.csv
• design_matrix_manifest.csv
• spec_summary.csv
• holiday_feature_manifest.csv when holidays are configured

config.resolved.yaml normalises configured data and holiday paths to absolute paths and records the effective sampler configuration on the model.

10_pre_diagnostics

Main files:

• prior_predictive.nc
• prior_predictive.png

20_model_fit

Main files:

• model.nc
• trace.png
• posterior_summary.csv

30_model_assessment

Main files:

• posterior_predictive.nc
• posterior_predictive.png
• posterior_predictive_summary.csv
• observed.csv
• fitted.csv
• fit_timeseries.png
• fit_scatter.png
• residuals.csv
• residuals_timeseries.png
• residuals_hist.png
• residuals_vs_fitted.png

This stage is the in-sample or training-fit assessment. It uses the same data the model was fit on and should not be read as the pipeline’s out-of-sample validation layer.

35_holdout_validation

Main files:

• validation_metadata.json
• holdout_posterior_predictive.nc
• holdout_predictive_summary.csv
• holdout_predictive_report.json
• holdout_observed.csv
• holdout_fitted.csv
• holdout_residuals.csv
• holdout_timeseries.png
• holdout_residuals_acf.png

The holdout summary and report include uncertainty-aware metrics such as crps, bias, and fixed coverage columns for coverage_50, coverage_80, and coverage_94.

This stage is optional. When validation is absent or disabled in YAML, the directory still exists and the stage is marked skipped.

40_decomposition

Main files:

• waterfall_components_decomposition.png
• weekly_media_contribution.png
• channel_contributions.csv
• baseline_contributions.csv
• mean_contributions_over_time.csv

50_diagnostics

Main files:

• design_summary.csv
• design_report.json
• vif_report.csv
• mcmc_summary.csv
• mcmc_report.json
• predictive_summary.csv
• predictive_report.json
• residual_diagnostics.csv
• residuals_acf.png
• diagnostics_report.csv
• diagnostics_summary.txt
• chain_diagnostics.txt

The design-oriented files are raw input screening outputs. In particular, diagnostics_report.csv labels the corresponding phase as raw_input_screening rather than design.

60_response_curves

Main files:

• saturation_curve.nc
• saturation_curve_summary.csv
• saturation_curve.png
• forward_pass_contribution_curve.nc
• forward_pass_contribution_curve_summary.csv
• forward_pass_contribution_curve.png
• adstock_curve.nc
• adstock_curve_summary.csv
• adstock_curve.png

These artefacts are intentionally different:

• saturation_curve.* is the sampled saturation transformation on the scaled channel axis, exported with original-scale contribution values for easier reading. The PNG overlays that saturation-only curve against posterior mean realised contributions.
• forward_pass_contribution_curve.* is a full-model direct contribution artefact. It rescales the observed historical spend path from 0% to 200%, runs that spend through the fitted adstock and saturation path, and records the resulting total channel contribution in original target units.
• adstock_curve.* is the sampled carryover-weight profile for one impulse.

70_optimisation

This directory is present for every run, but the stage is skipped unless the YAML config contains an optimization block.

Main files when the stage runs:

• optimized_allocation.nc
• optimized_allocation.csv
• response_distribution.nc
• optimize_result.json
• budget_summary.csv
• budget_response_points.csv
• budget_impact.csv
• budget_bounds_audit.csv
• budget_roi_cpa.csv
• budget_response_curves.csv
• budget_mroi.csv
• budget_optimisation.json
• several PNG plots for allocation, contribution over time, response curves, impact, bounds audit, and ROI or CPA

run_manifest.json

The manifest is the machine-readable index for the whole run.

Top-level fields include:

data includes:

• x_shape
• y_length
• target_column
• x_columns

Stage records

Each stage record contains:

The artifacts mapping uses root-relative paths such as 20_model_fit/model.nc.

Stage statuses

Common cases:

• Stage 35 is skipped when validation is missing or disabled from YAML.
• Stage 70 is skipped when optimization is missing from YAML.
• Later stages become not_reached after the first failure.

Practical use

Use the run directory when you want:

• a stable folder for downstream reporting
• a machine-readable audit trail through run_manifest.json
• stage-level links to artefacts without hard-coding filenames

If you want to add new artefact types or stages, see Extending the Runner.

CLI Reference

The pipeline exposes a thin CLI through abacus.pipeline.runner.

Entry point

python -m abacus.pipeline.runner --config path/to/config.yml

On success, the CLI prints the final run directory:

Structured pipeline completed: results/my_run_20260308_153000

Arguments

Common command patterns

Use the dataset path from YAML

python -m abacus.pipeline.runner \
  --config data/demo/geo_panel/config.yml

Override the combined dataset path

python -m abacus.pipeline.runner \
  --config configs/geo_panel.yml \
  --dataset-path /data/geo_panel_latest.csv \
  --run-name geo_panel_latest

Use separate feature and target files

python -m abacus.pipeline.runner \
  --config configs/panel.yml \
  --x-path /data/X.csv \
  --y-path /data/y.csv \
  --target-column revenue

Override sampler settings for one run

python -m abacus.pipeline.runner \
  --config configs/panel.yml \
  --draws 1000 \
  --tune 1000 \
  --chains 4 \
  --cores 4 \
  --random-seed 42

Override the holiday CSV

python -m abacus.pipeline.runner \
  --config configs/panel.yml \
  --holidays-path /data/holidays_uk_fr.csv

How CLI overrides interact with YAML

The CLI does not replace the full YAML config. It only overrides the runtime fields exposed through PipelineRunConfig.

Important behaviours:

• --dataset-path takes precedence over data.dataset_path.
• --x-path and --y-path take precedence over data.x_path and data.y_path.
• --holidays-path takes precedence over holidays.path.
• --draws, --tune, --chains, --cores, and --random-seed are merged onto YAML fit.
• --target-column affects CSV loading. Keep it consistent with target.column in YAML.

Exit behaviour

The CLI exits with status 0 on success. On failure, the process exits non-zero with the underlying exception.

The pipeline stops at the first stage failure. It does not provide flags to:

• run only a subset of stages
• continue after a failed stage
• disable individual built-in stages other than omitting the optional optimization block from YAML

See Runner Overview and YAML Configuration for the execution model and config surface.

Extending the Runner

The retained runner is static, not plugin-based. To add a stage or integrate custom status reporting, extend the existing runner surfaces instead of bypassing them.

Stage contract

A stage function has this contract:

def run_some_stage(context: PipelineContext) -> dict[str, str] | None:
    ...

Return values:

• return a dict[str, str] of artefact labels to root-relative paths when the stage succeeds
• return None when the stage is intentionally skipped
• raise an exception when the stage fails and should abort the run

The runner handles manifest updates around the stage call. Do not update context.manifest directly from a normal stage implementation unless you are changing core runner behaviour.

What is available in PipelineContext

PipelineContext gives each stage access to:

Artifact helpers

Use the helpers in abacus/pipeline/artifacts.py:

• write_json(...)
• write_dataframe(...)
• write_dataset(...)
• write_idata(...)
• write_text(...)
• save_figure(...)
• copy_file(...)

Use context.paths.relative(path) when building the artefact mapping that the stage returns. The manifest expects root-relative paths, not absolute paths.

Adding a new stage

To add a new built-in stage, update these places:

1. abacus/pipeline/artifacts.py Add the stage directory name to STAGE_DIRECTORIES.
2. abacus/pipeline/runner.py Add a PipelineStageSpec to PIPELINE_STAGE_SPECS.
3. abacus/pipeline/runner.py Add the stage function to the stage_functions mapping inside run_pipeline(...).
4. abacus/pipeline/stages/__init__.py Export the new stage helper if you want it available from the stage package.

Minimal stage example

from abacus.pipeline.artifacts import write_dataframe


def run_custom_stage(context):
    if context.model is None:
        raise ValueError("Model has not been initialized before the custom stage.")

    stage_dir = context.paths.stage_dirs["custom"]
    output_path = stage_dir / "custom_summary.csv"

    frame = context.model.summary.total_contribution(output_format="pandas")
    write_dataframe(output_path, frame)

    return {
        "custom_summary": context.paths.relative(output_path),
    }

Optional stage pattern

If a stage should only run when a config block is present, follow the same pattern as Stage 70:

def run_optional_stage(context):
    cfg = context.raw_cfg.get("my_optional_block")
    if cfg is None:
        return None
    ...

Returning None is what marks the stage as skipped in the manifest.

Failure semantics

If your stage raises an exception:

• the stage is marked failed
• the run is marked failed
• later pending stages are marked not_reached
• run_pipeline(...) re-raises the exception

That means stage code should only catch exceptions when it can recover locally and still produce a valid artefact set.

Adding structured reporting

If you want progress callbacks without changing the core stage code, implement a PipelineReporter and pass it to run_pipeline(...).

The reporter protocol methods are:

• on_pipeline_start(...)
• on_stage_start(...)
• on_stage_end(...)
• on_pipeline_end(...)
• on_pipeline_error(...)

This is the right extension point for:

• notebooks or dashboards that want progress updates
• lightweight orchestration wrappers
• structured logging around pipeline runs

Consuming the manifest programmatically

The manifest is written after every stage transition, so external tools can poll run_manifest.json during execution.

Typical uses:

• check whether the optimisation stage was skipped
• discover stage artefact paths without hard-coding filenames
• detect the first failed stage and its error message

See Output Directory Schema for the manifest fields and status values.