Quickstart

This guide takes you from a fresh install to your first completed run in under five minutes using the bundled demo data.

1. Run a bundled demo

List the available demos:

meridian-tools demo --list

Output:

timeseries
geo_panel

Run the timeseries demo:

meridian-tools demo timeseries

When run from the source checkout, this creates a dated run directory under runs/demos/. When run from an installed package, the default output root is ./runs/demos/ relative to your current working directory. Each demo produces a full staged output layout.

2. Inspect the run directory

After the demo completes, find the created run directory:

ls runs/demos/

You will see a directory like demo-timeseries_20260402_073500/. The name comes from the demo’s project.name (demo-timeseries) plus a timestamp. The bundled demos now default to full-sample fits, so LOO and WAIC outputs are available in the assessment stage by default. Inside:

demo-timeseries_20260402_073500/
  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
    model_results_summary.html
    loo_summary.json
    waic_summary.json
  40_decomposition/
    summary_metrics.csv
    summary_metrics.nc
  60_response_curves/
    response_curves.csv
    response_curves.nc
  70_optimisation/
    optimisation_summary.html
    optimised_data.csv

3. Read the key outputs

Start with the manifest:

cat runs/demos/demo-timeseries_*/run_manifest.json | python -m json.tool | head -20

Check the diagnostics bundle:

cat runs/demos/demo-timeseries_*/30_model_assessment/diagnostics_bundle.json | python -m json.tool

View the model results summary by opening the HTML file in your browser:

# Linux
xdg-open runs/demos/demo-timeseries_*/30_model_assessment/model_results_summary.html

# macOS
open runs/demos/demo-timeseries_*/30_model_assessment/model_results_summary.html

Inspect the decomposition CSV:

head runs/demos/demo-timeseries_*/40_decomposition/summary_metrics.csv

4. Run your own config

Create a YAML config file (e.g. project.yml):

project:
  name: my-first-run

data:
  path: ./my_data.csv
  kpi_type: revenue
  coord_to_columns:
    time: week
    geo: market
    kpi: revenue
    media: [impressions_tv, impressions_search]
    media_spend: [spend_tv, spend_search]

fit:
  n_chains: 4
  n_adapt: 500
  n_burnin: 500
  n_keep: 1000
  seed: 42

validation:
  strategy: blocked_tail
  holdout_size: 8

exports:
  export_predictive_accuracy: true
  export_review_summary: true
  export_model_selection: true

Run it:

meridian-tools run --config project.yml --output-dir runs

5. Next steps