Meridian is Google's open-source Bayesian MMM: TensorFlow Probability, geo-hierarchical by default, with media effects parameterised by ROI rather than by coefficient. That last choice is the important one — the prior sits directly on the quantity stakeholders argue about.
Install: pip install google-meridian (Python ≥ 3.10; pulls TensorFlow 2.21 and a pinned
tfp-nightly). GPU: google-meridian[and-cuda]. There is also a [jax] extra.
1. When Meridian is the right choice
Choose Meridian when:
- You have a geo panel with population data. Hierarchical geo pooling is its core strength and the main reason to prefer it.
- Reach and frequency matter. Meridian is the only major open framework that models RF natively and answers "what frequency should we buy?".
- You want ROI priors. Calibrating to a geo experiment is a one-line prior change rather than a reverse-engineered coefficient.
- You need organic media and non-media treatments kept structurally separate from paid media.
- You want a built-in EDA guardrail that refuses to fit data with critical problems.
Choose something else when:
- The model is national with no geo dimension — you lose the main advantage and keep the TensorFlow dependency.
- You need a multiplicative (log-link) model. Meridian's media terms are additive.
- You need custom likelihoods, arbitrary priors on arbitrary parameters, or a mediation structure. pymc-marketing is a modelling toolkit; Meridian is a well-designed application.
- You need Fourier seasonality specifically. Meridian uses knots for time effects.
2. Data model
Meridian's InputData distinguishes variable kinds explicitly — the structural feature
that stops a price column from acquiring a ROAS.
| Slot | Dims | Meaning |
|---|---|---|
kpi |
(geo, time) | Outcome. kpi_type is "revenue" or "non_revenue" |
revenue_per_kpi |
(geo, time) | Value per KPI unit; turns a non-revenue KPI's ROI into money |
population |
(geo,) | Required for geo models; enables per-capita scaling |
media |
(geo, media_time, channel) | Paid exposure (impressions, GRPs) |
media_spend |
(geo, time, channel) | Paid cost |
reach, frequency, rf_spend |
(geo, ·, rf_channel) | Reach-and-frequency channels |
organic_media |
(geo, media_time, channel) | Unpaid activity with carryover |
organic_reach, organic_frequency |
Organic RF | |
non_media_treatments |
(geo, time, channel) | Price, promo, distribution |
controls |
(geo, time, variable) | Confounders |
n_media_times >= n_times: media may extend earlier than the KPI so pre-window exposure
drives adstock into the modelled period. This is a genuine advantage — most frameworks
lose the first l_max periods to a cold start.
from meridian.data import load
coord_to_columns = load.CoordToColumns(
time="date", geo="geo", kpi="revenue", population="population",
revenue_per_kpi=None,
media=["tv_grps", "yt_impressions"], media_spend=["tv_spend", "yt_spend"],
reach=["ctv_reach"], frequency=["ctv_frequency"], rf_spend=["ctv_spend"],
organic_media=["email_sends"],
non_media_treatments=["price_index", "acv"],
controls=["competitor_spend", "consumer_confidence"],
)
loader = load.DataFrameDataLoader(
df=df, kpi_type="revenue", coord_to_columns=coord_to_columns,
media_to_channel={"tv_grps": "TV", "yt_impressions": "YouTube"},
media_spend_to_channel={"tv_spend": "TV", "yt_spend": "YouTube"},
)
data = loader.load()
Loaders: DataFrameDataLoader, CsvDataLoader, XrDatasetDataLoader. The panel must be
rectangular — every (geo, time) cell present.
National models use a single constant geo. Everything works; the hierarchy is inert.
3. ModelSpec
from meridian.model import spec as model_spec
spec = model_spec.ModelSpec(
prior=prior, # PriorDistribution
media_effects_dist="log_normal", # or "normal"; geo random effects
hill_before_adstock=False,
max_lag=8,
unique_sigma_for_each_geo=False,
media_prior_type="roi", # roi | mroi | contribution | coefficient
rf_prior_type="roi",
roi_calibration_period=None, # (n_media_times, n_media_channels) bool
rf_roi_calibration_period=None,
organic_media_prior_type="contribution", # contribution | coefficient
organic_rf_prior_type="contribution",
non_media_treatments_prior_type="contribution",
non_media_baseline_values=None, # float | "min" | "max" per channel
knots=None,
baseline_geo=None,
holdout_id=None, # bool mask; excludes KPI, keeps media
control_population_scaling_id=None,
non_media_population_scaling_id=None,
adstock_decay_spec="geometric", # "geometric" | "binomial" | per-channel map
saturation_spec="hill", # "hill" | "none" | per-channel map
enable_aks=False, # automatic knot selection
)
The four prior types
media_prior_type |
Prior on | Use when |
|---|---|---|
"roi" (default) |
Return per unit spend | You have ROI beliefs or experiments. Default choice. |
"mroi" |
Marginal ROI at current spend | You care about the next pound, not the average |
"contribution" |
Share of outcome | You believe a channel drives ~x% of sales |
"coefficient" |
beta_m directly |
You are porting a coefficient-parameterised model |
roi_calibration_period restricts the ROI prior to the window a test actually covered —
essential when a channel was tested in one quarter only.
Knots: the most consequential setting
knots controls the flexibility of time effects, which is Meridian's baseline.
knots=Noneon a geo model means one knot per time period — the most flexible baseline available, able to absorb almost any variation media might otherwise explain.knots=Noneon a national model means 1 (a constant).knots=kplaces k equally spaced knots;knots=[0, 25, 51]places them explicitly.enable_aks=Trueselects the number automatically; it errors ifknotsis also set.
Never leave knots=None on a geo model without deciding it. Fewer knots means a
stiffer baseline and more variance available for media; more knots means the opposite.
This is a prior about how much marketing does, expressed as a smoothing parameter. Fit at
two settings and compare the media share before choosing.
Adstock and saturation
adstock_decay_spec: "geometric" or "binomial", globally or per channel. There is no
delayed/Weibull option — map a delayed request to "binomial", which has a delayed peak,
and expect a slightly different carryover shape from an equivalent pymc-marketing model.
saturation_spec: "hill" or "none", globally or per channel. "none" is right for
channels genuinely in their linear range.
hill_before_adstock=False (default) applies adstock first. Does not apply to RF channels.
4. Priors
PriorDistribution holds a TFP distribution per parameter family. Defaults verified
against 1.8.0:
| Parameter | Default | Meaning |
|---|---|---|
roi_m, roi_rf |
LogNormal(0.2, 0.9) |
ROI; median ≈ 1.2, 90% range ≈ 0.3–5.3 |
mroi_m, mroi_rf |
LogNormal(0.0, 0.5) |
Marginal ROI |
contribution_m/rf/om/orf |
Beta(1, 99) |
Contribution share; mean 1% |
contribution_n |
TruncatedNormal(0, 0.1, -1, 1) |
Non-media contribution, can be negative |
beta_m, beta_rf, beta_om, beta_orf |
HalfNormal(5) |
Coefficients (non-negative) |
eta_m/rf/om/orf |
HalfNormal(1) |
Geo-level random-effect scale |
gamma_c, gamma_n |
Normal(0, 5) |
Control and non-media coefficients |
xi_c, xi_n |
HalfNormal(5) |
Their geo random-effect scales |
alpha_m/rf/om/orf |
Uniform(0, 1) |
Adstock decay |
ec_m, ec_om |
TruncatedNormal(0.8, 0.8, 0.1, 10) |
Hill half-saturation |
ec_rf, ec_orf |
LogNormal(0.7, 0.4) shifted by 0.1 |
Hill half-saturation, RF |
slope_m, slope_om |
Deterministic(1.0) |
Hill slope fixed → concave |
slope_rf, slope_orf |
LogNormal(0.7, 0.4) |
Hill slope, RF (S-curve allowed) |
knot_values |
Normal(0, 5) |
Time effects |
tau_g_excl_baseline |
Normal(0, 5) |
Geo intercepts vs baseline geo |
sigma |
HalfNormal(5) |
Residual sd |
Note slope_m is deterministic at 1.0: paid media gets a concave Hill curve, not an
S-curve, unless you override it. RF channels do allow an S-curve, which is the right
default given how frequency behaves.
Helpers for stating a prior the way a human would:
from meridian.model import prior_distribution as pd
pd.lognormal_dist_from_range(low=1.0, high=6.0, mass_percent=0.9) # "ROAS is 1-6, 90% sure"
pd.lognormal_dist_from_mean_std(mean=3.0, std=1.0)
import numpy as np, tensorflow_probability as tfp
tfd = tfp.distributions
# Channel order must match data.media_channel exactly.
prior = pd.PriorDistribution(roi_m=tfd.LogNormal([0.5, 0.2], [0.4, 0.9], name="roi_m"))
5. Fitting
from meridian.model import model
mmm = model.Meridian(input_data=data, model_spec=spec)
mmm.sample_prior(500)
mmm.sample_posterior(n_chains=4, n_adapt=500, n_burnin=500, n_keep=1000, seed=1)
health = mmm.review() # post-fit health checks -> mmm.health_summary
# or: mmm.sample_posterior_and_review(...)
model.save_mmm(mmm, "model.pkl")
n_chains accepts a list (e.g. [2, 2]) to split sampling into separate calls and cap
memory. posterior_thinning() reduces a large posterior for downstream analysis.
The EDA guardrail. Meridian runs its own checks before fitting and refuses to proceed
on critical findings. Check types: PAIRWISE_CORRELATION, STANDARD_DEVIATION,
MULTICOLLINEARITY, KPI_INVARIABILITY, COST_PER_MEDIA_UNIT,
VARIABLE_GEO_TIME_COLLINEARITY, POPULATION_CORRELATION, PRIOR_PROBABILITY,
DATA_ADEQUACY. Read mmm.eda_outcomes rather than working around a refusal — the
checks map closely onto the problems that produce confidently wrong MMMs.
6. Analysis
from meridian.analysis import analyzer, optimizer, summarizer, visualizer
an = analyzer.Analyzer(mmm)
an.rhat_summary(bad_rhat_threshold=1.2)
an.predictive_accuracy()
an.summary_metrics() # ROI, mROI, CPIK, contribution, effectiveness
an.baseline_summary_metrics()
an.negative_baseline_probability() # check this before believing any ROI
an.incremental_outcome(...)
an.roi(); an.marginal_roi(); an.cpik()
an.response_curves(spend_multipliers=np.linspace(0, 2, 20))
an.adstock_decay(); an.hill_curves()
an.optimal_freq() # RF channels only
an.expected_vs_actual_data(split_by_holdout_id=True)
negative_baseline_probability() exists because the failure is common: a negative
baseline means the model is borrowing from an impossible counterfactual to pay media, and
every ROI downstream is inflated.
CPIK (cost per incremental KPI) is the non-revenue counterpart of ROI — the right headline metric when the KPI is signups or policies.
opt = optimizer.BudgetOptimizer(mmm)
res = opt.optimize(fixed_budget=True, budget=1_000_000,
spend_constraint_lower=0.3, spend_constraint_upper=0.3,
use_optimal_frequency=True)
res.output_optimization_summary("optimization.html", ".")
summarizer.Summarizer(mmm).output_model_results_summary("summary.html", ".")
Scenarios: fixed_budget=True (reallocate a fixed pot), fixed_budget=False with
target_roi or target_mroi (flexible budget to a return threshold). The second is the
more useful question and the one most teams never ask.
Visualizers: ModelDiagnostics, ModelFit, MediaEffects, MediaSummary,
ReachAndFrequency — each produces Altair charts and the DataFrames behind them.
7. Meridian ↔ pymc-marketing
| Concept | Meridian | pymc-marketing |
|---|---|---|
| Geo panel | native, population-weighted | dims=("geo",) |
| Media prior | ROI / mROI / contribution / coefficient | coefficient (saturation_beta) |
| Adstock | geometric, binomial | geometric, delayed, Weibull CDF/PDF, binomial |
| Saturation | Hill (slope fixed at 1 for paid media) | logistic, Hill, MM, tanh, root, log |
| Time effects | knots | Fourier, LinearTrend, HSGP |
| Reach & frequency | native + optimal frequency | not modelled |
| Organic media | own slot | channel_columns + role discipline |
| Non-media treatments | own slot | control_columns |
| Experiment calibration | ROI prior + roi_calibration_period |
add_lift_test_measurements (likelihood) |
| Link function | additive only | identity or log |
| Pre-period media | n_media_times > n_times |
not supported |
| Custom priors | fixed parameter families | any Prior on any parameter |
| Backend | TensorFlow Probability | PyMC / PyTensor |
Porting caveats. A delayed adstock has no exact Meridian equivalent; Fourier seasonality has no equivalent at all; a log-link model cannot be ported. Expect different numbers, and reconcile on the decision (which channels to grow) rather than on the point estimates.
agent_mmm.backends.get_backend("meridian").translate(spec, priors=...) generates the
code and lists every spec feature Meridian cannot express.
8. Common failures
| Symptom | Cause |
|---|---|
| Fit refused before sampling | EDA guardrail found a critical issue — read mmm.eda_outcomes |
| Baseline absorbs almost everything | knots=None on a geo model; set an explicit number |
| ROI posterior ≈ ROI prior | The channel is not identified (flat spend, collinearity). Widen, or test |
negative_baseline_probability is high |
Missing driver; every ROI is inflated |
| Loader errors on shape | Panel is not rectangular, or media/KPI time axes disagree |
| ROI in KPI units, not money | Non-revenue KPI without revenue_per_kpi |
| A price variable appears with a ROI | It was loaded as media instead of non_media_treatments |
| Frequency recommendation missing | Channel loaded as media rather than reach/frequency |