Skip to contents

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 θ\theta each period, at=xt+θat−1a_t = x_t + \theta a_{t-1}. This is the Koyck distributed lag, introduced to advertising as “adstock” by Broadbent (1979). mediamix defaults to the normalised kernel, weights (1−θ)θl(1-\theta)\theta^l 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, wl=θ(l−δ)2w_l = \theta^{(l-\delta)^2}, whose peak falls δ\delta periods after the spend. It does not contain the geometric kernel as a special case: with δ=0\delta = 0 its weights fall off as θl2\theta^{l^2}, 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.000

Each 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 1−F(l)1 - F(l), 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 θ=0.85\theta = 0.85 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, m/(1−θ)m/(1-\theta) for the recursive kernel, so a series does not begin at zero adstock.

Saturation

The Hill curve xs/(xs+Ks)x^s / (x^s + K^s) comes from Hill (1910) and is the saturation curve of Jin et al. (2017), Robyn and Meridian. mediamix parameterises it by half_max (KK, the level of adstocked media at which the response reaches half its ceiling) and shape (ss; above 1 gives an S-curve). It is evaluated as 1/(1+(K/x)s)1 / (1 + (K/x)^s), 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 ⌈n1/3⌉\lceil n^{1/3} \rceil 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 βjzjt\beta_j z_{jt} 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.24495

The 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, (I−Q)−1R(I - Q)^{-1} R, 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.6667

The 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