YAML configuration schema reference

This is the complete field-level reference for meridian-tools YAML configuration files. For usage guidance, see the configuration guide.

All configuration models use Pydantic extra="forbid" — any key not listed here will produce a validation error.

Top-level structure

project: ProjectConfig         # optional, has defaults
data: CsvDataConfig            # required
model_spec: ModelSpecConfig    # optional, has defaults
fit: FitConfig                 # optional, has defaults
validation: ValidationConfig   # optional, has defaults
exports: ExportsConfig         # optional, has defaults
response_curves: ResponseCurvesConfig | null   # optional
optimisation: OptimisationConfig | null         # optional

project

Field Type Default Description
name str "meridian-project" Human-readable project name. Used as the base for run directory names.

data

Field Type Default Description
path Path required Path to CSV data file. Relative paths resolve against the YAML file’s directory.
kpi_type "revenue" | "non-revenue" "revenue" KPI type for Meridian’s data loader.
coord_to_columns dict[str, Any] required Maps Meridian coordinate names to CSV column names. Must include time.
media_to_channel dict[str, str] | null null Optional media-to-channel mapping override.
media_spend_to_channel dict[str, str] | null null Optional media-spend-to-channel mapping override.
reach_to_channel dict[str, str] | null null Optional reach-to-channel mapping override.
frequency_to_channel dict[str, str] | null null Optional frequency-to-channel mapping override.
rf_spend_to_channel dict[str, str] | null null Optional RF-spend-to-channel mapping override.
organic_reach_to_channel dict[str, str] | null null Optional organic-reach-to-channel mapping override.
organic_frequency_to_channel dict[str, str] | null null Optional organic-frequency-to-channel mapping override.

model_spec

Field Type Default Description
kwargs dict[str, Any] {} Keyword arguments forwarded directly to Meridian ModelSpec(**kwargs).

Supported kwargs keys include any argument accepted by Meridian’s ModelSpec constructor: max_lag, media_prior_type, holdout_id, etc. If holdout_id is present, the run is treated as an authored-holdout validation run.

Array-valued keys (holdout_id, control_population_scaling_id, non_media_population_scaling_id, rf_roi_calibration_period, roi_calibration_period) are converted to NumPy arrays at runtime.

fit

Field Type Default Constraint Description
sample_prior_draws PositiveInt | null null >0 if set Number of prior predictive draws. null skips prior sampling.
n_chains PositiveInt | list[PositiveInt] 4 >0 Number of MCMC chains.
n_adapt PositiveInt 500 >0 Adaptation steps per chain.
n_burnin PositiveInt 500 >0 Burn-in steps per chain.
n_keep PositiveInt 1000 >0 Posterior samples to retain per chain.
seed int | list[int] | null null — RNG seed for reproducibility.
max_tree_depth PositiveInt 10 >0 NUTS maximum tree depth.
max_energy_diff float 500.0 — NUTS maximum energy difference.
unrolled_leapfrog_steps PositiveInt 1 >0 NUTS unrolled leapfrog steps.
parallel_iterations PositiveInt 10 >0 TensorFlow parallel iterations.

validation

Field Type Default Constraint Description
strategy "none" | "blocked_tail" | "rolling_origin" "none" — Validation strategy.
holdout_size PositiveInt | null null Required for blocked_tail Number of tail time periods to hold out.
initial_train_size PositiveInt | null null Required for rolling_origin Initial training window size.
test_size PositiveInt | null null Required for rolling_origin Test window size per split.
step_size PositiveInt | null null Must equal test_size Step between rolling splits. Defaults to test_size.
max_splits PositiveInt | null null >=2 if set Maximum number of rolling splits.

Cross-field validation rules

  • strategy: none rejects all holdout and rolling-origin parameters.
  • strategy: blocked_tail requires holdout_size, rejects rolling-origin parameters.
  • strategy: rolling_origin requires initial_train_size and test_size, rejects holdout_size.
  • holdout_size without an explicit strategy is rejected (legacy shorthand removed).
  • Rolling-origin parameters without strategy: rolling_origin are rejected.

exports

Field Type Default Description
use_kpi bool false Use KPI-based metrics in Meridian analysis surfaces.
batch_size PositiveInt 1000 Batch size for Meridian Analyzer computations.
export_predictive_accuracy bool true Write predictive_accuracy.csv.
export_review_summary bool true Write review_summary.json.
export_model_selection bool true Write LOO/WAIC outputs (when compatible).
export_plots bool true Write PNG plot artefacts in each stage.

response_curves

Optional section. If omitted or null, the response curves stage is skipped.

Field Type Default Constraint Description
spend_multipliers list[float] required Non-empty, all >=0 Spend multiplier grid for response curve computation.
use_posterior bool true — Use posterior (vs prior) for response curves.
by_reach bool true — Compute reach-based response curves.
use_optimal_frequency bool false — Use optimal frequency in computation.
confidence_level float 0.9 0 < x < 1 Confidence level for credible intervals.

optimisation

Optional section. If omitted or null, the optimisation stage is skipped.

Field Type Default Constraint Description
start_date str required ISO YYYY-MM-DD Start of the optimisation window.
end_date str required ISO YYYY-MM-DD, >= start_date End of the optimisation window.
budget OptimisationBudgetConfig required — Budget specification (see below).
use_posterior bool true — Use posterior (vs prior) for optimisation.
use_optimal_frequency bool true — Use optimal frequency in optimisation.
confidence_level float 0.9 0 < x < 1 Confidence level for credible intervals.

optimisation.budget

Field Type Default Constraint Description
mode "fixed_total" | "relative_reference_window_total" required — Budget mode.
value PositiveFloat required >0 Budget value. Absolute for fixed_total, multiplier for relative_reference_window_total.

When mode: relative_reference_window_total, the effective budget is value × total_spend_in_reference_window. The reference window is defined by start_date and end_date.