/index.html Abacus is a Bayesian MMM library built on PyMC and PyTensor. It provides PanelMMM for multi-market panel modelling, structured YAML-driven configuration, a staged pipeline runner, and budget optimisation — all designed for reproducible, production-grade MMM workflows. Where to start You want to… Start here Install and run your first model Installation → Quickstart: Python Build a model from YAML config Quickstart: YAML → YAML Configuration Run the full staged pipeline Quickstart: Runner → Runner Overview Understand the model equation Model Overview → Adstock and Saturation Interpret results and outputs Post-Modeling → Response Curves Optimise a budget allocation Budget Optimisation → Interpreting Results Learn the econometrics behind it FAQ — explainers for practitioners Hugo en-gb /getting-started/index.html Mon, 01 Jan 0001 00:00:00 +0000 /getting-started/index.html This section helps you install Abacus and run your first model. Start here if you want to: set up a local environment from this repository fit PanelMMM directly from Python build a model from YAML run the structured pipeline against one of the bundled demo configs Pages Installation — Set up Abacus from a local checkout with Conda or pip, add optional extras, and verify the install. Quickstart: Python API — Fit PanelMMM directly from a pandas dataset in Python. Quickstart: YAML Builder — Construct a model from a YAML config and combined dataset. Quickstart: Pipeline Runner — Run the staged pipeline from Python, the thin CLI, or the bundled demo launcher. /data-preparation/index.html Mon, 01 Jan 0001 00:00:00 +0000 /data-preparation/index.html This section explains how to prepare X and y for PanelMMM. It covers the required columns, how panel rows are organised when you use dims, and how Abacus scales channels and the target before fitting. Pages Input Data Requirements — Required X and y inputs, column roles, alignment rules, and common input errors. Panel Data Layout — How to structure rows for no panel dims, one dim such as geo, or multiple dims such as geo and brand. Scaling and Preprocessing — What Abacus scales automatically, how Scaling works, and what to preprocess yourself. /model-specification/index.html Mon, 01 Jan 0001 00:00:00 +0000 /model-specification/index.html This section explains how PanelMMM is defined: the model structure, media transforms, priors, panel dimensions, optional time variation, and calibration hooks. Pages Model Overview - The actual PanelMMM mean structure, scaled-space formulation, and optional components. Adstock and Saturation - Supported media transforms, their priors, and the adstock_first composition order. Priors and Configuration - Default prior keys, model_config, transform-prior overrides, and directional control priors. Time-Varying Parameters - How time_varying_intercept and time_varying_media use SoftPlusHSGP. Seasonality and Trends - Built-in yearly seasonality plus custom Fourier, trend, and event effects. Panel Dimensions - How dims change the shape of the data and parameters. Calibration - Lift-test and cost-per-target calibration for a built model. /model-fitting/index.html Mon, 01 Jan 0001 00:00:00 +0000 /model-fitting/index.html This section covers the core fitting workflow for PanelMMM: running MCMC, checking priors before fitting, and saving a fitted model for later reuse. Pages Fitting the Model - How fit() works, how sampler settings are applied, and what you get back. Prior Predictive Checks - How to sample and inspect prior predictive draws before fitting. Save and Load - How to persist a fitted model to NetCDF and rebuild PanelMMM from saved InferenceData. /post-modeling/index.html Mon, 01 Jan 0001 00:00:00 +0000 /post-modeling/index.html Use this section after fitting PanelMMM. It covers posterior predictive checks, diagnostics, contribution analysis, response curves, efficiency metrics, and the tabular summary surfaces that Abacus exposes from fitted InferenceData. Pages Posterior Predictive: Sample fitted or future predictions and compare them with observed data where available. Diagnostics: Run design-matrix, MCMC, and predictive diagnostics and export machine-readable reports. Contributions and Decomposition: Inspect channel, baseline, control, seasonality, and event contributions. Response Curves: Sample and summarise posterior saturation and adstock curves, and understand the runner’s forward-pass direct contribution artefacts. ROAS and Metrics: Calculate ROAS, CPA-style metrics, spend tables, and predictive error metrics. Summary and Export: Work with MMMSummaryFactory, HDI settings, time aggregation, and DataFrame export. /optimization/index.html Mon, 01 Jan 0001 00:00:00 +0000 /optimization/index.html This section covers Abacus budget optimisation workflows for fitted PanelMMM models. It explains the low-level optimisation wrapper, how to inspect optimisation outputs. For the higher-level planner service and Dash UI, see Scenario Planning. Pages Budget Optimisation - How to run PanelBudgetOptimizerWrapper, set bounds and masks, and define spend over a future window. Interpreting Optimisation - How to read the allocation output, inspect simulated response samples, and use the pipeline optimisation artefacts. Scenario Planning - How to compare current, manual, and fixed-budget optimised scenarios with the planner service and optional Dash UI. /scenario-planning/index.html Mon, 01 Jan 0001 00:00:00 +0000 /scenario-planning/index.html Use this section when you want to compare historical, manual, and optimised future plans with abacus.scenario_planner. The scenario planner is a higher-level planning surface than the low-level optimisation wrapper. It works in total horizon spend units, returns structured comparison tables, and includes a supported workspace app for fitted runs. Pages Supported Surface: The recommended planner entry points, fitted-run contract, persisted workspace state, and beta limits. Overview and Workflow: What the planner does, how it differs from low-level optimisation, and how scenario windows work. Scenario Specifications: The public scenario spec classes, allocation shapes, bounds, and budget distributions. Python API: How to use ScenarioPlanner.evaluate(...) and the supported workspace helpers from Python. Comparison Outputs: The structure and meaning of ScenarioResult, ScenarioComparison, and the output tables. Dash App: How to launch the supported workspace UI from a fitted run, work with saved workspaces, and understand background jobs. /pipeline/index.html Mon, 01 Jan 0001 00:00:00 +0000 /pipeline/index.html This section covers the structured abacus.pipeline runner: how it loads a config and dataset, executes the retained stage sequence, and writes reproducible run artefacts to disk. Pages Runner Overview - How run_pipeline(...) works, which stages run, and when the optimisation stage is skipped. YAML Configuration - Which YAML keys the runner consumes and how they map to model build, data loading, holidays, and optimisation. CLI Reference - The thin python -m abacus.pipeline.runner interface and its supported flags. Output Directory Schema - The run directory layout, manifest schema, stage statuses, and main artefacts. Extending the Runner - How to add a stage or wire in reporting without bypassing the manifest and artifact helpers. /faq/index.html Mon, 01 Jan 0001 00:00:00 +0000 /faq/index.html This section collects longer-form answers to recurring MMM, Bayesian, and panel-econometrics questions that come up when practitioners move from classical econometrics to PanelMMM. The pages are written for technical readers who already understand regression, panel data, and causal inference, but want the Abacus framing. Core model concepts Adstock and Saturation for Econometricians — Why modern MMM uses carryover and diminishing-returns transformations instead of log-linear shortcuts. Causal Identification in Marketing Mix Modelling — What an MMM can and cannot identify causally from observational data. HSGP (Hilbert Space Gaussian Process) for Econometricians — How flexible time-varying effects map to familiar basis and shrinkage ideas. Baseline vs Media Trade-Offs in MMM — Why baseline terms and media terms can trade attribution against each other even when fit quality looks similar. Priors and model checking Bayesian Priors for Econometricians — How priors relate to constraints, penalties, and regularisation you already use in classical work. Prior Predictive Checks for Econometricians — How to test whether your configured priors imply plausible behaviour before fitting. Posterior Predictive Checks for Econometricians — How to judge whether the fitted model reproduces the data well enough to trust downstream interpretation. Computation and comparison MCMC Diagnostics for Econometricians — How to read trace plots, R-hat, ESS, and divergences. Model Comparison for Econometricians — How to think about ELPD, LOO-CV, posterior predictive checks, and their limitations. Panel specification Do We Need a Mundlak Specification Test in Abacus? — Why Abacus uses posterior inspection of CRE terms rather than a frequentist Mundlak test. Suggested reading order If you are new to Bayesian MMM, a practical sequence is: /contributing/index.html Mon, 01 Jan 0001 00:00:00 +0000 /contributing/index.html Use this section when you are changing Abacus itself rather than using it as a library. The contributor docs focus on three questions: How do you get a working local environment? Where should new code live? What do you need to run before you consider a change complete? Abacus is intentionally local-first. The source of truth for development workflow is the combination of the repo Makefile, ARCHITECTURE.md, and the verification scripts in sandbox/. /reference/index.html Mon, 01 Jan 0001 00:00:00 +0000 /reference/index.html This section is a hand-curated reference for the retained public Abacus API. It focuses on stable entry points that users are expected to import directly. It does not try to document every internal module under abacus.mmm.models, abacus.mmm.summarization, or abacus.pipeline.stages. For task-oriented workflows, use the main documentation sections first. Use this reference when you need the exact import path, object name, or the scope of a public surface. Main module groups Module Primary public surface abacus.mmm.panel PanelMMM abacus.mmm Adstock, saturation, Fourier, HSGP, and trend classes abacus.mmm.optimization PanelBudgetOptimizerWrapper and advanced optimisation helpers abacus.mmm.builders.yaml build_mmm_from_yaml(...) abacus.pipeline PipelineRunConfig, run_pipeline(...), PipelineRunResult abacus.scenario_planner Planner specs, ScenarioPlanner, ScenarioComparison abacus.data.idata MMMIDataWrapper, schema helpers, and idata utilities Pages PanelMMM: Core model import path, constructor surface, lifecycle methods, and bound properties. Post-Fit Facades: mmm.data, mmm.summary, mmm.diagnostics, mmm.plot, and direct factory imports. Transforms and Supporting Types: Adstock, saturation, Fourier, HSGP, trend, and scaling types. Optimisation API: PanelBudgetOptimizerWrapper and the exported advanced optimisation helpers. Builders and Pipeline: YAML builder, structured pipeline entry points, and run result objects. Scenario Planner API: Scenario spec classes, planner service objects, and the Dash app entry point. Additive Effects and Events: Advanced extension points for mu_effects and dated event modelling. Recommended starting points If you are building and fitting a model in code, start with PanelMMM. If you are reading fitted outputs, start with Post-Fit Facades. If you are building from YAML or running the structured runner, start with Builders and Pipeline. If you are comparing plans, start with Scenario Planner API.