Adoption brief for agency teams
This page is the short version for teams deciding whether to use
meridian-tools around Google Meridian.
Recommendation
Use meridian-tools when a Meridian model must be reviewed, compared,
refreshed, or handed to another team. Do not use it merely because it exists.
A one-off exploratory Meridian fit with no model comparison, no refresh
cadence, and no handoff requirement may not need this layer.
What breaks without the wrapper?
| Agency requirement | Risk without meridian-tools |
|---|---|
| Defensible model choice | Candidate specifications can be selected on in-sample fit or visual judgement alone. |
| Reviewable execution | The authored config, resolved config, data provenance, and tool versions can be scattered across notebooks and local state. |
| Client or internal handoff | The output set can depend on analyst habits rather than a stable directory contract. |
| Refresh cadence | A later run may not know exactly which config, data snapshot, validation window, or package versions created the earlier result. |
| Compatibility management | Meridian upgrades can silently affect wrapper-owned seams such as schema serialisation or log-likelihood reconstruction unless they are gated. |
What does adoption cost?
| Cost | Practical meaning |
|---|---|
| Dependency boundary | Use the supported Meridian-compatible environment rather than arbitrary package versions. |
| YAML config | Each project needs one reviewed config that defines data mapping, model settings, fit settings, validation, and exports. |
| Run directory convention | Analysts inspect staged artefacts under a predictable output directory rather than ad hoc notebook outputs. |
| Validation discipline | Holdout choices are declared before fitting and validation fits are not reused as final production fits. |
What does the team get?
| Need | Evidence produced |
|---|---|
| What was modelled? | config.source.yaml and input-data provenance. |
| What actually ran? | config.resolved.yaml and run_manifest.json. |
| Which model should we prefer? | LOO/WAIC summaries, pointwise diagnostics, and model_comparison.csv for compatible final fits. |
| Can another analyst inspect it? | Staged assessment, decomposition, response-curve, optimisation, and manifest artefacts. |
| Can it be refreshed later? | Lifecycle helpers that load, compare, and refresh stored run records. |
What does it not do?
meridian-tools does not replace Meridian’s model, sampler, or diagnostics. It
does not make every run perfectly reproducible across all hardware and future
dependency versions. It records the conditions needed for a bounded,
reviewable rerun.
It also does not make LOO or WAIC meaningful for holdout-fitted models. Those
runs deliberately record model_selection_status.json instead.
Decision rule
Adopt the wrapper when the model is part of an operating process. Skip it when the work is a disposable exploration.
If the model is going to a client, an internal reviewer, or a future refresh, the wrapper is not overhead. It is the audit trail.