YAML Model Specification

This page documents the YAML keys that define the statistical model: the core modelling blocks, the named estimator presets, additive effects, holidays and original-scale contribution variables. The YAML configuration overview lists all root keys, YAML runner settings covers data loading, fitting, optimisation and validation, and YAML advanced blocks covers prior_sensitivity, ai_advisor and diagnostics.

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
• estimator, for a named preset
• dimensions.panel, if any
• media.adstock
• media.saturation
• fit

Half-life adstock YAML

Set media.adstock.parametrization: halflife only for geometric or delayed adstock. It requires an explicit halflife prior. median: 4 means four model periods and becomes mu: log(4) for a LogNormal prior. Omit parametrization to retain the established alpha default.

media:
  channels: [tv, search]
  adstock:
    type: geometric
    l_max: 16
    normalize: true
    parametrization: halflife
    priors:
      halflife:
        distribution: LogNormal
        median: 4
        sigma: 0.35
        dims: [channel]
  saturation:
    type: logistic

Stage 00 retains the source YAML as config.original.yaml. Its config.resolved.yaml contains the effective half-life component prior with mu, and no competing active root prior. The fit summary labels halflife as a sampled parameter in model_periods and alpha as a derived, dimensionless diagnostic. For delayed adstock, the half-life label means half-width at half maximum around theta.

estimator

The released named single-series contract is:

estimator:
  type: time_series

It requires one observation per date and no panel unit. It builds the same single-series graph as the established configuration with no dimensions.panel for the same configuration. With the default model settings, this means one global intercept and shared media, control, adstock, saturation, and residual parameters. Other explicit single-series model options retain their established behaviour; the estimator declaration does not silently override them.

The released fixed-effects contract is:

estimator:
  type: fe
  unit: geo
  estimability:
    within_variation_share_warning: 0.05
    max_vif_warning: 20
    condition_number_warning: 30

It accepts one unit column and uses an exact within-unit orthonormal-contrast likelihood. Unit intercepts are absorbed. Media and control slopes, adstock, saturation, and residual scale are shared across units. The FE preset does not support common time effects, annual seasonality, custom additive effects, or time-varying parameters. See Fixed-effects Estimator for the estimability checks and interpretation limits.

The released correlated-random-effects contract is:

estimator:
  type: cre
  unit: geo
  estimability:
    within_variation_share_warning: 0.05
    max_vif_warning: 20
    condition_number_warning: 30
    minimum_between_residual_df: 2
    posterior_diagnostic_draws: 50

It accepts one balanced unit panel. Media and control slopes, geometric adstock, logistic saturation, and residual scale are shared across units. The graph uses an exact marginal Gaussian random-intercept likelihood and adds centred unit means of the transformed media basis and eligible time-varying controls. Common time effects, seasonality, custom effects, calibration, optimisation and fixed-budget scenario optimisation are not supported. Prediction and historical/manual scenarios require all fitted units and reject unseen units and unit subsets. Manual CRE scenarios retain the fitted training-period Mundlak summaries rather than recomputing them from planned spend. See Correlated-random-effects Estimator for the estimability and interpretation limits.

The re declaration validates as typed configuration but remains release-gated. It fails before graph construction and does not fall back to the advanced panel-dimension surface.

Do not combine estimator with dimensions.panel. AMMM3 rejects the mixed declaration rather than guessing which semantics you intended.

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:
  mode: prophet_component
  path: "../../data/holidays.csv"
  prefix: "holiday"
  countries: "UK"

The CLI or PipelineRunConfig.holidays_path overrides holidays.path.

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

Country-selection rules:

• time-series configs default to US when holidays.countries is omitted
• geo-panel configs must declare holidays.countries explicitly
• geo-panel configs must provide multiple countries, for example ["UK", "FR", "DE"]

If you provide a catalogue-style holiday CSV, AMMM3 only creates holiday effects for the countries listed in holidays.countries.

Holiday modes:

• event creates one latent holiday/event effect per holiday row, which is why posterior summaries include terms like holiday_effect_size[...].
• pooled_control creates one pooled binary holiday regressor over time and estimates a single shared holiday coefficient. This is useful when you want a strict calendar-only single holiday term instead of one parameter per holiday.
• prophet_component fits Prophet on the training target with the configured holiday calendar, extracts the continuous holidays component, and uses that single smoothed series inside the MMM as one holiday term. For panel models, AMMM3 fits one Prophet holiday component per panel series and filters the holiday calendar by geo when that dimension is present.

For holiday effects, each model date labels the start of its observed period. AMMM3 assigns an inclusive holiday date range to every model period it overlaps. For example, on W-MON data, a Wednesday or Sunday holiday is assigned to the Monday date that starts that week. Daily data retains its existing date-by-date assignment.

Default behavior:

• configs default to prophet_component
• use event explicitly when you want one latent holiday effect per holiday row

Current limitation:

• pooled_control currently supports only single-country, non-geo models.
• prophet_component requires exactly one holiday country unless the model has a geo dimension, in which case it can route multiple holiday countries to the matching geo-level panel series.

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.

Related pages

• YAML Configuration
• YAML Runner Settings
• YAML Advanced Blocks