A two-parameter kernel whose "pdf" form, unlike the geometric kernel, can
place its peak after the period in which the money was spent.
Television, cinema and out-of-home often behave this way: the response
builds for a week or two before it turns over. A geometric kernel cannot
represent that shape at any decay rate. The default "cdf" form decays
monotonically.
Usage
adstock_weights_weibull(
max_lag,
shape,
scale,
type = c("cdf", "pdf"),
normalise = TRUE
)Arguments
- max_lag
Number of periods the kernel spans, including the current period. Unlike the geometric kernel, Weibull adstock has no infinite form:
max_lagis required and must be finite.- shape
Weibull shape parameter, positive. In the
"pdf"form,shape <= 1produces a monotonically decaying kernel, andshape > 1allows a delayed peak without guaranteeing one: see Details for when the peak moves past the period of spend. In the"cdf"form, larger values produce a flatter plateau followed by a sharper drop.- scale
Weibull scale parameter, positive, measured in periods. Larger values stretch the kernel over more periods.
- type
Either
"cdf"(default) or"pdf". See Details.- normalise
Should the weights sum to 1? Defaults to
TRUE. WhenFALSE, weights are scaled so the largest is 1, matching the unnormalised geometric convention.
Details
The two forms answer different questions.
The "cdf" form builds the kernel as a cumulative product of Weibull
survival values. Numbering lags from 1 so that \(w_1\) is the period of
spend, \(w_i = \prod_{j<i} (1 - F(j))\), where \(F\) is the Weibull
distribution function, so \(w_1 = 1\) and each later weight is the
previous one times \(1 - F(i - 1)\). Read \(1 - F(j)\) as a
time-varying retention rate: it plays the role that the constant
\(\theta\) plays in the geometric kernel, which is the sense in which this
form generalises geometric decay. It is always monotonically decreasing,
but the rate of decay can itself change over time. The kernel is the
running product of these values rather than the Weibull survival function
\(1 - F(i)\), and its tail falls away much faster. The construction is
the one Robyn calls "weibull_cdf". Robyn expresses scale as a
quantile of the series length rather than in periods; from_robyn()
converts it.
The "pdf" form uses the Weibull density directly, \(w_i \propto f(i)\).
This is the form that permits a delayed peak, and it is the reason to reach
for Weibull adstock at all. With shape <= 1 it collapses back to a
monotone decay. Lags are numbered from 1 here too, so the period of spend
carries \(f(1)\) and the next period \(f(2)\), and the kernel peaks
after the period of spend only when \(f(2) > f(1)\). That needs
shape > 1 and a Weibull mode, scale * ((shape - 1) / shape)^(1 / shape),
of roughly 1.5 or more (1.47 at shape = 2, rising towards 2 as shape
grows). With shape = 2, scale = 2 puts the mode at 1.41 and the kernel
still peaks in the period of spend; scale = 3 moves the peak one period
later. A density that is numerically zero at every lag, with all its mass
beyond max_lag or before the first lag, is an error.
Examples
# Monotone decay, a flexible generalisation of geometric
round(adstock_weights_weibull(8, shape = 2, scale = 3, type = "cdf"), 4)
#> [1] 0.3680 0.3293 0.2111 0.0777 0.0131 0.0008 0.0000 0.0000
# Delayed peak: the largest single weight lands one period after the spend,
# not in the period of spend itself. No geometric decay rate can do this.
w <- adstock_weights_weibull(8, shape = 2, scale = 3, type = "pdf")
round(w, 4)
#> [1] 0.2027 0.2905 0.2500 0.1531 0.0704 0.0249 0.0069 0.0015
which.max(w)
#> [1] 2