Abacus Library API¶

This document outlines the structure and key components of the Abacus Marketing Mix Modelling (MMM) library API.

Overview¶

Abacus provides a framework for building, analysing, and optimising MMMs. The typical workflow involves:

Configuration: Defining model parameters, data sources, and preprocessing steps in a YAML file (see Configuration Guide).
Preprocessing: Using the abacus.prepro subpackage (often invoked by the driver) to load, clean, validate, and transform data into a model-ready format (DataToFit).
Driver Execution: Utilising the abacus.driver.driver.Driver class as the main entry point to orchestrate the process, including loading configuration, running preprocessing, fitting the core model, and generating visualisations/results.
Core Modelling: The abacus.core subpackage handles the underlying Bayesian model definition (using pymc), fitting, decomposition, and optimisation logic.
Sketching Results: The abacus.sketch subpackage generates plots and descriptive summaries based on the model outputs.

Note: Modules starting with _ (e.g., abacus.driver._assess) are internal helpers and not part of the public API.

.pyi files are stub files for static type checking. (i.e. def func(a: int) -> int: ...)

Contains the core model definitions, transformations, and optimisation logic.

Modules

base.py -- includes the foundational BaseMMM class.
build.py -- includes ModelBuilder(ABC) class.
consts.py -- includes model constants used to preprocess the data.
decomp.py -- includes functions for model decomposition (e.g., baseline breakdown).
lift_test.py -- includes functions for integrating lift test data into the model likelihood.
mmm_base.py -- includes the BaseDelayedSaturatedMMM class, providing the core structure for the delayed saturation MMM.
mmm_model.py -- includes the final concrete DelayedSaturatedMMM class, combining base functionality with specific mixins.
model.py -- includes the primary user-facing MMM class, inheriting from BaseMMM and validation mixins.
opt.py -- includes functions for budget optimisation:

calculate_expected_contribution() - Calculate expected contributions using the specified model.
objective_distribution() - Compute the total contribution for a given budget distribution.
optimize_budget_distribution() - Optimize the budget allocation across channels to maximize total contribution.
budget_allocator() - Allocates the budget based on the given method, total budget, channels, parameters, and budget ranges.

ConvMode(str, Enum) class - A generic enumerator for convolution modes.
WeibullType(str, Enum) class - A generic enumerator for Weibull distribution types.
batched_convolution() - Apply a 1D convolution in a vectorized way across multiple batch dimensions.
geometric_adstock() - Geometric adstock transformation.
delayed_adstock() - Delayed adstock transformation.
weibull_adstock() - Weibull Adstocking Transformation.
logistic_saturation() - Logistic saturation transformation.
scale_preserving_logistic_saturation() - Scale preserving logistic transformation.
TanhSaturationParameters(NamedTuple) class - Named tuple for the parameters of the tanh saturation transformation.
TanhSaturationBaselinedParameters(NamedTuple) class - Named tuple for the parameters of the tanh saturation transformation with baseline.
tanh_saturation() - Tanh saturation transformation.
tanh_saturation_baselined() - Tanh saturation transformation with baseline.

transformers.py -- includes various adstock and saturation functions.
utils.py -- includes utility functions like Fourier mode generation and saturation parameter estimation.
mixins/ -- Subdirectory containing mixin classes for scaling, validation etc. (Specific modules not detailed here).

Provides the high-level interface for running the end-to-end MMM workflow.

Modules

driver.py -- includes the main Driver class orchestrating the workflow.
opt.py -- includes functions related to budget optimisation setup and execution.

Handles data loading, validation, cleaning, transformation, and preparation for modelling.

Modules

config.py -- Functions for loading and setting up model configuration.
convert.py -- Functions for converting raw data formats to the internal InputData structure.
data_to_fit.py -- Defines the DataToFit class, representing model-ready data (split, scaled).
decode.py -- Functions for parsing input CSV files based on configuration.
dir.py -- Utilities for creating unique results directories.
input_data.py -- Defines the InputData class, encapsulating raw input metrics.
outliers.py -- Functions for detecting and handling outliers.
prepro.py -- Core preprocessing functions (validation, quality checks, splitting) and scaling classes.
scaler.py -- Defines the SerializableScaler class for consistent scaling.
seas.py -- Includes functions related to seasonality handling (e.g., potentially holiday features, though Prophet dependency is likely removed).
valid.py -- Includes validation mixin classes used by the core MMM class.

Contains functions for validating input data before modelling.

Modules

input_validator.py -- includes functions to check for NaNs, duplicates, date consistency, variance etc.

Responsible for generating plots and descriptive summaries from model inputs and results.

Modules

depict.py -- Functions to describe model training, predictions, inputs, and configuration, often generating text or CSV summaries.
plot_diagnostics.py -- Functions for plotting model diagnostics (predictions vs actuals, trace plots, posterior distributions).
plot_input.py -- Functions for plotting input data characteristics (metrics over time, correlation matrices).
plot_results.py -- Functions for plotting model results (channel contributions, ROI, response curves).

Contains general utility functions used across different subpackages.

Modules

utils.py -- Includes functions for logging setup, seeding, folder creation, git info, and data highlighting/comparison utilities.