Scenario Planner API

The scenario planner API lives under abacus.scenario_planner.

Use it when you want to compare current, manual, and fixed-budget optimised plans in total horizon spend units.

For workflow guidance, see Scenario Planning.

Main import path

from abacus.scenario_planner import (
    CurrentScenarioSpec,
    DataArraySpec,
    FixedBudgetOptimizedScenarioSpec,
    ManualAllocationScenarioSpec,
    ScenarioComparison,
    ScenarioPlanner,
    ScenarioResult,
)

The package also exports shared base types:

  • BaseScenarioSpec
  • HistoricalReferenceScenarioSpec
  • SimulatedScenarioSpec
  • ScenarioSpec

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(...)

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.

Dash app entry point

The optional UI lives in a separate module:

from abacus.scenario_planner.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 run the planner itself.