Math 00: The MMM as a Generative Model

The framework's BayesianMMM is, at heart, a generative story for the weekly KPI: a recipe that, given parameters \(\theta\), generates a plausible sales series. Fitting the model is running that recipe backwards. This page — the index of the math series — writes the recipe down: the full additive mean function \(\mu_t\), the Normal likelihood, every default prior, and the spend-to-contribution pipeline. Then it runs the recipe forward, live in your browser: one draw from the prior, decomposed into its additive pieces, with a button to draw again. The six pages that follow (01–06) each make one term of this equation precise.

The generative equation

The framework first standardizes the KPI so all priors live on a common, unit-free scale:

and maps back at the end with \(y_t = s_y\,\tilde y_t + \bar y\). Everything downstream is modeled on \(\tilde y_t\). The heart of the model is a single additive linear predictor \(\mu_t\) — the model's noiseless expectation for the standardized KPI in period \(t\):

The media term is where the marketing nonlinearity lives. It sums, over channels \(c\), a coefficient \(\beta_c\) times a saturated, adstocked version of that channel's spend:

Adstock spreads each week's spend forward in time — carryover (math 01). Saturation then imposes diminishing returns. The framework's core saturation is the exponential curve (this is model/base.py's _build_model — not a Hill curve; the Hill mention in the docstrings is a reference alternative only, a distinction math 02 dissects and stress 01 shows can cost +38% on total media):

clipped via \(\exp(\mathrm{clip}(-\lambda_c u, -20, 0))\) so it stays numerically in \([0, 1)\). The controls term is plain linear: \(\text{controls}_t = \sum_j \beta^{\text{ctrl}}_j z_{j,t}\). Finally the likelihood — the generative step that adds irreducible noise:

That is the entire forward model. To generate data: sample \(\theta\) from the priors, compute \(\mu_t\), draw \(\tilde y_t\). We do exactly that below.

Every symbol in \(\mu_t\)

The priors — the model's beliefs before seeing data

A Bayesian model is its priors plus its likelihood. These are the exact priors the framework places (verbatim from _build_model in src/mmm_framework/model/base.py), each with a one-line intuition. They are deliberately weakly informative: regularizing enough to keep the sampler well-behaved, loose enough to let the data speak. (If priors are new to you, workshop 01 is the gentler on-ramp; this table is the reference card.)

See the priors rather than just tabulating them. Each density below is built from 30,000 seeded draws with the analytic density overlaid; the dashed line marks the sample mean.

Computed live in your browser — the same math as the notebook (30,000 seeded draws per prior; analytic density overlaid in dark green). Note how much mass the \(\beta\) prior puts above 1, how \(\mathrm{Exp}(0.5)\) favors gentle saturation rates, and how \(\mathrm{Beta}(2,2)\) is a symmetric hill centered at \(0.5\).

Deriving the \(\mathrm{Gamma}(\mu, \sigma) \to\) shape/scale conversion

The framework parameterizes the channel prior by its mean \(\mu\) and standard deviation \(\sigma\), but samplers want the canonical shape/scale pair \((k, \theta)\). For a Gamma,

For the framework's \(\mu = 1.5\), \(\sigma = 1.0\) this gives \(k = 2.25\), \(\theta = 0.667\). The notebook asserts this conversion and its round-trip: the 60,000 sampled draws recover mean 1.502 (target 1.5) and standard deviation 1.001 (target 1.0); the \(\mathrm{Exponential}(0.5)\) draws recover mean 1.982 (target 2.0); the \(\mathrm{Beta}(2,2)\) draws recover mean 0.501 (target 0.5). That assertion is what ties the plotted histogram to the stated prior.

The pipeline, drawn

Before any numbers, the shape of the computation. Raw spend enters on the left; each channel is pushed through carryover (adstock) and then diminishing returns (saturation), scaled by its coefficient \(\beta_c\), summed across channels, added to the baseline, and a Normal draw turns the deterministic \(\mu_t\) into the observed KPI.

The generative pipeline: spend → carryover → diminishing returns → \(\times\beta\) → sum + baseline → KPI. Fitting runs this diagram backwards.

Simulate one draw from the prior — live

The payoff of an overview: run the generative model once. Below, your browser samples one value of every parameter from its exact framework prior — \(\beta_c \sim \mathrm{Gamma}(\mu{=}1.5, \sigma{=}1.0)\), \(\lambda_c \sim \mathrm{Exponential}(0.5)\), intercept, trend slope, two Fourier coefficients, \(\sigma\) — plus a per-channel geometric decay \(\alpha_c \sim \mathrm{Beta}(2,2)\) (illustratively wider than the shipped default prior \(\mathrm{Beta}(1,3)\); the default model estimates exactly such an \(\alpha_c\) in-graph since June 2026 — math 01). It then pushes a fixed two-year, four-channel spend plan through adstock → saturation → \(\beta\), assembles \(\mu_t\), adds \(\mathrm{Normal}(0, \sigma)\) noise, and decomposes the result. The spend plan never changes between draws — only the parameters do, so what you are watching is pure prior-predictive diversity.

Computed live in your browser — the same forward math as the notebook. Dots are the observed draw \(\tilde y_t\); the line is the noiseless mean \(\mu_t\); the band is \(\mu_t \pm \sigma\). The gap between dots and line is the likelihood. The first draw uses a hand-picked seed so every channel's saturation lands mid-curve (the notebook does the same with its seed 83) — it is one honest draw of the true priors, not a re-shaped distribution. Re-draws are unfiltered: expect occasional wild worlds. That diversity is the prior.

Computed live in your browser. The additive identity drawn as a stacked area: baseline plus each channel's contribution stacks up exactly to \(\mu_t\); the white dots add the noise back. This is the picture an MMM tries to recover from data — except in real life only the dots are observed, and the colors must be inferred. (A small constant display offset keeps the stack positive; it cancels from every identity.)

Many prior draws of a single channel's response curve

The same forward model, viewed as a response curve: for one channel, how does contribution \(\beta \cdot \mathrm{sat}(x) = \beta\,(1 - e^{-\lambda x})\) rise with adstocked spend \(x\)? Each light line below is a fresh draw of \((\beta, \lambda)\) from the priors; together they are a prior-predictive envelope for the shape of diminishing returns. Every curve is monotone increasing (because \(\beta > 0\)) and concave / saturating (because of the \(1 - e^{-\lambda x}\) form) — the two structural commitments the priors bake in before any data arrive. Both are notebook-asserted facts.

Computed live in your browser — the same math as the notebook (60 seeded prior draws). The dark line is the prior-mean curve (\(\beta{=}1.5\), \(\lambda{=}2\)). Whether this concave-only family is the right commitment is exactly what math 02 and stress 01 interrogate.

Computed live in your browser. The marginal return at the prior-mean parameters: \(\frac{d}{dx}\,\beta(1 - e^{-\lambda x}) = \beta \lambda e^{-\lambda x}\) — another dollar buys less and less. At \(x = 0\) the marginal return is \(\beta\lambda = 3.00\) (prior means), decaying toward zero as spend grows. Average vs marginal return is the decision lever workshop 05 builds on.

Roadmap — the rest of the series

Every term in \(\mu_t\) that we just sampled gets a dedicated page. Math 01 derives carryover: the geometric IIR recurrence vs normalized FIR kernels, the \(1/(1-\alpha)\) multiplier, and the parametric default vs the legacy Beta(2,2) blend weight. Math 02 owns diminishing returns: \(1 - e^{-\lambda u}\) vs Hill, the half-saturation point \(\ln 2 / \lambda\), and marginal ROAS. Math 03 builds the baseline: Fourier seasonality and three trend families (linear, piecewise/Prophet, B-spline). Math 04 assembles the full Bayesian machine: priors → prior predictive → NUTS → convergence diagnostics → posterior intervals → decomposition. Math 05 confronts identifiability — the decay/saturation/\(\beta\) equifinality trap — and shows how a randomized experiment enters as a prior or directly in the likelihood (see also stress 03 and the gauntlet). Math 06 extends the equation itself: NestedMMM mediation, MultivariateMMM cross-effects and correlated residuals, and CombinedMMM as their synthesis. The full system-level reference lives in the technical guide.

The one idea to carry forward: an MMM is a forward recipe for the KPI; fitting is running that recipe backwards. Everything else — carryover, saturation, hierarchy, calibration — is detail on one term of the additive \(\mu_t\), and on the priors that regularize it: