dials parameter objects for the quantities step_adstock() and
step_saturation() expose to tuning. They are one reason for the
transforms to be recipe steps rather than functions you call beforehand:
they let carryover decay, saturation shape and a model's own penalty be
tuned jointly, in one tune::tune_bayes() call over proper rolling-origin
resampling, rather than fixing the transform parameters by eye and tuning
only the model.
Usage
carryover_decay(range = c(0, 0.95), trans = NULL)
carryover_max_lag(range = c(1L, 26L), trans = NULL)
carryover_shape(range = c(0.5, 5), trans = NULL)
carryover_scale(range = c(0.5, 10), trans = NULL)
carryover_peak(range = c(0, 4), trans = NULL)
saturation_half_max(range = c(0.05, 1), trans = NULL)
saturation_shape(range = c(0.5, 3), trans = NULL)Details
carryover_decay() spans [0, 0.95] rather than [0, 1). The upper bound
is a practical one: a decay of 0.99 implies a half-life of 69 periods, which
no ordinary media dataset can identify, and leaving it in the range mostly
wastes tuning iterations on parameter values that trade off against the
intercept.
carryover_max_lag() spans 1 to 26 periods. It is finite by necessity:
Inf is a legitimate value for step_adstock() but not a tunable one, since
a search cannot propose an infinite integer. So tuning max_lag over a
finite grid and leaving it fixed at Inf are genuinely different searches:
the first over truncated kernels, the second over the recursive one. Most of
the time, tuning decay with max_lag = Inf is the better use of the
budget: the truncation point is usually a modelling decision rather than
something the data speaks to.
carryover_shape() and carryover_scale() are the shape and scale of
step_adstock()'s Weibull kernel. The shape spans [0.5, 5] and the
scale [0.5, 10] periods. Over those ranges the kernel keeps some weight at
its first lag in both forms and at every max_lag, so no candidate is
rejected as a kernel that is zero everywhere. carryover_peak() is the
delayed kernel's peak lag, from 0 to 4 periods. A peak must not pass
max_lag - 1, so step_adstock() stops this range there when max_lag is
fixed, and starts a tuned max_lag above the largest peak. For the delayed
kernel it also narrows carryover_decay() to [0.05, 0.95], since that
kernel needs a positive retention rate.
saturation_half_max() is a fraction of each column's reference level, so
its range is unitless and comparable across channels. See
step_saturation().
saturation_shape() spans [0.5, 3]. Values above 1 give an S-shaped
response with a threshold below which media barely registers; below 1 the
curve bends harder than a plain hyperbola. step_saturation() narrows
this range to [0.1, 1] when type = "power", where shape is the
exponent itself and a value above 1 would not be saturating at all. It
offers saturation_shape() only for the Hill and power curves and
saturation_half_max() only for the three curves with a half-saturation
point, since the others ignore them.
Examples
carryover_decay()
#> Carryover Decay (quantitative)
#> Range: [0, 0.95]
dials::value_seq(carryover_decay(), 5)
#> [1] 0.0000 0.2375 0.4750 0.7125 0.9500
saturation_shape()
#> Saturation Shape (quantitative)
#> Range: [0.5, 3]
dials::grid_regular(carryover_decay(), saturation_shape(), levels = 3)
#> # A tibble: 9 × 2
#> decay shape
#> <dbl> <dbl>
#> 1 0 0.5
#> 2 0.475 0.5
#> 3 0.95 0.5
#> 4 0 1.75
#> 5 0.475 1.75
#> 6 0.95 1.75
#> 7 0 3
#> 8 0.475 3
#> 9 0.95 3
# The Weibull kernel's two parameters
dials::grid_regular(carryover_shape(), carryover_scale(), levels = 3)
#> # A tibble: 9 × 2
#> shape scale
#> <dbl> <dbl>
#> 1 0.5 0.5
#> 2 2.75 0.5
#> 3 5 0.5
#> 4 0.5 5.25
#> 5 2.75 5.25
#> 6 5 5.25
#> 7 0.5 10
#> 8 2.75 10
#> 9 5 10