Overview and Workflow

Use the scenario planner when you want to compare whole plans rather than run a single low-level optimisation call.

The planner combines three things:

• typed scenario specifications
• a Python comparison service
• a supported workspace app for fitted results directories

If you need the low-level optimiser instead, see Budget Optimisation.

For the supported beta entry points and current limits, see Supported Surface.

What the planner compares

The retained planner supports three scenario types:

Planner units versus optimiser units

The most important distinction is budget units.

For example, if a four-period scenario has a total budget of 900_000, the planner converts that to per-period units internally before it calls the wrapper or response sampler.

Requested and evaluated windows

Each scenario has a requested window from start_date to end_date.

For simulated scenarios, the evaluated window can be longer than the requested window when you set include_carryover=True. Abacus extends the synthetic future path so lagged adstock effects can continue after the requested end date.

The planner reports both windows in the metadata output.

Historical overlap for current scenarios

CurrentScenarioSpec is strict about history.

Its requested window must overlap observed data. Abacus does not reinterpret a future-only window as “use the latest history instead”.

Typical workflow

The common workflow is:

1. Fit PanelMMM.
2. Build one or more scenario specs.
3. Either run ScenarioPlanner.compare(...) or launch the workspace app from the fitted run directory.
4. Inspect the comparison tables, save workspaces, and export the planning outputs you need.

Minimal example

from abacus.scenario_planner import (
    CurrentScenarioSpec,
    ManualAllocationScenarioSpec,
    ScenarioPlanner,
)

planner = ScenarioPlanner(mmm)

comparison = planner.compare(
    [
        CurrentScenarioSpec(
            name="Current baseline",
            start_date="2025-01-06",
            end_date="2025-02-24",
        ),
        ManualAllocationScenarioSpec(
            name="Manual plan",
            start_date="2025-03-03",
            end_date="2025-03-24",
            noise_level=0.0,
            include_carryover=False,
            allocation={
                "channel_1": 420_000.0,
                "channel_2": 280_000.0,
                "channel_3": 200_000.0,
            },
        ),
    ]
)

For the full API, see Python API.

How the planner differs from post-model summaries

The scenario planner does not reuse mmm.summary tables directly. Instead, it builds comparison tables that are specific to planning:

• totals
• channels
• contributions_over_time
• allocations
• metadata

See Comparison Outputs.

Common pitfalls

• Mixing up total horizon spend and per-period spend
• Using a future-only window in CurrentScenarioSpec
• Forgetting that carryover can extend the evaluated window

Scenario Specifications

This page documents the public spec classes under abacus.scenario_planner.

Most users create one of the three concrete scenario specs:

• CurrentScenarioSpec
• ManualAllocationScenarioSpec
• FixedBudgetOptimizedScenarioSpec

Abacus also exposes shared base models such as HistoricalReferenceScenarioSpec and SimulatedScenarioSpec, but you do not normally instantiate those directly.

Shared fields

All public scenario specs inherit these core fields:

If you do not set scenario_id, Abacus derives one by slugifying name.

Scenario IDs must be unique within one ScenarioPlanner.compare(...) call.

CurrentScenarioSpec

Use CurrentScenarioSpec for a historical reference plan.

from abacus.scenario_planner import CurrentScenarioSpec

spec = CurrentScenarioSpec(
    name="Current baseline",
    start_date="2025-01-06",
    end_date="2025-02-24",
)

Requirements:

• the requested window must overlap observed data
• no allocation or budget inputs are needed

Shared simulated-scenario fields

ManualAllocationScenarioSpec and FixedBudgetOptimizedScenarioSpec both inherit these fields:

Set noise_level=0.0 when you want deterministic realised spend paths.

ManualAllocationScenarioSpec

Use ManualAllocationScenarioSpec when you already know the total allocation you want to simulate.

from abacus.scenario_planner import ManualAllocationScenarioSpec

spec = ManualAllocationScenarioSpec(
    name="Manual reallocation",
    start_date="2025-03-03",
    end_date="2025-03-24",
    noise_level=0.0,
    include_carryover=False,
    allocation={
        "channel_1": 420_000.0,
        "channel_2": 280_000.0,
        "channel_3": 200_000.0,
    },
)

Supported allocation shapes

allocation can be:

• a dict of {channel: total_budget} for ("channel",) budgets only
• an xarray.DataArray
• a DataArraySpec

For panel budgets such as ("geo", "channel") or ("geo", "brand", "channel"), use xarray.DataArray or DataArraySpec.

Dict allocations must match the model’s channel coordinates exactly. Missing or extra keys raise ValueError.

FixedBudgetOptimizedScenarioSpec

Use FixedBudgetOptimizedScenarioSpec when you want Abacus to optimise the allocation.

from abacus.scenario_planner import FixedBudgetOptimizedScenarioSpec

spec = FixedBudgetOptimizedScenarioSpec(
    name="Optimised plan",
    start_date="2025-03-03",
    end_date="2025-03-24",
    noise_level=0.0,
    include_carryover=False,
    total_budget=900_000.0,
)

Optimisation fields

The default response_variable is "total_media_contribution_original_scale".

Default bound derivation

If you do not pass budget_bounds, Abacus derives them from historical reference spend.

For each omitted relative constraint side, Abacus uses 0.3. That gives the default Meridian-style bounds:

• lower bound: scaled reference spend × (1 - 0.3)
• upper bound: scaled reference spend × (1 + 0.3)

If historical reference spend sums to zero, Abacus cannot derive those default bounds and raises ValueError.

Supported budget_bounds shapes

budget_bounds can be:

• a dict of {channel: (lower, upper)} for ("channel",) budgets only
• an xarray.DataArray
• a DataArraySpec

For xarray or DataArraySpec, the dims must be (*budget_dims, "bound") with "lower" and "upper" values on the bound dimension.

budget_distribution_over_period

Both simulated scenario types support budget_distribution_over_period.

The object must:

• have dims ("date", *budget_dims)
• contain one weight per scenario period
• sum to 1 across date for every budget cell

The date coordinates can be:

• integer positions 0 .. num_periods - 1, or
• exact dates that match the requested scenario window

If the dates do not match the scenario window exactly, Abacus raises ValueError.

DataArraySpec

Use DataArraySpec when you want JSON-friendly or YAML-friendly planner inputs.

from abacus.scenario_planner import DataArraySpec

allocation = DataArraySpec(
    values=[[420_000.0, 280_000.0], [300_000.0, 200_000.0]],
    dims=("geo", "channel"),
    coords={
        "geo": ["UK", "FR"],
        "channel": ["channel_1", "channel_2"],
    },
)

Abacus materialises DataArraySpec as an xarray.DataArray before it validates dims and coordinates.

Common pitfalls

• Reusing the same scenario_id twice in one comparison
• Using dict allocations or dict bounds for panel budgets
• Passing an allocation or bounds object with missing coordinates
• Providing a budget_distribution_over_period that does not sum to 1

Python API

Use ScenarioPlanner when you want to evaluate one scenario or compare multiple scenarios from Python.

The public API lives under abacus.scenario_planner.

For the recommended entry points and supported beta scope, see Supported Surface.

Prerequisite

ScenarioPlanner requires a fitted PanelMMM with idata.

If you construct the planner before fitting, Abacus raises ValueError.

Create a planner

from abacus.scenario_planner import ScenarioPlanner

planner = ScenarioPlanner(mmm)

You can inspect the modelled channel names with:

channels = planner.channels

Supported workspace helpers

If you want to work with the supported app from Python, use these helpers:

Example:

from abacus.scenario_planner import create_app_from_results_dir

app, run_context, workspace_service, workspace = create_app_from_results_dir(
    "results/timeseries_20260308_144627",
    workspace_name="Timeseries planning workspace",
)

app.run(host="127.0.0.1", port=8050, debug=False)

These helpers expect a fitted results directory with run_manifest.json and a fit-stage idata artefact.

When available, the loader rebuilds the model from in-run metadata config artifacts in this order:

1. 00_run_metadata/config.resolved.yaml
2. 00_run_metadata/config.original.yaml
3. the copied config file under 00_run_metadata/
4. run_manifest.json["config_path"] as fallback

The returned run_context records both config_path and config_provenance_type so callers can tell which source was used.

Residual portability risk remains if the chosen config still points to dataset files outside the saved run directory.

Evaluate one scenario

Use evaluate(...) when you want one scenario result:

from abacus.scenario_planner import ManualAllocationScenarioSpec, ScenarioPlanner

planner = ScenarioPlanner(mmm)

result = planner.evaluate(
    ManualAllocationScenarioSpec(
        name="Manual plan",
        start_date="2025-03-03",
        end_date="2025-03-24",
        noise_level=0.0,
        include_carryover=False,
        allocation={
            "channel_1": 420_000.0,
            "channel_2": 280_000.0,
            "channel_3": 200_000.0,
        },
    )
)

print(result.totals)
print(result.channels)
print(result.metadata)

evaluate(...) returns ScenarioResult with:

• totals
• channels
• contributions_over_time
• allocation
• metadata

Compare multiple scenarios

Use compare(...) when you want one combined comparison object:

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

planner = ScenarioPlanner(mmm)

comparison = planner.compare(
    [
        CurrentScenarioSpec(
            name="Current baseline",
            start_date="2025-01-06",
            end_date="2025-02-24",
        ),
        ManualAllocationScenarioSpec(
            name="Manual plan",
            start_date="2025-03-03",
            end_date="2025-03-24",
            noise_level=0.0,
            include_carryover=False,
            allocation={
                "channel_1": 420_000.0,
                "channel_2": 280_000.0,
                "channel_3": 200_000.0,
            },
        ),
        FixedBudgetOptimizedScenarioSpec(
            name="Optimised plan",
            start_date="2025-03-03",
            end_date="2025-03-24",
            noise_level=0.0,
            include_carryover=False,
            total_budget=900_000.0,
        ),
    ]
)

print(comparison.totals)
print(comparison.allocations)

compare(...) returns ScenarioComparison with:

• totals
• channels
• contributions_over_time
• allocations
• metadata

Unlike ScenarioResult, the combined object uses the plural allocations.

Programmatic workspace orchestration

Use WorkspaceService when you want to work with saved planner workspaces from Python.

Common operations include:

• load_workspace(...)
• save_workspace(...)
• clone_workspace(...)
• update_workspace_metadata(...)
• create_template_draft(...)
• replace_draft(...)
• evaluate_draft(...)
• run_sensitivity_sweep(...)
• export_workspace_bundle(...)

Example:

from abacus.scenario_planner import load_workspace_bundle

run_context, workspace_service, workspace = load_workspace_bundle(
    "results/timeseries_20260308_144627",
)

draft = workspace_service.create_template_draft(
    workspace=workspace,
    scenario_type="fixed_budget_optimized",
)
workspace = workspace_service.replace_draft(workspace, draft)
workspace = workspace_service.evaluate_draft(workspace, draft)
workspace_service.save_workspace(
    workspace,
    action="evaluate_draft",
    changed_scenario_ids=[draft.scenario_id],
)

WorkspaceService defaults to synchronous jobs when you instantiate it directly. The supported app uses ThreadedScenarioPlannerJobRunner automatically.

Prepare data for a client UI

Use to_store_payload() when you want a JSON-friendly version of the comparison tables:

payload = comparison.to_store_payload()

This method converts datetime columns to YYYY-MM-DD strings and returns a dict of record lists that works well for client-side UIs such as Dash.

Background-job helpers

For custom integrations, WorkspaceService also exposes queue/apply methods:

• submit_draft_evaluation(...)
• apply_draft_evaluation_job(...)
• submit_sensitivity_sweep(...)
• apply_sensitivity_sweep_job(...)

Use these only when you need the same background-job pattern as the supported app. For most scripted flows, the blocking methods are simpler.

Relationship to the low-level wrapper

ScenarioPlanner uses PanelBudgetOptimizerWrapper internally for simulated scenarios, but its public contract is different:

• you pass total horizon budgets and allocations
• the planner converts them to per-period units internally
• the planner returns comparison tables rather than raw optimiser objects

If you want direct access to optimize_budget(...) or sample_response_distribution(...), use Budget Optimisation instead.

Common pitfalls

• Passing per-period spend into ManualAllocationScenarioSpec or FixedBudgetOptimizedScenarioSpec
• Expecting duplicate scenario_id values to be allowed in compare(...)
• Forgetting that result.allocation and comparison.allocations use different attribute names

Comparison Outputs

ScenarioPlanner returns structured planning tables rather than a single optimiser object.

This page explains the output objects and the meaning of each table.

Output objects

ScenarioComparison is a row-wise concatenation of the individual scenario results, with scenario identifiers added to every table.

totals

totals has one row per scenario.

It includes:

• scenario_id
• scenario_name
• scenario_type
• total_spend
• contribution_mean
• contribution_median
• contribution_hdi_94_lower
• contribution_hdi_94_upper
• efficiency_metric
• efficiency_mean
• efficiency_median
• efficiency_hdi_94_lower
• efficiency_hdi_94_upper

efficiency_metric is ROAS for revenue targets and CPA for conversion targets.

channels

channels has one row per (scenario, channel).

It includes:

• scenario identifiers
• channel
• spend
• spend_share
• spend_per_period
• contribution summary columns
• contribution-per-period columns
• efficiency summary columns
• efficiency_metric

The planner aggregates non-channel panel dims before it builds this table. For example, a (geo, channel) model still returns one row per channel here.

contributions_over_time

contributions_over_time has one row per (scenario, date, channel).

It includes:

• scenario identifiers
• date
• channel
• contribution_mean
• contribution_median
• contribution_hdi_94_lower
• contribution_hdi_94_upper

Like channels, this table aggregates non-channel panel dims before summarising.

allocations

allocations keeps the original allocation grain.

It includes:

• scenario identifiers
• the allocation dims, such as channel, geo, or brand
• allocation
• realized_spend

For current scenarios, allocation is the summed historical spend over the reference window. For simulated scenarios, allocation is the requested total horizon allocation and realized_spend is the realised spend from the response simulation.

metadata

metadata is the audit table for each scenario.

Shared fields include:

• scenario_id
• scenario_name
• scenario_type
• start_date
• end_date
• evaluated_start_date
• evaluated_end_date
• num_periods
• target_type
• efficiency_metric

Additional fields depend on scenario type.

Current scenario metadata

Current scenarios add:

• reference_window_dates

Manual scenario metadata

Manual scenarios add:

• requested_total_budget
• total_budget
• reference_window_dates
• budget_unit

Fixed-budget optimised metadata

Optimised scenarios add:

• requested_total_budget
• total_budget
• optimization_success
• optimization_status
• optimization_message
• optimization_objective_value
• reference_window_dates
• budget_unit

Requested versus evaluated windows

The metadata table is the best place to check whether the evaluated window matches the requested window.

When include_carryover=True, the evaluated end date can be later than the requested end_date.

Example inspection

comparison = planner.compare(specs)

totals = comparison.totals
metadata = comparison.metadata

optimised_metadata = metadata.loc[
    metadata["scenario_type"] == "fixed_budget_optimized"
].iloc[0]

print(optimised_metadata["optimization_success"])
print(optimised_metadata["optimization_message"])

to_store_payload()

ScenarioComparison.to_store_payload() converts the comparison tables into a JSON-friendly dict of record lists:

payload = comparison.to_store_payload()

This is the payload format consumed by the supported workspace app.

Common pitfalls

• Reading channels as if it retained non-channel panel dims
• Ignoring metadata when carryover is enabled
• Comparing requested allocation with realised spend without checking the allocations table

Supported Surface

Use this page to understand which Scenario Planner entry points Abacus supports for beta evaluation.

The planner has two primary surfaces:

• a Python comparison API for scripted planning workflows
• a workspace-based Dash app for interactive scenario editing and review

Recommended entry points

Use these entry points in preference order.

Advanced integration surfaces

Abacus also exposes lower-level objects such as:

• create_scenario_planner_dash_app(...)
• ThreadedScenarioPlannerJobRunner
• SynchronousScenarioPlannerJobRunner
• WorkspaceStore

These are public, but they are more implementation-shaped than the recommended entry points above. Use them when you need to embed the planner into a custom application or override the default job runner or storage behaviour.

Results directory contract

The supported launcher and load_workspace_bundle(...) expect a fitted run directory, not raw modelling inputs.

The run directory must include:

When metadata-stage config artifacts are present, Abacus prefers those in-run files when rebuilding the saved PanelMMM:

• 00_run_metadata/config.resolved.yaml
• 00_run_metadata/config.original.yaml
• the copied config file under 00_run_metadata/

Only when those in-run config artifacts are absent does the planner fall back to run_manifest.json["config_path"].

That makes the supported loader more portable when the original config path is no longer available, but it does not guarantee full relocation across machines. The chosen config can still reference dataset files outside the run directory.

The planner can also load these optional optimisation artefacts when they are present:

• 70_optimisation/budget_response_curves.csv
• 70_optimisation/budget_bounds_audit.csv

When these files are available, the app can show saved saturation-reference response-curve and bounds-audit views.

What the app persists

The workspace app stores its own planning state under the fitted run directory:

Workspaces persist:

• workspace metadata such as name, owner, tags, and notes
• draft metadata such as scenario owner, workflow status, approvals, pinning, notes, and tags
• evaluated scenarios
• sensitivity runs
• revision history
• job history
• cache metadata

Background jobs in the supported app

The supported app launches with ThreadedScenarioPlannerJobRunner.

In the current beta:

• draft evaluation runs as a queued background job
• sensitivity sweeps run as queued background jobs
• export remains synchronous, but Abacus still records it in job history

The UI currently tracks one active planner job at a time. Wait for the current evaluation or sweep to finish before starting another one from the app.

Beta scope and current limits

The current supported beta scope is:

• local use against fitted run directories
• file-backed workspace persistence inside the run directory
• interactive drafting, evaluation, comparison, sensitivity sweeps, and export

Current limits to keep in mind:

• the app does not fit or refit PanelMMM
• the launcher starts Dash’s built-in server for local evaluation
• the UI does not yet manage multiple active planner jobs at the same time

Next pages

• Overview and Workflow
• Python API
• Dash App

Dash App

Abacus includes a supported Dash app for workspace-based scenario planning.

Use it when you already have a fitted run directory and want to inspect, edit, evaluate, compare, sweep, and export scenarios without writing the entire workflow by hand.

The app does not fit PanelMMM. It loads an existing fitted run, reuses the saved idata, and evaluates planner scenarios against that fitted model.

For the recommended entry points and beta scope, see Supported Surface.

Install the optional dependencies

python -m pip install -e ".[planner]"

The planner extra installs the Dash and Plotly dependencies used by the UI.

Launch the supported app

Use the supported module launcher for fitted pipeline results:

python -m abacus.scenario_planner \
  --results-dir results/timeseries_20260308_144627

This launcher is the recommended interactive entry point for beta evaluation. It loads the fitted run, opens or seeds a planner workspace, and starts the app with the threaded job runner used by the supported UI.

Useful flags:

• --workspace-id to open one previously saved workspace
• --workspace-name to control the seeded workspace name
• --current-periods and --future-periods to change the default seeded windows
• --budget-scale to scale the default future budget
• --build-only to validate the run and print a summary without starting Dash
• --host, --port, and --debug for the Dash server

For example:

python -m abacus.scenario_planner \
  --results-dir results/timeseries_20260308_144627 \
  --workspace-id timeseries-20260308-144627-planning-workspace \
  --host 127.0.0.1 \
  --port 8050

Create the app from Python

If you want to embed the UI in your own script, use the supported helper:

from abacus.scenario_planner import create_app_from_results_dir

app, run_context, workspace_service, workspace = create_app_from_results_dir(
    "results/timeseries_20260308_144627",
)

app.run(host="127.0.0.1", port=8050, debug=False)

Abacus also still exposes the lower-level create_scenario_planner_dash_app(...) factory when you already have a ScenarioComparison or ScenarioWorkspace.

What the launcher requires

The supported launcher expects a fitted results directory that contains:

• run_manifest.json
• a fit-stage idata artefact

When the metadata stage is present, the launcher prefers the in-run config artifacts under 00_run_metadata/ and only falls back to run_manifest.json["config_path"] if those files are absent.

In build-only mode, the launcher prints the selected config path and its provenance so you can see whether the planner loaded:

• resolved_in_run
• original_in_run
• copied_in_run
• external_manifest_path

This makes the launcher more portable when the original config path no longer exists, but the chosen config can still fail if it references dataset files that are not present on the current machine.

When these optional files are present, the app also loads them for richer UI views:

• 70_optimisation/budget_response_curves.csv
• 70_optimisation/budget_bounds_audit.csv

What the UI includes

The current app has five tabs:

• Plan Setup for run context, workspace metadata, saved workspaces, draft inventory, and the launch path into Scenario Builder
• Scenario Builder for editing one draft at a time and evaluating it back into the workspace
• Review for cross-scenario totals, deltas, rankings, movers, and approval/export readiness
• Explain for response curves, operating-region views, lift comparisons, and diagnostics/audit surfaces
• Export for reproducible export bundles and deterministic sensitivity output selection

What the app saves

The workspace app persists planning state under the fitted run directory:

This means a planner session stays attached to one fitted run.

Plan Setup page

The Plan Setup page shows the loaded run context and the active planner workspace. It also lets you:

• open a different saved workspace for the same run
• clone the current workspace into a new planning branch
• edit workspace name, owner, tags, and notes
• inspect revision history, job history, and evaluation-cache reuse
• launch the current workspace into Scenario Builder

This page is the planner launch surface: planning context stays visible first, while operational details remain available through collapsed secondary sections.

Scenario Builder page

The Scenario Builder page is interactive. You can:

• create current, manual_allocation, and fixed_budget_optimized drafts
• duplicate or delete drafts
• edit names, dates, carryover, budget, and manual allocations
• capture scenario owner, workflow status, approvals, pinning, tags, and notes
• evaluate and save the draft back into the workspace

When a draft has been evaluated, the page shows planned versus realised spend, allocation detail, and scenario metadata. When a draft has changed but has not yet been re-evaluated, the page shows a draft preview instead.

Scenario Builder page in the supported Dash app.

Review page

The Review page focuses on scenario-to-scenario trade-offs and review readiness. It includes:

• scenario summary cards
• overview and delta charts
• channel comparison charts
• scenario ranking and top-mover tables
• contribution-over-time comparisons

Compare Scenarios page in the supported Dash app.

Explain and Export pages

The remaining tabs build on the same workspace state:

• Explain overlays scenario reference points on the saved Stage 70 saturation-only response-curve artefact when available
• the plotted marker position follows the saved reference curve at each scenario’s spend-per-period level
• marker hover text also shows the actual evaluated average contribution so you can compare the scenario outcome with the reference-curve position
• Explain also surfaces scenario warnings, optimiser status, bounds audit, allocation reconciliation, operating-region views, and lift comparisons
• Export writes reproducible bundles under the run directory and exposes any saved sensitivity output selections

Background jobs

The supported app runs draft evaluation and sensitivity sweeps as background jobs.

In the current beta:

• the app queues draft evaluation and sensitivity sweeps
• the UI polls the active job and refreshes the workspace when the job completes
• export runs synchronously, but Abacus still records it in job history

The UI currently tracks one active planner job at a time. Finish the current evaluation or sweep before starting another one.

Practical guidance

• Launch the app from a fitted results directory, not from raw input data.
• Use separate cloned workspaces for competing planning narratives.
• Re-evaluate a draft after changing dates, budget, or allocation values.
• Check both requested and evaluated windows when carryover is enabled.
• Review the Diagnostics page before exporting or sharing a scenario set.
• Treat the built-in launcher as a local beta workflow rather than a production deployment surface.

Common pitfalls

• Launching the app without installing .[planner]
• Pointing the launcher at a directory without run_manifest.json and fit artefacts
• Expecting the app to fit a model from scratch
• Interpreting a draft preview as evaluated output before clicking Evaluate and Save
• Starting a second evaluation or sweep while another planner job is still running