Each function in mediamix implements a published method or a documented convention. This page says which one, where it comes from, and what choices the implementation makes, so a result can be reproduced, cited or challenged.
| Function | Method | Source |
|---|---|---|
adstock_geometric() |
Geometric (Koyck) carryover | Broadbent (1979); Koyck (1954) |
adstock_delayed() |
Delayed-peak carryover | Jin et al. (2017) |
adstock_weibull() |
Weibull CDF / PDF carryover | As implemented in Robyn |
saturate_hill() |
Hill saturation | Hill (1910); Jin et al. (2017) |
saturate_michaelis_menten(),
saturate_exponential(), saturate_power()
|
Alternative concave response curves | Standard |
tune_carryover() |
Forward-only cross-validation, one-SE rule | Tashman (2000); Hastie et al. (2009) |
tune_carryover_joint() |
Coordinate descent over per-channel carryover in one model | Standard |
adstock_steady_state() |
Steady-state filter initialisation | Standard |
block_bootstrap() |
Moving block bootstrap | Künsch (1989); Lahiri (2003) |
step_adstock() |
Adstock continued across resampling boundaries | This package |
contributions() |
Additive decomposition, baseline as residual | Standard |
marginal_roi() |
Counterfactual marginal ROI | Jin et al. (2017); Meridian |
allocate_budget() |
Best split of a budget on a grid of spend levels, by dynamic programming | Bellman and Dreyfus (1962) |
diagnose_media() |
Variance inflation factors, coefficient of variation, CPM outliers | Standard |
diagnose_media(date =) |
Time-index check: order, repeated periods and gaps | This package |
from_robyn() |
Conversion of Robyn’s adstock and Hill hyperparameters | Robyn’s transformation.R
|
build_paths() |
Journey construction | This package |
credit_*() |
Rule-based attribution | Industry conventions |
markov_removal() |
First-order Markov removal effects | Anderl et al. (2016) |
attribute(times =) |
Bootstrap intervals on attribution shares | Efron (1979) |
Carryover
Geometric. The effect of spend decays by a constant factor each period, . This is the Koyck distributed lag, introduced to advertising as “adstock” by Broadbent (1979). mediamix defaults to the normalised kernel, weights summing to one, as in Jin et al. (2017); Robyn uses the unnormalised recursion. The two differ only in the scale of the regressor, and so of its coefficient.
Delayed. Jin et al. (2017) also use a delayed
kernel,
,
whose peak falls
periods after the spend. It does not contain the geometric kernel as a
special case: with
its weights fall off as
,
faster than geometric. This is the kernel to use when the response
builds before it decays, and peak is read directly in
periods:
round(rbind(
geometric = adstock_weights(8, decay = 0.6),
delayed = adstock_weights_delayed(8, decay = 0.6, peak = 2)
), 3)
#> [,1] [,2] [,3] [,4] [,5] [,6] [,7] [,8]
#> geometric 0.407 0.244 0.146 0.088 0.053 0.032 0.019 0.011
#> delayed 0.052 0.243 0.405 0.243 0.052 0.004 0.000 0.000Each row is a kernel from the period of spend (first column)
outwards. The geometric kernel puts its largest weight on the period of
spend; the delayed one puts it two periods later, at
peak = 2.
Weibull. Two parameterisations, both following
Robyn’s construction: the "cdf" form is a running product
of
,
always decreasing but with a time-varying rate; the "pdf"
form uses the density itself and can peak late. Robyn expresses the
scale as a quantile of the window, so its fitted scale values do not
transfer directly. from_robyn() converts the scale of the
CDF form to periods, and Robyn’s geometric decay and Hill
alpha and gamma to
media_transform() arguments, following the transformation
code in Robyn’s repository (R/R/transformation.R). Robyn
rescales the PDF form’s weights so that the smallest is 0, which
adstock_weibull() does not, so from_robyn()
refuses that form rather than approximate it.
Start-up bias. Every filter here is cold-started at
zero unless given a state. For a slow channel that
understates the first weeks of the series: at
a constant spend reaches 15% of its steady-state adstock in week one and
90% only after 15 weeks. Pass real pre-period spend through
adstock_state() when you have it. When you do not,
adstock_steady_state() returns the filter state that
constant spend at the early-period mean would have left,
for the recursive kernel, so a series does not begin at zero
adstock.
Saturation
The Hill curve
comes from Hill (1910) and is the saturation curve of Jin et al. (2017),
Robyn and Meridian. mediamix parameterises it by half_max
(,
the level of adstocked media at which the response reaches half its
ceiling) and shape
(;
above 1 gives an S-curve). It is evaluated as
,
which is algebraically identical but cannot overflow. Saturation is
applied after adstock, as in Jin et al.;
media_transform() uses that order by default and warns if
asked to reverse it.
Choosing carryover by cross-validation
tune_carryover() scores each candidate decay by
out-of-sample prediction of the KPI, on forward-only splits. This is
rolling-origin evaluation (Tashman, 2000), which never trains on the
future. Bergmeir and Benítez (2012) found no practical harm from
cross-validation’s theoretical problems in their study and recommend
blocked cross-validation, which also trains on later blocks; for a
filter whose purpose is to carry the past forward, forward-only splits
are the conservative choice. Because adstock is causal, the series is
transformed once and then split; the package’s tests enforce the
causality this relies on.
The score is pooled across splits by default: every out-of-sample forecast is collected and the metric computed once, so RMSE is a true root mean squared forecast error.
Carryover is usually weakly identified, so a single minimum
overstates what the data knows. best_1se applies the
one-standard-error rule (Breiman et al., 1984; Hastie et al., 2009,
§7.10), choosing the shortest carryover the resampling cannot
distinguish from the best. mediamix uses the paired form, on
the quantity best minimises: candidates are scored on the
same splits, and a candidate qualifies when its metric exceeds the
best’s by no more than one standard error of the difference, estimated
by a jackknife over splits (se_block leaves out blocks of
consecutive splits when forecast errors are autocorrelated). The
unpaired form is dominated by how hard each period is to forecast, which
is shared by every candidate, and admits almost the whole grid.
Several channels. Tuned one at a time, a channel’s
carryover absorbs the other channels’ effects and the controls’.
tune_carryover_joint() puts every channel and the controls
into one model and chooses each channel’s (max_lag, decay)
by coordinate descent: each channel in turn is set to its best grid
point with the rest held fixed, repeating until a sweep changes nothing.
Every accepted step lowers the cross-validated error, so it terminates,
at a local optimum of the grid; the cost is a few sweeps of the
one-channel grid rather than the full product grid. It reports each
channel’s final profile, so a flat one, carryover the data does not
identify, is visible rather than hidden behind a point estimate. Its
best_1se applies the rule channel by channel with the
others held at their best, so the combined set was never chosen as a
set; the result reports that set’s cross-validated error as
best_1se_metric. With by and
index, both tuners filter each geography separately and
form splits on the shared time index.
Warm start. warm_start = TRUE applies
adstock_steady_state() inside both tuners, seeded from
media in the first training window only, so it uses neither the KPI nor
media from later periods.
Uncertainty
block_bootstrap() implements the moving block bootstrap
of Künsch (1989): resample overlapping blocks of consecutive rows,
concatenate them to the original length, recompute the statistic, and
report percentile intervals. Blocks preserve the autocorrelation that
carryover creates; resampling single weeks would destroy it and
understate the uncertainty. The default block length
is the rate-optimal order for estimating a variance (Lahiri, 2003);
percentile intervals from short blocks cover less often than their
nominal level when errors are strongly autocorrelated, so for media data
a block at least as long as the carryover’s effective window is a
sensible floor. With by, every group uses the same time
blocks by default (panel = "shared"), so shocks that hit
every geography in the same week stay together;
panel = "independent" draws each group’s blocks separately.
The circular option (Politis and Romano, 1992) wraps blocks around the
end of the series, so the first and last weeks are drawn as often as the
rest.
The transform should be computed once, on the original series, before bootstrapping: re-adstocking resampled rows would carry spend across the joins between blocks. The resulting intervals describe sampling uncertainty given the transform parameters, not the uncertainty in choosing them.
attribute(times =) puts intervals on attribution shares
with the ordinary bootstrap of Efron (1979): journeys are drawn
independently with replacement, every rule is recomputed on each draw,
and the intervals are percentiles of the resampled shares. They hold
journey construction and the choice of rule fixed, and treat a
customer’s several journeys as unrelated.
Joint tuning with tidymodels
step_adstock() stores each group’s training time points
and media values at prep(). bake() filters the
training rows before the new data and then the new rows, so data that
continues or repeats the end of the training series gets exactly the
values of a whole-series filter. That is what lets carryover, saturation
and a model penalty be tuned jointly by tune’s resampling,
including rsample::rolling_origin(lag =) splits, with no
rows lost at the boundary. New data that starts after a gap, out of step
with the training periods, or in a group prep() never saw
is cold-started with a warning, or refused under
carry_over = "warm".
Contributions and return on investment
contributions() computes
for each channel and takes the baseline as the fitted value minus total
media, so the decomposition sums exactly to the model’s prediction. For
an additive model this is also each channel’s removal effect: what the
model predicts would be lost with that channel at zero. For periods the
model was not fitted on, contributions(newdata =) takes the
baseline from predict(); under a non-identity link the
decomposition is on the scale of the linear predictor.
marginal_roi() follows the counterfactual definition
used by Jin et al. (2017) and by Google’s Meridian, whose
marginal_roi() raises spend by 1% by default: increase
spend by a small proportion, re-run carryover and saturation, and divide
the extra response by the extra spend. Differentiating the saturation
curve at the mean adstocked level instead is a common shortcut and has
two problems. Multiplying by the kernel’s first weight to get back to
spend counts only the period of spend and drops every later period’s
carryover, and the slope at the mean is not the mean of the slope. The
simulation has neither problem. On a simulated channel with decay
0.85:
set.seed(3)
x <- pmax(0, rnorm(200, 1000, 300))
z <- adstock_geometric(x, decay = 0.85)
returns <- c(shortcut = mroi(mean(z), 1000, half_max = 1000) * (1 - 0.85),
simulated = marginal_roi(x, 1000, adstock = list(decay = 0.85),
saturation = list(half_max = 1000))$mroi)
returns
#> shortcut simulated
#> 0.03835 0.24495The shortcut understates the marginal return 6.4-fold here.
Budget allocation
allocate_budget() chooses each channel’s total spend to
maximise the predicted media response, each channel’s coefficient times
the sum of its transformed series, given a fixed total and bounds on
each channel’s total. Each channel’s series is rescaled as a whole, so
its flighting is kept. Its response is evaluated at its lower bound and
at every multiple of a step above it, the step being the budget above
the lower bounds divided by steps. Dynamic programming over
the channels, the one-dimensional allocation process of Bellman and
Dreyfus (1962, chapter I), then finds the combination of levels that
spends the total exactly with the largest response. That is the best
split on the grid whatever the shape of the curves. A greedy search,
which gives each increment to the channel whose next increment returns
most, can leave an S-shaped channel unfunded, because its first
increments return little. Nothing between grid points is searched, and
the coefficients are taken as exact.
Diagnostics
diagnose_media() reports variance inflation factors
(regressing each channel on the others), the coefficient of variation,
the share of dark periods and implied cost-per-mille outliers (a
median-absolute-deviation rule). With decay, collinearity
is measured on adstocked media, which is what the model sees. With
by, each is computed within series and the worst case
reported, since pooling geographies that differ in scale manufactures
correlation. With date, each series’ time index is checked
for rows out of order, repeated periods and missing periods, judged
against the series’ usual spacing: the median step between its distinct
time points, as in step_adstock(). Adstock treats adjacent
rows as adjacent periods, and none of these raises an error in the
transforms themselves.
Journeys and attribution
build_paths() has no single literature source; it
encodes the construction choices that the attribution literature assumes
have already been made: splitting on conversion and inactivity,
lookback, null paths, direct traffic, repeats and tie-breaking. The
rule-based credits (credit_first(),
credit_last(), credit_linear(),
credit_position(), credit_time_decay()) are
industry conventions and make no causal claim.
markov_removal() implements the first-order Markov model
of Anderl et al. (2016). Journeys are walks from a start state through
channels to one of two absorbing states. The conversion probability
comes from the fundamental matrix,
,
so it is exact for the fitted chain rather than simulated. A channel’s
removal effect is the proportional drop in that probability when every
transition into the channel is redirected to the null state, and
conversions are divided in proportion to removal effects.
Three journeys, small enough to check by hand: a then
b and a conversion, a alone without one, and
b alone with one.
ev <- data.frame(id = c("j1", "j1", "j2", "j3"), ch = c("a", "b", "a", "b"),
ts = c(1, 2, 1, 1), conv = c(0, 1, 0, 1))
m <- markov_removal(build_paths(ev, id = "id", channel = "ch",
timestamp = "ts", conversion = "conv"))
m
#> channel removal_effect conversions share p_without
#> 1 b 1.0 1.3333 0.6667 0.0000
#> 2 a 0.5 0.6667 0.3333 0.3333
attr(m, "p_conversion")
#> [1] 0.6667The conversion probability is 2/3. Removing a halves it
and removing b makes conversion impossible, so
b’s removal effect is twice a’s and it gets
twice a’s credit.
What none of this is
None of these methods estimates incrementality from observational data alone. Regression-based MMM is identified only as well as its specification and the variation in the data allow, and attribution rules, Markov removal effects included, divide observed conversions by a convention. Randomised experiments (geo experiments for media, holdouts for digital channels) measure what these methods estimate, and Robyn, Meridian and PyMC-Marketing all provide for calibrating a model to them.
References
Anderl, E., Becker, I., von Wangenheim, F. and Schumann, J. H. (2016). Mapping the customer journey: Lessons learned from graph-based online attribution modeling. International Journal of Research in Marketing, 33(3), 457–474. https://doi.org/10.1016/j.ijresmar.2016.03.001
Bellman, R. E. and Dreyfus, S. E. (1962). Applied Dynamic Programming. Princeton University Press. https://doi.org/10.1515/9781400874651
Bergmeir, C. and Benítez, J. M. (2012). On the use of cross-validation for time series predictor evaluation. Information Sciences, 191, 192–213. https://doi.org/10.1016/j.ins.2011.12.028
Breiman, L., Friedman, J., Olshen, R. and Stone, C. (1984). Classification and Regression Trees. Wadsworth. https://doi.org/10.1201/9781315139470
Broadbent, S. (1979). One way TV advertisements work. Journal of the Market Research Society, 21(3), 139–166.
Efron, B. (1979). Bootstrap methods: another look at the jackknife. The Annals of Statistics, 7(1), 1–26. https://doi.org/10.1214/aos/1176344552
Hastie, T., Tibshirani, R. and Friedman, J. (2009). The Elements of Statistical Learning (2nd ed.). Springer. https://doi.org/10.1007/978-0-387-84858-7
Hill, A. V. (1910). The possible effects of the aggregation of the molecules of haemoglobin on its dissociation curves. The Journal of Physiology, 40, iv–vii. https://doi.org/10.1113/jphysiol.1910.sp001386
Jin, Y., Wang, Y., Sun, Y., Chan, D. and Koehler, J. (2017). Bayesian methods for media mix modeling with carryover and shape effects. Google Inc. https://research.google/pubs/pub46001/
Koyck, L. M. (1954). Distributed Lags and Investment Analysis. North-Holland.
Künsch, H. R. (1989). The jackknife and the bootstrap for general stationary observations. The Annals of Statistics, 17(3), 1217–1241. https://doi.org/10.1214/aos/1176347265
Lahiri, S. N. (2003). Resampling Methods for Dependent Data. Springer. https://doi.org/10.1007/978-1-4757-3803-2
Politis, D. N. and Romano, J. P. (1992). A circular block-resampling procedure for stationary data. In R. LePage and L. Billard (eds.), Exploring the Limits of Bootstrap, 263–270. Wiley.
Robyn, Meta’s open-source marketing mix modelling package. https://github.com/facebookexperimental/Robyn.
from_robyn() follows R/R/transformation.R at
commit 5915aa9, and at release 3.11.1 for the range-based
Hill inflexion point.
Tashman, L. J. (2000). Out-of-sample tests of forecasting accuracy: an analysis and review. International Journal of Forecasting, 16(4), 437–450. https://doi.org/10.1016/S0169-2070(00)00065-0