Changelog

All notable changes to meridian-tools are documented in this file.

The format is based on Keep a Changelog.

[Unreleased]

No unreleased changes.

[0.4.0] — 2026-07-29

Added

  • YAML media priors — YAML-driven media prior configuration for roi_m, mroi_m, and alpha_m, including scalar priors, per-channel overrides, and support for Normal, LogNormal, TruncatedNormal, and Beta distributions.
  • Prior distribution export — prior_distributions.json is written in the model-fit stage so authored and resolved Meridian prior distributions are captured with run artefacts.
  • Config templates — Commented starter configs under templates/ cover minimal, standard, media-prior, and blocked-tail validation workflows.
  • Geo panel demo artefacts — Stored geo_panel demo run outputs now live under runs/demos/, so reference artefacts cover both bundled pipeline shapes.
  • Meridian compatibility inventory — Project documentation now records the Meridian 1.5.3 files and private sampler seams that must be reviewed before changing the dependency pin.
  • Validation-spec v2 bindings — Stored validation specs now bind coordinate and data-shape metadata so refresh and rolling-origin execution can fail closed when input data no longer matches the stored contract.
  • Ephemeral input provenance — Manifest v4 runs record provenance for the exact temporary snapshot loaded by Meridian.
  • Canonical verification gate — scripts/verify_release.py now runs the constrained release checks for dependency consistency, compile/import health, CLI help, Ruff, mypy, Hugo docs, and the coverage suite.

Changed

  • Strict run names — Pipeline run names must now match ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$; path separators, whitespace, Unicode, and relative path segments are rejected before run directories are created.
  • CSV loader YAML validation — data.coord_to_columns and channel mapping fields now fail earlier with wrapper-owned errors when shapes, keys, or channel ordering are inconsistent with Meridian loader contracts.
  • ModelSpec array validation — Known boolean array kwargs forwarded through model_spec.kwargs now reject scalars, ragged lists, strings, and numeric stand-ins before Meridian model construction; their ranks and loaded-data shapes are also checked before model construction.
  • Model-selection resilience — Optional LOO/WAIC exports now capture ArviZ warnings and degrade to explicit status artifacts for unexpected ArviZ or artifact-write failures instead of failing the whole run.
  • Bounded rolling-origin execution — Each split fits only through its test boundary and records the exact validation window used for execution.
  • Manifest v4 completion integrity — Completed runs validate required manifest artefacts as existing, contained regular files before the final manifest is written.
  • Release documentation — Architecture, schema, release-baseline, and generated Hugo documentation now describe manifest v4, validation-spec v2, bounded reproducibility, and the canonical constrained gate.

Fixed

  • Launcher empty-result handling — The source-checkout launcher now raises a clear runtime error if the pipeline unexpectedly returns no run result.
  • Run directory collisions — Same-second runs with the same logical name now use deterministic suffixes such as _001 instead of failing on an existing directory.
  • Private destination JSON writes — Newly created destination JSON files now use private file modes.
  • Temporary snapshot cleanup — Temporary Meridian input snapshots are removed after handoff while hashed provenance for the loaded bytes is kept.
  • Finite numeric configuration — Non-finite numeric, analysis, and nested Meridian configuration values are rejected before they reach Meridian.
  • Repo-owned Hugo configuration — The repository-owned Hugo language setting no longer emits a deprecation warning on the supported Hugo line.
  • Protobuf compatibility bound — The supported dependency boundary now constrains protobuf<7 because Meridian 1.5.3 serialises boolean TensorFlow Probability parameters through an int proto path that protobuf 7 rejects.

[0.3.0] — 2026-04-24

Changed

  • CLI single source of truth — runme.py now delegates directly to meridian_tools.cli, removing duplicate root-level argument parsing.
  • Typed runner state — Pipeline orchestration now uses PipelineContext for shared stage state.
  • Shared posterior sampling — Runner posterior sampling keyword mapping is centralized in one helper.
  • Lifecycle comparison schema — Run comparison rows are generated from declarative comparison field descriptors.
  • Meridian compatibility pin — The package pins google-meridian[schema]==1.5.3, and log-likelihood reconstruction refuses unvalidated Meridian versions.
  • Static analysis tooling — Development extras now include mypy, and Ruff enables additional complexity, simplification, and Ruff-specific rule families.

Fixed

  • Optimized Python safety — Validation helpers now use explicit exceptions instead of assert for runtime invariants.
  • Shared confidence validation — Response curve and optimisation configs share one confidence_level validator.
  • Export coercion documentation — NetCDF attribute coercion now documents its input-to-output type mapping.

[0.2.0] — 2026-04-07

Added

  • Docs site build — Hugo-based website documentation under docs-site/, generated from the repository Markdown set by docs-site/build_content.py.
  • Manifest v3 provenance — Explicit input_data_provenance capture for stored runs and lifecycle refresh or compare workflows.
  • Typed failure boundaries — ConfigPreflightError, ValidationExecutionContractError, and PipelineRunFailure distinguish wrapper-owned preflight, validation contract misuse, and post-directory runtime failures.
  • Bounded live verification — An opt-in Meridian real-fit smoke route gated behind MERIDIAN_TOOLS_ENABLE_REAL_FIT=1.
  • Module-path CLI contract — Explicit support and regression coverage for python -m meridian_tools.cli ....

Changed

  • Shared launch flow — meridian-tools and the repo-root runme.py launcher now share one launch flow for config loading, preflight checks, progress reporting, and terminal success or failure output.
  • Packaged demo assets — Bundled demo configs and datasets are resolved from packaged _demo_data, so demo runs work from installed wheels as well as source checkouts.
  • Default demo fit mode — Bundled demos now default to full-sample fits (validation.strategy: none), so loo_summary.json and waic_summary.json are generated by default and 10_validation is recorded as skipped.
  • Refresh contract — Stored-run refresh now reloads from the saved resolved config while preserving the original source config copy in run metadata.
  • Lifecycle compare semantics — Compare now distinguishes legacy runs without dataset provenance from real dataset changes.
  • Documentation layout — Public documentation is reorganised under docs/ into getting-started, guides, reference, concepts, and project sections.

Fixed

  • Structured public entrypoint failures — Missing or invalid config paths in public entrypoints now produce structured failure output instead of raw Python tracebacks unless --traceback is used.
  • Relative-path refresh — Refreshing a stored run with relative data.path input no longer depends on the original source config location remaining present on disk.
  • Partial-run failure reporting — Failed runs that already created an output directory now report the concrete run directory, manifest path, and failing stage through the CLI and runme.py.
  • Docs-site theme resolution — Hugo builds resolve the Relearn theme through a pinned module dependency instead of requiring a local theme checkout.

[0.1.0] — 2026-04-02

Added

  • Typed YAML configuration — Pydantic-validated config with extra="forbid" strictness for all sections: project, data, model_spec, fit, validation, exports, response_curves, optimisation.
  • Staged pipeline runner — Sequential execution through 00_run_metadata, 10_validation, 20_model_fit, 30_model_assessment, 40_decomposition, 60_response_curves, 70_optimisation with manifest persistence after each stage.
  • Validation orchestration — blocked_tail and rolling_origin time-series validation strategies with auto-generated holdout masks. Authored holdout passthrough through model_spec.kwargs.holdout_id.
  • Diagnostics bundling — diagnostics_bundle.json manifest with optional predictive_accuracy.csv and review_summary.json exports.
  • Bayesian model selection — Compatibility-aware LOO and WAIC computation through ArviZ, with automatic log-likelihood reconstruction for fitted Meridian models. Graceful degradation for incompatible runs through structured ModelSelectionError with reason codes.
  • Response curves export — Configurable spend multiplier grid with NetCDF and CSV outputs.
  • Optimisation export — Fixed-budget and relative-budget optimisation with full artefact set including allocation charts.
  • Plot exports — PNG plot artefacts through Altair/vl-convert for model fit, diagnostics, decomposition, response curves, and optimisation stages.
  • Lifecycle management — load_run_record, list_run_records, build_refresh_run_config, compare_run_records for post-run analysis and reproducible refresh workflows.
  • CLI — meridian-tools run and meridian-tools demo subcommands with lightweight imports for fast startup.
  • Bundled demos — timeseries and geo_panel reference workflows with packaged data and configs.
  • Manifest versioning — Support for manifest versions 0, 1, and 2 with backward-compatible deserialisation.
  • Comprehensive test suite — 218 tests across 15 test files covering configuration, validation, pipeline execution, exports, diagnostics, model selection, lifecycle, and demos.