Evaluate retained scenarios

A version-1 scenario recipe evaluates a completed runner model without refitting or rereading its training CSV. It supports an observed current window and a future manual_allocation, both for the fixed estimand posterior_media_contribution_original_scale.

The bundled FE recipe supplies complete labels, dates and values. First fit the geo_fe demo and inspect its diagnostics, then supply the retained model to the scenario command. A reduced workflow check can use uv run python runme.py --demo geo_fe --quick --no-ai-advisor; its completion does not establish posterior qualification.

uv run --no-sync python runme.py   --scenario-recipe data/demo/geo_fe/scenario_recipe.yml   --model results/<run>/20_model_fit/model.nc   --scenario-output results/scenario-001

This is a command template: <run> is the retained directory name. Scenario mode requires all three options. The source run_manifest.json must identify a completed run, and the model path must have the structured runner layout. An existing scenario destination is rejected.

Allocation and time semantics

The recipe has scenario_contract_version: "1", the fixed estimand, and a scenarios list. Each entry names its type and exact date window. Manual entries provide an allocation with dims, coords and values containing every fitted channel and panel label exactly once.

Manual recipe allocations use allocation_unit: total_horizon_spend, whereas the Python response API uses per-period amounts. The recipe divides spend evenly across decision periods. Its noise_level: 0.0 preserves the requested allocation.

include_last_observations supplies factual carry-in from the fitted model; the history must be complete and contiguous with the future window. include_carryover extends the scoring window to include trailing response. Record both policies because two scenarios with different windows can answer different questions even if their total spend matches.

Evidence bundle

The resolved recipe and validation report accompany model/run identities, checksums, scenario_posterior.nc, contribution and total CSVs, a semantic JSON payload and an artefact manifest. The bundle is assembled before exposing the completed destination. Posterior summaries include means, medians and 94% highest-density intervals.

A current-versus-future comparison can change dates and histories as well as spend. It is not automatically a controlled incremental contrast. Inspect the actual estimand and hold all other assumptions consistent for the comparison you intend. Log-link response semantics also remain in force.

The recipe contract does not add a solver, new-unit prediction, a workspace service, or an AMMM3 PanelMMM compatibility interface. Evaluation is conditional on the retained fit and does not qualify a budget intervention.

FE workflow verification

The repaired runner completed a two-chain geo_fe check with 300 tuning steps and 300 retained draws per chain, seed 42, followed by both bundled scenarios on 1 October 2026. Prior plots now compare within-unit contrasts; posterior predictions retain their outcome-level interpretation (src/ammm/mmm/plotting/diagnostics.py:206, working tree after 7cb7f20). The fit failed diagnostic gates. Use this result as workflow evidence and assess the retained posterior separately before making decisions.

Implementation reference at 7cb7f20: src/ammm/mmm/scenarios.py:160, src/ammm/mmm/scenarios.py:734.