/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/. Hugo en-gb /contributing/architecture/index.html Mon, 01 Jan 0001 00:00:00 +0000 /contributing/architecture/index.html Abacus is structured so that the public MMM API stays small while the implementation can evolve behind stable seams. The most important rule is that PanelMMM is a facade, not the place where new core behaviour should accumulate. For the complete module map, read ARCHITECTURE.md in the repository root. This page summarises the parts that matter most when you are deciding where to put new code. Design Principles PanelMMM stays thin. Constructor normalisation, data prep, graph construction, prediction, calibration, runtime helpers, and serialisation live under abacus/mmm/models/. Compute comes before presentation. Diagnostics, summaries, and plotting should consume structured outputs from the model layer rather than embedding analytical logic in presentation code. Dependencies flow downward. Shared root infrastructure can be imported by MMM modules, but MMM-specific modules should not leak back into the shared layer. Compatibility is deliberate. If you move imports or rename internals, keep facades or compatibility shims where public usage would otherwise break. High-Level Package Layers Layer Purpose Examples Public facades Stable user-facing entry points abacus.mmm.panel, abacus.mmm.plot, abacus.mmm.summary Panel implementation seams Core panel behaviour abacus.mmm.models.panel_config, panel_build, panel_predict, panel_runtime, panel_serialize MMM primitives Reusable modelling building blocks abacus.mmm.components, abacus.mmm.transforms, abacus.mmm.fourier, abacus.mmm.hsgp, abacus.mmm.events Post-fit outputs Diagnostics, summaries, optimisation, plots abacus.mmm.diagnostics, abacus.mmm.summarization, abacus.mmm.optimization, abacus.mmm.plotting Shared root Generic infrastructure used across the package abacus.modeling, abacus.prior, abacus.metrics, abacus.data, abacus.pipeline Where New Code Goes If you are adding… Put it in… Constructor normalisation, dims logic, transform configuration abacus/mmm/models/panel_config.py Data conversion, scaling, Mundlak support, prediction-data prep abacus/mmm/models/panel_data.py PyMC graph construction abacus/mmm/models/panel_build.py Posterior predictive or response-curve sampling abacus/mmm/models/panel_predict.py Serialisation or save/load compatibility abacus/mmm/models/panel_serialize.py and shared helpers in abacus/modeling/io.py Diagnostics compute abacus/mmm/diagnostics/ Summary tables and exported curve summaries abacus/mmm/summarization/ Static charts abacus/mmm/plotting/ Budget optimisation logic abacus/mmm/optimization/ Adstock or saturation behaviour abacus/mmm/components/ and abacus/mmm/transforms/ Shared model-builder infrastructure abacus/modeling/ Dependency Rules Allowed Shared root modules can be imported by MMM modules. abacus/mmm/models/ can depend on MMM primitives and shared root modules. Facades such as panel.py can depend on the extracted panel modules. Plotting, summaries, diagnostics, and optimisation can depend on model outputs and extracted helpers. Avoid Importing panel.py from abacus/mmm/models/*. Adding plotting or summary logic to core model-building modules. Adding MMM-specific behaviour to the shared abacus/modeling/ layer unless it is genuinely reusable. Defaulting to panel.py for new features just because it is visible. Practical Guidance When you touch a feature area, check whether there is already an extracted seam for it before adding a new helper. Examples: /contributing/development-setup/index.html Mon, 01 Jan 0001 00:00:00 +0000 /contributing/development-setup/index.html This page describes the supported local setup for working on Abacus. The project is maintained with local verification scripts rather than a CI-first workflow, so your development environment needs to be able to run linting, pytest, and the packaging smoke checks directly. Prerequisites Python 3.12 A local environment manager such as Conda A writable temporary directory such as /tmp for PyTensor caches and package verification artefacts Create the Development Environment The simplest supported path is the repository environment file: /contributing/testing/index.html Mon, 01 Jan 0001 00:00:00 +0000 /contributing/testing/index.html Abacus uses pytest for automated tests, plus local verification scripts for the broader confidence checks that glue linting, smoke paths, and packaging together. The expected workflow is to run targeted tests while you iterate and then run the wider local verification commands before you finish substantial work. Test Layout Path What it covers tests/test_*.py Shared infrastructure such as model IO, paths, package identity, and root-level helpers tests/mmm/ MMM behaviour at the public surface tests/mmm/models/ Extracted panel implementation seams tests/mmm/components/ Adstock and saturation component behaviour tests/mmm/plotting/ Static plotting helpers and theme/layout behaviour tests/mmm/optimization/ Budget optimisation logic and wrappers tests/mmm/diagnostics/ Structured diagnostics compute tests/mmm/summarization/ Summary/export helpers When you change a specific module seam, add or update tests in the matching test area instead of only asserting through a broad end-to-end test.