Scenario Planner API

The preferred statistical scenario API lives under abacus.scenarios.

Use it when you want to compare current, manual, and fixed-budget optimised plans in total horizon spend units. FE and CRE support current and manual plans only; their fixed-budget optimisation path remains blocked.

For workflow guidance, see Scenario Planning.

Main import path

from abacus.scenarios import (
    SCENARIO_CONTRACT_VERSION,
    CurrentScenarioSpec,
    DataArraySpec,
    FixedBudgetOptimizedScenarioSpec,
    ManualAllocationScenarioSpec,
    ScenarioArtifactBundle,
    ScenarioComparison,
    ScenarioPlanner,
    ScenarioRecipe,
    ScenarioResult,
    evaluate_scenario_recipe,
    load_scenario_recipe,
    run_scenario_recipe,
)

The package also exports shared base types:

  • BaseScenarioSpec
  • HistoricalReferenceScenarioSpec
  • SimulatedScenarioSpec
  • ScenarioSpec

abacus.scenario_planner remains available as a compatibility namespace for existing statistical imports. New statistical scenario code should import from abacus.scenarios.

Dashboard entrypoints and UI compatibility modules have been removed. Application wrappers consume the statistical APIs and evidence contracts.

Scenario spec classes

Main concrete spec types:

TypePurpose
CurrentScenarioSpecHistorical reference scenario
ManualAllocationScenarioSpecUser-defined future allocation
FixedBudgetOptimizedScenarioSpecFixed-budget optimised future allocation
DataArraySpecJSON-friendly or YAML-friendly xarray representation

Shared fields across the concrete specs include:

  • name
  • start_date
  • end_date
  • scenario_id

Planner service objects

Main service types:

TypePurpose
ScenarioPlannerEvaluate and compare scenarios for a fitted PanelMMM
ScenarioResultOutput object from evaluate(...)
ScenarioComparisonCombined output object from compare(...)
ScenarioRecipeVersioned collection of historical and manual specifications
ScenarioArtifactBundleRetained recipe output paths plus the in-memory comparison

ScenarioPlanner

planner = ScenarioPlanner(mmm)

Main methods:

MethodPurpose
evaluate(spec)Evaluate one scenario and return ScenarioResult
compare(specs)Evaluate several scenarios and return ScenarioComparison

Useful property:

PropertyMeaning
channelsModelled channel names

ScenarioResult

ScenarioResult exposes:

  • spec
  • totals
  • channels
  • contributions_over_time
  • allocation
  • metadata

ScenarioComparison

ScenarioComparison exposes:

  • totals
  • channels
  • contributions_over_time
  • allocations
  • metadata

It also provides:

payload = comparison.to_store_payload()

to_store_payload() returns a JSON-friendly payload for client-side UIs. The payload contains a scalar contract_version plus record lists for the comparison tables. The current contract value is exported as SCENARIO_CONTRACT_VERSION from abacus.scenarios.

Recipe functions

FunctionPurpose
load_scenario_recipe(path)Parse and validate a versioned YAML recipe
evaluate_scenario_recipe(...)Evaluate an in-memory recipe against a fitted model and retain its evidence
run_scenario_recipe(...)Load a fitted pipeline run, evaluate a YAML recipe, and retain its evidence
write_scenario_artifacts(...)Persist an evaluated comparison as an immutable, checksummed bundle

The command-line equivalent of run_scenario_recipe(...) is:

python -m abacus.scenarios \
  --results-dir results/<fitted-run> \
  --recipe data/demo/geo_cre/scenario_recipe.yml

Workspaces, jobs and protocol

See Scenario Workspaces and IDE Protocol for exported workspace and job types, revision conflicts and the PlannerIdeService JSON contract.