Meridian Tools demo guide

This is the canonical guide to the bundled meridian-tools demos. Use it when you want one safe, reproducible, end-to-end example without client data.

The public story is simple:

  • Meridian is the modelling engine.
  • meridian-tools is the workflow wrapper.
  • The bundled demos are launched through meridian-tools surfaces, not by calling Meridian directly.

What the bundled demos are for

Phase 08 adds two bundled reference workflows:

  • timeseries
    • a national timeseries demo shipped as packaged demo data
  • geo_panel
    • a geo-panel demo shipped as packaged demo data

Both datasets are bundled non-client reference data. They exist so analysts and stakeholders can inspect the workflow, run structure, and review artefacts without using client material.

What the package adds on top of Meridian

Meridian remains responsible for the modelling and analysis primitives. meridian-tools adds the operational surface that agencies usually need around it:

  • typed YAML configuration
  • blocked-tail and rolling-origin validation workflow
  • manifest-backed run directories
  • diagnostics bundling
  • compatibility-aware Bayesian model-selection outputs
  • lifecycle compare and refresh helpers
  • a thin demo launcher for bundled reference workflows

This is why the demos are useful. They show the wrapper workflow directly, rather than asking users to reconstruct it from notebooks or internal scripts.

Demo entrypoints

List the supported demos:

meridian-tools demo --list

Run the bundled timeseries demo:

meridian-tools demo timeseries

Run the bundled geo-panel demo:

meridian-tools demo geo_panel

By default, demo runs are written under runs/demos/. If you want a different root, pass --output-dir. If you want a custom visible run name, pass --run-name.

Example:

meridian-tools demo timeseries --output-dir sandbox/demo-runs --run-name demo-timeseries-review

The repo-root checkout wrapper remains available when you are working from the source tree:

python runme.py demo --list
python runme.py demo timeseries

The same package can also run an explicit authored config:

meridian-tools run --config /path/to/project.yml --output-dir runs

The repo-root wrapper can run an explicit authored config too:

python runme.py run --config /path/to/project.yml --output-dir runs

Bundled YAML surface

The bundled demo YAML files are real meridian-tools configs. They are not legacy Abacus-style placeholders.

The authored sections used in Phase 08 are:

  • project
  • data
  • model_spec
  • fit
  • validation
  • exports
  • response_curves
  • optimisation

The Phase 08 additions are:

  • response_curves
    • required if you want the response-curve export stage to run
  • optimisation
    • required if you want the optimisation export stage to run

The bundled demos include both sections so that the full staged schema is exercised.

The default demo configs use validation.strategy: none. That keeps the reference runs model-selection compatible, so LOO and WAIC outputs are written by default.

Output schema

Each successful demo run writes one manifest-backed staged directory layout:

<run_dir>/
  run_manifest.json
  00_run_metadata/
    config.source.yaml
    config.resolved.yaml
  20_model_fit/
    meridian_model.binpb
    fit_metadata.json
  30_model_assessment/
    diagnostics_bundle.json
    predictive_accuracy.csv
    review_summary.json
    model_results_summary.html
    plots/
      model_fit.png
      rhat_boxplot.png
    loo_summary.json
    waic_summary.json
    loo_pointwise.csv
    waic_pointwise.csv
    model_comparison.csv
    # or model_selection_status.json when unavailable
  40_decomposition/
    summary_metrics.nc
    summary_metrics.csv
    plots/
      channel_contribution_area_chart.png
      contribution_waterfall_chart.png
      spend_vs_contribution_chart.png
      roi_bar_chart.png
  60_response_curves/
    response_curves.nc
    response_curves.csv
    plots/
      response_curves_plot.png
  70_optimisation/
    optimisation_summary.html
    optimised_data.nc
    optimised_data.csv
    nonoptimised_data.nc
    nonoptimised_data.csv
    optimisation_grid.csv
    plots/
      incremental_outcome_delta_plot.png
      budget_allocation_optimised_plot.png
      budget_allocation_nonoptimised_plot.png
      spend_delta_plot.png
      optimisation_response_curves_plot.png

run_manifest.json stays top-level and remains the source of truth for artefact discovery, stage status, version metadata, and relative file paths.

Always exported versus config-gated outputs

For the current Phase 08 contract:

  • always exported for successful runs:
    • 00_run_metadata
    • 20_model_fit
    • 30_model_assessment
    • 40_decomposition
    • exported only when applicable:
    • 10_validation
      • written for validation-aware runs
      • skipped for runs with no validation metadata
    • 60_response_curves
      • requires the authored response_curves section
    • 70_optimisation
      • requires the authored optimisation section

Within 30_model_assessment, model selection remains compatibility-aware:

  • compatible runs write loo, waic, and comparison outputs
  • incompatible runs write model_selection_status.json
  • compatibility unavailability is non-fatal

How to read the important outputs

Start with these artefacts:

  • run_manifest.json
    • run identity, versions, timestamps, stage status, and top-level artefact links
  • 00_run_metadata/config.source.yaml
    • the authored YAML
  • 00_run_metadata/config.resolved.yaml
    • the same YAML after runtime path resolution
  • 10_validation/validation_spec.json
    • validation provenance for validation-aware runs only
    • not present in the default bundled demos because they run as full-sample fits
  • 30_model_assessment/diagnostics_bundle.json
    • the stable machine-readable record of diagnostics export state
  • 30_model_assessment/model_results_summary.html
    • the wrapped Meridian assessment summary
  • 40_decomposition/summary_metrics.csv
    • the easiest tabular decomposition output to inspect first

For model selection, keep the boundary honest:

  • LOO and WAIC are only available for compatible fitted Meridian models
  • validation fits and other incompatible cases will record model_selection_status.json instead
  • the package does not pretend unsupported runs have valid Bayesian comparison outputs
  • the bundled demos are configured as full-sample fits, so they should write loo_summary.json and waic_summary.json by default

For response curves and optimisation:

  • these outputs are useful for scenario and allocation review
  • they are not a substitute for checking diagnostics, validation provenance, or model-selection compatibility first

For visual review, each stage now keeps its PNG exports inside a local plots/ subdirectory rather than mixing image files into the stage root. That keeps the machine-readable exports and the human-review plots in one predictable place.

If you are new to the repository, use this order:

  1. run meridian-tools demo --list
  2. run one of the bundled demos
  3. open run_manifest.json
  4. inspect 00_run_metadata/config.source.yaml
  5. inspect 30_model_assessment/diagnostics_bundle.json
  6. inspect 40_decomposition/summary_metrics.csv
  7. inspect 60_response_curves/ and 70_optimisation/ if those stages ran

If you are working from a source checkout, python runme.py demo --list and python runme.py demo ... remain equivalent convenience wrappers.

That sequence shows the wrapper value quickly: one YAML config in, one structured run directory out, with the Meridian and meridian-tools artefacts kept in one predictable place.