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.

The experimental abacus-dashboard application is deprecated. Legacy dashboard imports under abacus.scenario_planner remain as advisory compatibility facades; their warnings refer to that deprecated package.

Scenario spec classes

Main concrete spec types:

Type Purpose
CurrentScenarioSpec Historical reference scenario
ManualAllocationScenarioSpec User-defined future allocation
FixedBudgetOptimizedScenarioSpec Fixed-budget optimised future allocation
DataArraySpec JSON-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:

Type Purpose
ScenarioPlanner Evaluate and compare scenarios for a fitted PanelMMM
ScenarioResult Output object from evaluate(...)
ScenarioComparison Combined output object from compare(...)
ScenarioRecipe Versioned collection of historical and manual specifications
ScenarioArtifactBundle Retained recipe output paths plus the in-memory comparison

ScenarioPlanner

planner = ScenarioPlanner(mmm)

Main methods:

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

Useful property:

Property Meaning
channels Modelled 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

Function Purpose
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

Dashboard app entry points

Historical reference only: the experimental abacus-dashboard application is deprecated. The entry points and former removal criteria below record its prototype interface, not a current recommendation or release commitment.

from abacus_dashboard.dash_app import create_scenario_planner_dash_app

Use it like this:

app = create_scenario_planner_dash_app(comparison)
app.run(debug=True)

The Dash app visualises a precomputed ScenarioComparison. It does not fit models.

Legacy app-layer imports such as abacus.scenario_planner.dash_app.create_scenario_planner_dash_app still work as compatibility facades, but they are advisory only. No removal will happen before Abacus 4.0, and removal requires all of the following:

  • a documented abacus-dashboard release and install path
  • passing dashboard smoke checks against the supported Abacus scenario contract
  • zero known internal imports using legacy dashboard paths under abacus.scenario_planner