Dash App

Deprecated experimental application. Use the abacus.scenarios Python API or recipe CLI for current scenario workflows.

The rest of this page is a historical record of the abacus-dashboard prototype. Installation commands, launch procedures, screenshots, beta limits and compatibility plans below describe that prototype, not a current product recommendation or release commitment.

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 current statistical API and estimator limits, see Supported Surface.

Interface version and screenshots

This guide describes the workspace interface in the companion source declaring abacus-dashboard version 0.1.0a0, checked on 24 September 2026. The five-page navigation and the Explain → Diagnostics and audit section were checked against that source. This identifies the documented interface; it does not certify an installed build or a published release.

The screenshots below show an earlier read-only demonstration interface with four navigation entries. Their exact app version was not recorded. They are historical illustrations, not screenshots of the documented five-page workspace. Follow the page names and procedures in the text.

Legacy app-layer imports and launchers under abacus.scenario_planner still work as advisory compatibility facades, but new dashboard code should use abacus_dashboard.*.

Install the dashboard package

python -m pip install -e ../abacus -e ../abacus-dashboard

The dashboard package owns the Dash, Plotly, Flask, Werkzeug, and dash-ag-grid dependencies used by the app.

Launch the dashboard app

Use the companion module launcher for fitted pipeline results:

python -m abacus_dashboard \
  --results-dir results/timeseries_20260308_144627

This launcher is the workspace 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 UI.

To inspect a retained YAML-recipe result without opening or creating a workspace, use the mutually exclusive read-only evidence-review mode:

python -m abacus_dashboard \
  --scenario-bundle \
  results/timeseries_20260308_144627/scenario_planner/recipes/<recipe-output>

Before the dashboard renders, this mode verifies every manifest checksum and cross-checks the versioned payload, scenario validation evidence, and fitted estimator manifest. It renders all five retained record collections. It does not fit, refit, evaluate, optimise, mutate evidence, or infer total outcomes, profits, causal effects, or model approval.

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

--workspace-id, --workspace-name, --current-periods, --future-periods, and --budget-scale apply only with --results-dir. The evidence-review mode rejects them rather than silently ignoring them.

For example:

python -m abacus_dashboard \
  --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 dashboard helper:

from abacus_dashboard.app 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)

For a verified, immutable recipe bundle, use the read-only helper instead:

from abacus_dashboard.app import create_app_from_scenario_bundle

app, evidence = create_app_from_scenario_bundle(
    "results/timeseries_20260308_144627/scenario_planner/recipes/<recipe-output>",
)

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

The dashboard package also exposes the lower-level create_scenario_planner_dash_app(...) factory when you already have a ScenarioComparison or ScenarioWorkspace.

New statistical scenario code should use abacus.scenarios. Legacy abacus.scenario_planner app-layer imports remain available as advisory compatibility facades and emit DeprecationWarnings that name the replacement abacus_dashboard.* import.

What the launcher requires

The dashboard 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 artefacts 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 documented workspace interface has five pages:

  • 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:

Path What Abacus saves
scenario_planner/workspaces/ workspace JSON files and compact manifests
scenario_planner/cache/ cached evaluated scenarios and cache index
scenario_planner/exports/ export bundles and zipped archives

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.

Historical illustration of allocation review:

Historical read-only Scenario Builder showing planned and realised spend Historical read-only Scenario Builder showing planned and realised spend

Earlier demonstration interface; exact version unrecorded. This view compares planned allocation with realised spend and shows requested and evaluated windows. It does not illustrate the current draft-editing controls. Use the workspace’s Scenario Builder procedure above for editing and evaluation.

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

Historical illustration of scenario comparison:

Historical Compare Scenarios page showing contribution totals and differences Historical Compare Scenarios page showing contribution totals and differences

Earlier demonstration interface; exact version unrecorded. Its Compare Scenarios page illustrates totals and differences relative to a baseline. In the documented workspace, use Review for this task. These displayed example values are not evidence that a proposed allocation improves outcomes.

Explain and Export pages

The remaining pages 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 dashboard app runs draft evaluation and sensitivity sweeps as background jobs.

In this 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.
  • Open Explain → Diagnostics and audit before exporting or sharing a scenario set. Diagnostics is a historical screenshot label, not a separate page in the documented workspace.
  • Treat the dashboard launcher as a local beta workflow rather than a production deployment surface.
  • Use abacus-dashboard as the dashboard app home; treat abacus.scenario_planner dashboard paths as legacy compatibility.

Legacy compatibility window

Compatibility remains advisory with no removal before Abacus 4.0. Removal of legacy dashboard app-layer facades under abacus.scenario_planner also requires:

  • 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

Common pitfalls

  • Launching the app without installing the companion abacus-dashboard package
  • 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