Output schema reference

This page documents the complete run directory layout produced by meridian-tools. Every successful pipeline run creates a timestamped directory containing the artefacts described below.

Run directory structure

<run_name>_<YYYYMMDD_HHMMSS>/
│
├── run_manifest.json                        # Source of truth for the run
│
├── 00_run_metadata/
│   ├── config.source.yaml                   # Verbatim copy of the authored YAML
│   ├── config.resolved.yaml                 # YAML after path resolution
│   └── input_data_provenance.json           # Pinned source/resolution/hash metadata
│
├── 10_validation/                           # Only for validation-aware runs
│   └── validation_spec.json                 # Validation provenance record
│
├── 20_model_fit/
│   ├── meridian_model.binpb                 # Serialised Meridian model
│   └── fit_metadata.json                    # Fit settings and Meridian version
│
├── 30_model_assessment/
│   ├── diagnostics_bundle.json              # Diagnostics export manifest
│   ├── predictive_accuracy.csv              # Per-observation accuracy metrics
│   ├── review_summary.json                  # Meridian review battery results
│   ├── model_results_summary.html           # Meridian HTML summary report
│   ├── plots/                               # When export_plots: true
│   │   ├── model_fit.png
│   │   └── rhat_boxplot.png
│   │
│   │  # Model selection outputs (compatible runs):
│   ├── loo_summary.json                     # LOO summary statistics
│   ├── waic_summary.json                    # WAIC summary statistics
│   ├── loo_pointwise.csv                    # Per-observation LOO + Pareto k
│   ├── waic_pointwise.csv                   # Per-observation WAIC
│   └── model_comparison.csv                 # Ranked comparison table
│   │
│   │  # Model selection status (incompatible runs):
│   └── model_selection_status.json          # Reason code for unavailability
│
├── 40_decomposition/
│   ├── summary_metrics.nc                   # NetCDF decomposition dataset
│   ├── summary_metrics.csv                  # Tabular decomposition
│   └── plots/                               # When export_plots: true
│       ├── channel_contribution_area_chart.png
│       ├── contribution_waterfall_chart.png
│       ├── spend_vs_contribution_chart.png
│       └── roi_bar_chart.png
│
├── 60_response_curves/                      # Only when response_curves configured
│   ├── response_curves.nc                   # NetCDF response curve dataset
│   ├── response_curves.csv                  # Tabular response curves
│   └── plots/                               # When export_plots: true
│       └── response_curves_plot.png
│
└── 70_optimisation/                         # Only when optimisation configured
    ├── optimisation_summary.html            # Meridian optimisation HTML report
    ├── optimised_data.nc                    # Optimised allocation (NetCDF)
    ├── optimised_data.csv                   # Optimised allocation (CSV)
    ├── nonoptimised_data.nc                 # Baseline allocation (NetCDF)
    ├── nonoptimised_data.csv                # Baseline allocation (CSV)
    ├── optimisation_grid.csv                # Full optimisation grid
    └── plots/                               # When export_plots: true
        ├── incremental_outcome_delta_plot.png
        ├── budget_allocation_optimised_plot.png
        ├── budget_allocation_nonoptimised_plot.png
        ├── spend_delta_plot.png
        └── optimisation_response_curves_plot.png

Stage details

00_run_metadata

Always present. Created first.

Artefact Format Description
config.source.yaml YAML Verbatim copy of the source config for this run. On refresh, this is copied from the source run’s archived config.source.yaml.
config.resolved.yaml YAML Config after relative path resolution. Does not include runtime-only fields (output_dir, run_name).
input_data_provenance.json JSON Pinned input-data provenance: authored path, resolved path, SHA-256, file size, mtime, row count, column count, and ordered columns.

10_validation

Present only for validation-aware runs (blocked tail, rolling origin, authored holdout, or final fit with validation provenance).

Artefact Format Description
validation_spec.json JSON Full validation provenance. See validation-spec-schema.md.

20_model_fit

Always present.

Artefact Format Description
meridian_model.binpb Protocol Buffers Serialised Meridian model (requires google-meridian[schema]).
fit_metadata.json JSON Records FitConfig values and Meridian version.

30_model_assessment

Always present. Content varies by compatibility.

Artefact Format Condition Description
diagnostics_bundle.json JSON Always Diagnostics export manifest with status of each sub-export.
predictive_accuracy.csv CSV export_predictive_accuracy: true Predictive accuracy per observation.
review_summary.json JSON export_review_summary: true Meridian review battery results.
model_results_summary.html HTML Always Meridian HTML model summary.
plots/model_fit.png PNG export_plots: true Model fit visualisation.
plots/rhat_boxplot.png PNG export_plots: true R-hat convergence diagnostic boxplot.
loo_summary.json JSON Compatible + export_model_selection: true LOO summary.
waic_summary.json JSON Compatible + export_model_selection: true WAIC summary.
loo_pointwise.csv CSV Compatible + export_model_selection: true Per-observation LOO values.
waic_pointwise.csv CSV Compatible + export_model_selection: true Per-observation WAIC values.
model_comparison.csv CSV Compatible + export_model_selection: true Ranked model comparison.
model_selection_status.json JSON Incompatible + export_model_selection: true Reason for unavailability.

40_decomposition

Always present.

Artefact Format Description
summary_metrics.nc NetCDF Full decomposition dataset with coordinates.
summary_metrics.csv CSV Flattened tabular decomposition.
plots/channel_contribution_area_chart.png PNG Channel contribution over time.
plots/contribution_waterfall_chart.png PNG Contribution waterfall breakdown.
plots/spend_vs_contribution_chart.png PNG Spend vs. contribution scatter.
plots/roi_bar_chart.png PNG ROI by channel bar chart.

60_response_curves

Present only when the response_curves YAML section is configured.

Artefact Format Description
response_curves.nc NetCDF Response curve dataset across spend multipliers.
response_curves.csv CSV Flattened tabular response curves.
plots/response_curves_plot.png PNG Response curve visualisation.

70_optimisation

Present only when the optimisation YAML section is configured.

Artefact Format Description
optimisation_summary.html HTML Meridian optimisation summary report.
optimised_data.nc NetCDF Optimised budget allocation.
optimised_data.csv CSV Tabular optimised allocation.
nonoptimised_data.nc NetCDF Baseline (non-optimised) allocation.
nonoptimised_data.csv CSV Tabular baseline allocation.
optimisation_grid.csv CSV Full optimisation grid dataset.
plots/incremental_outcome_delta_plot.png PNG Incremental outcome delta.
plots/budget_allocation_optimised_plot.png PNG Optimised allocation chart.
plots/budget_allocation_nonoptimised_plot.png PNG Baseline allocation chart.
plots/spend_delta_plot.png PNG Spend delta between optimised and baseline.
plots/optimisation_response_curves_plot.png PNG Optimisation response curves.

Reading order for analysts

For a quick assessment of a completed run:

  1. run_manifest.json — run identity, timing, stage completion
  2. 00_run_metadata/config.source.yaml — what was authored
  3. 00_run_metadata/input_data_provenance.json — dataset identity and shape
  4. 30_model_assessment/diagnostics_bundle.json — diagnostics export state
  5. 30_model_assessment/model_results_summary.html — visual model summary
  6. 40_decomposition/summary_metrics.csv — easiest tabular output to inspect

For model selection:

  1. 30_model_assessment/loo_summary.json or model_selection_status.json

For scenario analysis:

  1. 60_response_curves/response_curves.csv
  2. 70_optimisation/optimisation_summary.html