AMMM User Guide

This is the practical day-to-day guide for running AMMM V2 and reading outputs.

What This Guide Covers

V2 architecture and preferred entrypoints
CLI usage (runme.py) and common run modes
Stage-based outputs and diagnostic gate checks
Optimisation, multi-period planning, and reporting outputs

1. Architecture in Practice

AMMM uses MMMBaseDriverV2 as the active orchestrator.

Preferred import in repository execution contexts:

from driver import MMMBaseDriverV2

Compatibility import (package-root contexts):

from src.driver import MMMBaseDriverV2

2. Quick Start Commands

# Default run (scenarios enabled)
python runme.py

# Explicit file paths
python runme.py --config data-config/demo_config.yml --data data-config/demo_data.csv --holidays data-config/holidays.csv

# Fast iteration mode
python runme.py --fast

# Single-period optimisation only
python runme.py --no-scenarios

# Multi-period planning
python runme.py --multiperiod --multiperiod-weeks 13

3. Important CLI Flags

Input/output

--data
--config
--holidays
--results-dir

Run mode

--no-scenarios
--scenarios
--multiperiod
--multiperiod-weeks
--no-seasonality
--use-adstock (not compatible with --multiperiod)

Sampling and runtime

--fast
--draws, --tune, --chains, --target-accept
--jax, --gpu, --chain-method

Multi-period constraints

--ramp-abs
--ramp-pct
--ramp-config
--strict-ramp-config
--ramp-eps
--round-increment
--seasonality-clip-min, --seasonality-clip-max

4. Results Layout (V2)

Each run writes stage folders under the results root:

results/
├── 00_run_metadata/
├── 10_pre_diagnostics/
├── 20_model_fit/
├── 30_model_assessment/
├── 40_decomposition/
├── 50_diagnostics/
├── 60_response_curves/
├── 70_optimisation/
└── 80_interpretation/

5. Diagnostic-First Review

Always inspect diagnostics before consuming business outputs.

Primary machine-readable checks:

50_diagnostics/convergence_report.json -> converged
50_diagnostics/calibration_report.json -> well_calibrated
50_diagnostics/pareto_k_summary.json -> ok

diagnostics_gating policy in config:

strict: halt pipeline on failed convergence gate
warn: continue with warnings
off: non-strict behaviour in current implementation

6. Core Artefacts by Stage

Model fit (`20_model_fit/`)

model.nc
model.dill
model_summary.csv
model_trace.png
posterior_forest.png
prior_posterior_comparison.png

Model assessment (`30_model_assessment/`)

model_fit_predictions.png
model_fit_metrics.csv
posterior_predictive_check.png

Decomposition (`40_decomposition/`)

all_decomp.csv
waterfall_plot_components_decomposition.png
media_contribution_per_spend.csv

Diagnostics (`50_diagnostics/`)

convergence_report.json / .csv
rank_trace.png
energy_diagnostic.png
calibration_report.json
calibration_pit_histogram.png
pareto_k_summary.json
pair_plot.png
residuals_vs_{channel}.png

Response curves (`60_response_curves/`)

response_curves.png
all_response_curves.csv

Optimisation (`70_optimisation/`)

optimization_results.csv
budget_optimisation.png
budget_scenario_results.csv
multiperiod_optimization_results.csv (multi-period mode)

Interpretation (`80_interpretation/`)

ammm_report.md
business_report.md
agentic_report.md (when available)
llm_interpretations.json

7. Python Workflow Example

from driver import MMMBaseDriverV2

driver = MMMBaseDriverV2(
    config_filename="data-config/demo_config.yml",
    input_filename="data-config/demo_data.csv",
    holidays_filename="data-config/holidays.csv",
    results_filename="results",
)

driver.main()

8. Multi-Period Notes

Enable from CLI:

python runme.py --multiperiod --multiperiod-weeks 13

Outputs are written to 70_optimisation/, including:

multiperiod_optimization_results.csv
multiperiod_budget_heatmap.png
multiperiod_contribution_over_time.png
multiperiod_budget_vs_contribution.png

For details, see Multi-Period Optimisation.

9. LLM Reports (Optional)

If LLM reporting is enabled, AMMM writes reports to 80_interpretation/. Review diagnostics first, then use report outputs as a summary layer.

10. Caveats

Good diagnostics indicate computational adequacy, not causal proof.
Assisted baseline mode (prophet.trend: true) can improve practical fit but introduces attribution leakage risk; run sensitivity checks.
Optimisation quality is limited by model specification quality.