Guide: Configuring the Model Run

This guide explains how to configure AMMM V2 with config.yml, and how that configuration interacts with runme.py CLI flags.

What This Guide Covers

• Required and high-impact YAML keys
• Current V2 run controls (runme.py flags)
• Stage-based output expectations
• Diagnostic gating behaviour (diagnostics_gating)

Minimal Workflow

1. Start from a known-good config (for example data-config/demo_config.yml).
2. Set data columns and media channel mappings.
3. Configure baseline controls and priors.
4. Run python runme.py.
5. Review diagnostics in 50_diagnostics/ before downstream interpretation.

Core YAML Sections

Data and Target

raw_data_granularity: weekly
date_col: date
target_col: kpi
target_type: revenue
train_test_ratio: 1.0

Media Channels

media:
  - display_name: TV
    impressions_col: tv_impressions
    spend_col: tv_spend
  - display_name: Search
    impressions_col: search_impressions
    spend_col: search_spend

Controls

extra_features_cols:
  - competitor_sales
  - newsletter
  - events

extra_features_impact:
  competitor_sales: negative

Prophet-Assisted Baseline

prophet:
  include_holidays: true
  holiday_country: US
  yearly_seasonality: true
  weekly_seasonality: true
  trend: true

Practical note:

• trend: true uses an assisted baseline (Prophet trend estimated from the target and injected as a control), which can reduce collinearity but introduces attribution leakage risk.
• For a more conservative setup, compare against trend: false.

Sampling Controls

tune: 2000
draws: 2000
chains: 4
target_accept: 0.95
ad_stock_max_lag: 8
seed: 42

Diagnostics Gating

diagnostics_gating: warn

Allowed policy values in practice:

• strict: halt after failed convergence gate
• warn: continue with warnings
• off: treated as non-strict in current workflow

Run Modes Are Controlled by CLI

Budget mode is not selected by a YAML run_mode key. Use runme.py flags:

# Scenario planning (default)
python runme.py

# Scenario planning with custom levels
python runme.py --scenarios "-10,-5,0,5,10"

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

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

Result artefacts:

• Scenario planning: 70_optimisation/budget_scenario_results.csv
• Single-period optimisation: 70_optimisation/optimization_results.csv
• Multi-period optimisation: 70_optimisation/multiperiod_optimization_results.csv

High-Value CLI Overrides

python runme.py \
  --draws 1500 \
  --tune 1000 \
  --chains 2 \
  --target-accept 0.9 \
  --results-dir results

Related flags:

• Performance: --fast, --jax, --gpu, --chain-method
• Ramping (multi-period): --ramp-abs, --ramp-pct, --ramp-config, --strict-ramp-config, --ramp-eps
• Seasonality clips: --seasonality-clip-min, --seasonality-clip-max

Validation Checks

After each config change, inspect:

1. 10_pre_diagnostics/stationarity_summary.csv
2. 10_pre_diagnostics/vif_summary.csv
3. 10_pre_diagnostics/prior_predictive_summary.csv
4. 50_diagnostics/convergence_report.json (converged)
5. 50_diagnostics/calibration_report.json (well_calibrated)

If diagnostics fail, revise priors/specification before trusting optimisation or business reports.

Full Example (Template)

raw_data_granularity: weekly
date_col: date
target_col: revenue
target_type: revenue
train_test_ratio: 1.0

media:
  - display_name: TV
    impressions_col: tv_impressions
    spend_col: tv_spend
  - display_name: Search
    impressions_col: search_impressions
    spend_col: search_spend

extra_features_cols:
  - competitor_sales
  - promotions

extra_features_impact:
  competitor_sales: negative

prophet:
  include_holidays: true
  holiday_country: US
  yearly_seasonality: true
  weekly_seasonality: true
  trend: false

tune: 2000
draws: 2000
chains: 4
target_accept: 0.95
ad_stock_max_lag: 8
seed: 42

diagnostics_gating: warn

See also:

• Running The Model
• Interpreting Results
• Optimisation