Short answers to questions that come up when building a media mix
model or attributing conversions with mediamix. Each one names the
functions and arguments involved, and their help pages have the detail.
The examples use the package’s simulated data, mm_weekly
and mm_events.
Carryover
Should the adstock kernel be normalised?
By default (normalise = TRUE) the kernel’s weights sum
to 1, so a steady spend of 100 a week adstocks to 100 once the filter
has filled, and a coefficient on the adstocked column reads per unit of
spend. With normalise = FALSE, the convention Robyn uses,
the same spend accumulates to 100 / (1 - decay), and the coefficient
reads per unit of accumulated media. The two series differ only by a
constant factor, so in a least-squares fit only the coefficient’s scale
changes. A saturation half_max given as an amount belongs
to one convention and is wrong for the other, while one set relative to
the series’ own reference level, as step_saturation() sets
it, gives the same curve under both. Keep one convention for a project,
and compare coefficients only between models fitted the same way.
steady <- rep(100, 100)
c(normalised = tail(adstock_geometric(steady, decay = 0.8), 1),
raw = tail(adstock_geometric(steady, decay = 0.8, normalise = FALSE), 1))
#> normalised raw
#> 100 500Why are the first weeks of an adstocked series low?
Every filter starts from zero unless told otherwise, as if nothing
had been spent before the first row. A slow channel takes weeks to fill:
at a decay of 0.85 a steady spend reaches 15% of its level in the first
week, and 90% only after effective_window(0.85), 15 weeks.
With spend from before the series, pass adstock_state() of
it as state; without it,
adstock_steady_state() gives the state that steady spend at
the series’ early average would have left.
warm_start = TRUE in the tuners and
start = "steady" in step_adstock() apply the
same correction. Robyn’s remedy, adstocking every row and fitting the
model on the later rows only, works here too.
x <- rep(100, 6)
rbind(cold = adstock_geometric(x, decay = 0.85),
steady = adstock_geometric(x, decay = 0.85,
state = adstock_steady_state(x, decay = 0.85)))
#> [,1] [,2] [,3] [,4] [,5] [,6]
#> cold 15 27.75 38.59 47.8 55.63 62.29
#> steady 100 100.00 100.00 100.0 100.00 100.00How long should max_lag be?
The default, max_lag = Inf, runs the geometric kernel as
a recursive filter and never truncates it, so there is nothing to
choose. A finite kernel should keep most of the effect:
effective_window(decay, coverage) is the smallest number of
periods that holds coverage of a geometric kernel’s total
weight. The same number checks a fitted decay, since an effective window
that approaches the length of the series is not identified by the data.
The Weibull and delayed kernels have no recursive form and always need a
finite max_lag; effective_window() of a
comparable geometric decay is a starting point.
effective_window(c(tv = 0.85, search = 0.15), coverage = 0.9)
#> tv search
#> 15 2
effective_window(0.85, coverage = 0.99)
#> [1] 29How do I convert a half-life between daily and weekly data?
decay_from_half_life() and half_life() take
period, the spacing between rows in the unit the half-life
is stated in. A 21-day half-life on weekly data is
decay_from_half_life(21, period = 7), the same decay as a
three-week half-life, and half_life(decay, period = 7)
gives a weekly decay’s half-life in days. To move a decay fitted on
daily data to weekly data, go through its half-life:
daily <- 0.9
days <- half_life(daily)
c(days = days, weekly = decay_from_half_life(days, period = 7),
daily_to_the_7th = daily^7)
#> days weekly daily_to_the_7th
#> 6.5788 0.4783 0.4783The half-life is kept and the decay per row changes. Adstocking weekly totals is still not the same as adstocking daily spend and summing it to weeks, because the timing of spend within each week is lost.
How do I choose the decay?
Choose it against the KPI, by cross-validation.
tune_carryover() scores each candidate
(max_lag, decay) for one channel by how well a model fitted
on the adstocked media predicts held-out KPI, on forward-only splits,
with trend, price and seasonality passed as controls.
tune_carryover_joint() does the same for every channel
inside one model, so no channel is credited with another’s effect, and
plot() on either result shows how sharply the data
identifies each decay. To tune carryover together with saturation and a
model penalty, use step_adstock_channels() or
step_adstock() with step_saturation() and
tune() in a tidymodels workflow, as
vignette("tidymodels") shows; that search needs the tune,
parsnip, workflows and yardstick packages.
What is the difference between best and
best_1se?
best is the candidate with the lowest cross-validated
error. best_1se is the shortest carryover (lowest
half-life, then shortest kernel) whose error is within one standard
error of best’s, the one-standard-error rule of Breiman et
al. (1984) and Hastie et al. (2009), with the standard error taken from
the paired difference between the two over the same splits. Carryover is
often weakly identified, so the two can differ widely, and when they do
the data cannot tell them apart. The shorter one is the more cautious
claim about how long a channel keeps working, though not for every
decision, since it also lowers the channel’s marginal return. In
tune_carryover_joint() the rule is applied channel by
channel, and best_1se_metric scores the resulting set as a
whole.
set.seed(42)
spend <- pmax(0, rnorm(120, 500, 250))
kpi <- 200 + 0.5 * adstock_geometric(spend, decay = 0.7) + rnorm(120, sd = 60)
tuned <- tune_carryover(spend, kpi, decays = seq(0.1, 0.9, by = 0.1))
rbind(best = tuned$best, one_se = tuned$best_1se)
#> max_lag decay half_life metric std_err n_splits
#> best Inf 0.8 3.106 54.75 4.548 60
#> one_se Inf 0.6 1.357 56.31 5.219 60The true decay here is 0.7, and the noise leaves the data unable to separate 0.6 from 0.8.
How do I adstock several geographies?
Pass the geography as by. Each group is filtered on its
own, so carryover never runs from the last week of one geography into
the first week of the next, and each group’s rows must be in time order,
since the transforms have no time index. media_transform(),
transform_plan(), marginal_roi(),
simulate_plan() and allocate_budget() take
by too, the tuners take by with
index, and step_adstock() takes
by and sorts by its own index. Do not rely on
dplyr::group_by() instead: the grouping does not survive
into every place the transforms run, such as a recipe’s
bake(), and diagnose_media() ignores it with a
message naming the by to pass.
spend <- c(100, 0, 0, 200, 0, 0)
geo <- rep(c("north", "south"), each = 3)
rbind(pooled = adstock_geometric(spend, decay = 0.5),
by_geo = adstock_geometric(spend, decay = 0.5, by = geo))
#> [,1] [,2] [,3] [,4] [,5] [,6]
#> pooled 50 25 12.5 106.2 53.12 26.56
#> by_geo 50 25 12.5 100.0 50.00 25.00What happens when weeks are missing?
The transforms treat adjacent rows as adjacent periods. A missing
week lets the decay act once across what were two weeks, a repeated week
is carried over twice, and a row out of order mixes later spend into
earlier weeks, and none of these raises an error. Given the time column
as date, diagnose_media() counts each of them
per series in its dates table and lists them in
flags, and step_adstock() warns at
prep() when its index is unevenly spaced and stops on a
repeated time point. Add a row for every missing period before
transforming, with zero spend where the channel did not run. A missing
value in a row that exists is an error in the adstock functions by
default; na_action = "zero" reads it as no spend, and
step_adstock() does that by default.
gappy <- mm_weekly[-10, ] # drops one week of north
diagnose_media(gappy, media = "tv", by = "geo", date = "date")$dates
#> group rows start end period out_of_order duplicated missing
#> 1 north 155 2023-01-02 2025-12-22 7 0 0 1
#> 2 central 156 2023-01-02 2025-12-22 7 0 0 0
#> 3 south 156 2023-01-02 2025-12-22 7 0 0 0
#> irregular
#> 1 1
#> 2 0
#> 3 0Saturation
Does saturation go before or after adstock?
Saturation goes after adstock. A saturation curve caps what the media
pressure in a period can achieve, and that pressure includes carryover
from earlier weeks. Saturating first puts each week’s spend through the
curve on its own, so carryover never counts towards saturation, and with
normalise = FALSE the carried-over values can add up past
the ceiling. media_transform() adstocks first by default
and warns when asked for order = "saturate_then_adstock",
and in a recipe step_saturation() goes after
step_adstock(). Robyn uses the same order.
Why is half_max a fraction in
step_saturation()?
In saturate_hill() and media_transform(),
half_max is an amount of adstocked media, the level at
which the response reaches half its ceiling, so it depends on each
channel’s scale. step_saturation() takes it as a fraction
of each column’s reference level in the training data, its largest value
by default (ref = "max"), so one tunable value means the
same thing for every channel. A half_max of 0.4 there puts
the half-way point at 40% of the largest adstocked value seen in
training, and with by each geography gets a reference of
its own.
Reporting
What does “(baseline)” mean?
contributions() gives each channel its coefficient times
its transformed column, period by period, and pools everything else the
model predicts into a channel called "(baseline)": the
intercept, trend, price, seasonality, holidays and any other control. It
is the model’s prediction minus the media effect, which is what makes
each period’s contributions sum to the prediction. It holds whatever
this decomposition does not attribute to media, and reporting it as
organic demand overstates what the model knows. For periods the model
was not fitted on, pass newdata so that the baseline comes
from predict(); for a bare coefficient vector it is the
intercept alone.
north <- mm_weekly[mm_weekly$geo == "north", ]
truth <- attr(mm_weekly, "truth")
channels <- c("tv", "video", "search", "social", "display")
spec <- lapply(stats::setNames(channels, channels), function(ch) list(
adstock = list(decay = truth$decay[[ch]]),
saturation = list(half_max = truth$half_max[[ch]], shape = truth$shape[[ch]])
))
media <- transform_plan(north, spec)
media$week <- seq_len(nrow(media))
fit <- lm(revenue ~ tv + video + search + social + display + week + price +
seasonality + holiday, data = media)
contrib <- contributions(media[channels], fit, index = media$date)
round(tapply(contrib$contribution, contrib$channel, sum))
#> (baseline) display search social tv video
#> 3190425 40853 208307 132709 349629 102461Should I use roi(), marginal_roi() or
mroi()?
roi() is the average return, each channel’s total
contribution divided by its total spend, which scores the period as a
whole. marginal_roi() is the return on the next unit of
spend. It re-runs carryover and saturation on a budget 1% larger
(lift = 0.01) and divides the extra response by the extra
spend, following Jin et al. (2017), so it is the one to use when moving
budget. mroi() is the slope of a saturation curve at one
level of transformed media, a property of the curve rather than a return
on spend. Under a concave curve the marginal return is below the average
one everywhere; under an S-shaped curve, below its inflection point, it
can be above.
marginal_roi(north, coef(fit), spec = spec)
#> channel spend contribution roi mroi
#> 1 tv 266978 349629 1.310 1.2534
#> 2 video 53248 102461 1.924 1.1961
#> 3 search 74560 208307 2.794 1.3490
#> 4 social 36716 132709 3.614 2.0892
#> 5 display 26937 40853 1.517 0.9324The roi column is the average return that
roi() reports from these contributions, and
mroi the marginal return beside it.
Why does marginal_roi() stop counting at the last
week?
By default (extend = 0) it sums response over the
observed weeks only, the weeks contributions() and
roi() cover, so that its average return matches theirs. The
carryover of spend near the end of the data then falls outside the sum,
which understates the marginal return of slow channels. For a budget
decision, pass extend = effective_window(decay, 0.99),
which appends that many weeks of zero spend so the late carryover plays
out.
tv_mroi <- function(extend) {
marginal_roi(north$tv, coefficient = coef(fit)[["tv"]],
adstock = spec$tv$adstock, saturation = spec$tv$saturation,
extend = extend)$mroi
}
c(observed_weeks = tv_mroi(0),
with_run_out = tv_mroi(effective_window(truth$decay[["tv"]], 0.99)))
#> observed_weeks with_run_out
#> 1.253 1.305How do I report by geography or by year?
Give contributions() the grouping as by,
and pass the same grouping to roi(), which then returns one
row per channel per group. For one year or quarter of a longer
decomposition, give roi() the period of each row of spend
as index and the periods to keep as periods.
rows in marginal_roi() raises spend only
inside a planning window, and simulate_plan() and
allocate_budget() take by for a panel.
year <- format(media$date, "%Y")
by_year <- contributions(media[channels], fit, index = media$date, by = year)
roi(by_year, north[channels], by = year)
#> group channel contribution spend roi
#> 1 2023 social 41852 11341 3.690
#> 2 2023 search 69308 24754 2.800
#> 3 2023 video 34499 19144 1.802
#> 4 2023 display 12225 8055 1.518
#> 5 2023 tv 113146 93732 1.207
#> 6 2024 social 48681 14037 3.468
#> 7 2024 search 71023 25540 2.781
#> 8 2024 video 34586 17499 1.976
#> 9 2024 display 14456 9626 1.502
#> 10 2024 tv 112666 77978 1.445
#> 11 2025 social 42177 11338 3.720
#> 12 2025 search 67976 24266 2.801
#> 13 2025 video 33376 16605 2.010
#> 14 2025 display 14172 9256 1.531
#> 15 2025 tv 123817 95268 1.300Where do intervals come from, and what do they leave out?
block_bootstrap() puts percentile intervals on any
statistic computed from a weekly table, such as coefficients,
contributions or returns. It resamples blocks of consecutive weeks, so
the autocorrelation that carryover creates survives (Künsch, 1989), then
refits and recomputes through your statistic function.
Transform the media first and put the transformed columns in the data,
so that no block carries spend across a join. The intervals cover
sampling variation given the model and its transform parameters; they
leave out the uncertainty in choosing those parameters and any error in
the specification, and on short series they cover less than their
nominal level, so read them as a lower bound. Make blocks at least as
long as the longest channel’s effective_window(), and for a
panel pass by, so that every geography takes the same
blocks of weeks.
Budgets
How do I compare plans or split a budget?
simulate_plan() runs each channel of a spend plan
through its transform and coefficient, and with baseline it
reports each channel’s change against another plan.
reallocate() builds such a plan by moving an amount from
one channel to another, and allocate_budget() splits a
total across channels to maximise the predicted response within
lower and upper bounds, searching a grid of
steps increments so that S-shaped curves do not trap it.
Both keep each channel’s weekly pattern and change only its level, so
neither can start a channel that has no spend until it is given small
weights in the weeks it should run; to try a different timing, build the
plan yourself and pass it to simulate_plan(). The answers
are only as good as the fitted curves, which are identified only over
the spend levels in the data, so a move far beyond them is extrapolation
and worth testing before it is made.
allocate_budget(north, spec, coef(fit), steps = 100)
#>
#> ── Budget allocation
#> A total of 458,439, in 100 increments of 4,584.39.
#> Predicted media response: 833,959 now, 845,422 recommended.
#> channel current_spend recommended_spend current_response recommended_response
#> tv 266978 252141 349629 330634
#> video 53248 45844 102461 93095
#> search 74560 77935 208307 212779
#> social 36716 64181 132709 177194
#> display 26937 18338 40853 31719
#> mroi
#> 1.299
#> 1.329
#> 1.289
#> 1.250
#> 1.203
#> The recommended plan is in $plan.Attribution
Why do the attribution rules disagree?
Each rule is a convention for dividing a conversion among the touches
before it, and the conventions favour different positions: first-touch
credits the channels that open journeys and last-touch those that close
them. attribute() runs all six rules on the same journeys,
attribution_spread() reports each channel’s lowest and
highest share, and channel_positions() shows which channels
open or close journeys. A wide spread is itself the finding, since it
measures how much of a channel’s credit comes from the choice of rule
rather than from the data.
paths <- build_paths(mm_events, id = "customer_id", channel = "channel",
timestamp = "timestamp", conversion = "conversion")
spread <- attribution_spread(attribute(paths))
spread[, c("channel", "min_share", "max_share", "first_last_ratio")]
#> channel min_share max_share first_last_ratio
#> 1 display 0.07187 0.29113 4.0508
#> 2 paid_search 0.09157 0.27253 0.3360
#> 3 email 0.05655 0.18314 0.3088
#> 4 social 0.11638 0.22072 1.8966
#> 5 organic_search 0.12623 0.17877 0.7061
#> 6 affiliate 0.08063 0.11711 1.4525
#> 7 direct 0.02225 0.02683 1.0492
#> 8 (blank) 0.02955 0.03379 0.9419
#> 9 (none) 0.02736 0.02982 1.0133
#> 10 (missing) 0.01569 0.01637 1.0233Can I attribute by segment, with intervals?
Yes. Carry the segment column into the journeys with the
keep argument of build_paths(), give each
journey a single value, and pass the column to attribute()
as by; every rule, the Markov chain included, then runs on
each segment’s journeys alone. With times (and
seed), attribute() adds percentile intervals
by resampling journeys with replacement. The intervals show how far the
shares move with the sample of journeys, with the journey construction
and each rule held fixed; they say nothing about the choice of rule,
which attribution_spread() measures.
Can I fit higher-order Markov chains?
markov_removal() fits the first-order chain, following
Anderl et al. (2016). For higher orders, export the journeys with
as_channel_paths() and pass them to
ChannelAttribution::markov_model() with its
order argument and the same sep on both sides;
ChannelAttribution::choose_order() suggests an order. That
needs the ChannelAttribution package, which mediamix suggests but does
not require. For order 1 the two packages implement the same
removal-effect definition, ChannelAttribution by simulation.
ca <- as_channel_paths(paths, sep = ">")
ChannelAttribution::markov_model(ca, var_path = "path",
var_conv = "total_conversions",
var_null = "total_null", order = 2, sep = ">")Why keep the journeys that did not convert?
Markov removal effects compare the chance of reaching a conversion
with the chance of reaching nothing, and the journeys that ended in
nothing are the only evidence of the second. Without them the baseline
conversion probability is 1, and every removal effect moves, up or down
depending on how the dropped journeys differed from the converting ones.
build_paths() keeps them by default
(keep_null_paths = TRUE), as_channel_paths()
counts them in total_null, and
markov_removal() warns when a table has none.
How do I choose a lookback window?
Read it off your own journeys. conversion_lag() reports
quantiles of the time from first touch to conversion, so a lookback at
its 90% point leaves nine in ten converting journeys whole. Run it on
journeys built without lookback, since a lookback caps
every lag it measures, and read the lags in the journey table’s
units, days by default.
conversion_lag(paths)
#> quantile lag
#> 1 0.50 4.535
#> 2 0.75 8.793
#> 3 0.90 13.492
#> 4 0.95 16.851
#> 5 0.99 23.538
#> 6 1.00 43.165Other tools
Can I use the transforms with brms, Stan or glmnet?
Yes, with the transform parameters fixed before the fit. The
transforms are R functions on numeric vectors, so
media_transform() or transform_plan() produces
columns that any model can take. contributions() reads
coefficients through coef(), which serves
lm(), glm() and the fixed effects of nlme and
lme4; for glmnet, brms or Stan, pass the point estimates as a named
vector, naming the intercept "(Intercept)" or giving it as
intercept, and the baseline is then that intercept alone.
marginal_roi(), simulate_plan() and
allocate_budget() take coefficients as a named vector in
any case. To estimate a decay or a half_max inside a
Bayesian model, the transform has to be written in that model’s own
language, Stan for brms.
# A ridge regression at a fixed penalty, chosen for illustration
X <- as.matrix(media[c(channels, "week", "price", "seasonality", "holiday")])
ridge <- glmnet::glmnet(X, media$revenue, alpha = 0, lambda = 50)
b <- as.matrix(coef(ridge))[, 1]
marginal_roi(north, b, spec = spec)
#> channel spend contribution roi mroi
#> 1 tv 266978 347225 1.301 1.245
#> 2 video 53248 101660 1.909 1.187
#> 3 search 74560 204208 2.739 1.322
#> 4 social 36716 126887 3.456 1.998
#> 5 display 26937 43968 1.632 1.003Can I reproduce Robyn’s transforms?
Yes, for geometric and Weibull CDF adstock with Hill saturation.
Given the series Robyn transformed and its modelling window,
from_robyn() converts one channel’s theta (or
shape and scale), alpha and
gamma into the adstock and
saturation lists that media_transform() takes,
and the result matches Robyn’s series. Set
inflexion = "range" for a model fitted by Robyn 3.7.0 to
3.11.1, which placed the Hill inflexion point differently. Robyn’s
Weibull PDF has no exact equivalent and is refused. Migrating from Robyn works through
an example.
Is any of this causal?
No. A media mix model fitted to observational data is identified only
as well as its specification and the variation in the data allow, and
cross-validation shows predictive value, not a causal mechanism.
Attribution rules, Markov removal effects included, divide observed
conversions by a convention and cannot say what would have happened
without a channel. Randomised experiments, such as geo tests for media
and holdouts for digital channels, measure that, and they are the way to
check or calibrate a model; mediamix has no calibration step of its own.
reallocate() with by sets up a move in one
region, the plan for such a test.
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
Breiman, L., Friedman, J., Olshen, R. and Stone, C. (1984). Classification and Regression Trees. Wadsworth. https://doi.org/10.1201/9781315139470
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
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/
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