Applies a diminishing-returns curve to media columns inside a recipes pipeline, with the half-saturation point expressed relative to each column's own scale so that one tunable parameter works across channels.
Arguments
- recipe
A recipe object.
- ...
One or more selector functions choosing the media columns. As with
step_adstock(), select media only;all_predictors()also picks up the controls.- type
Which curve:
"hill"(the default),"exponential","michaelis_menten"or"power".- half_max
Half-saturation point, expressed as a fraction of the column's reference level, in
(0, 2].0.5means the curve reaches half its ceiling at half the reference level. Ignored whentype = "power", which has no half-saturation point, and it cannot be tuned there. Otherwise tunable, over[0.05, 1]by default.- shape
Means different things to different curves, and is validated accordingly. For
"hill"it is the Hill exponent, any positive number:1gives a concave curve and values above1an S-shape with a threshold. For"power"it is the exponent itself and must lie in(0, 1], since a power above 1 is not saturating at all. Ignored by"exponential"and"michaelis_menten", and it cannot be tuned there. Tunable for"hill"and"power"; the advertised range narrows to[0.1, 1]whentype = "power", so a joint search cannot propose a value the curve would reject.- ref
How to set each column's reference level from the training data:
"max"(the default),"q99","q95"or"mean". Using a high quantile rather than the maximum keeps a single outlying week from setting the reference, but a channel that ran in only a few training periods can have a 95th percentile of zero.- by
Optional character vector naming grouping columns. When given, each group gets its own reference level, so a small geography is placed on the curve by its own scale rather than by the largest one's.
NULL(the default) pools all rows.- role
Not used by this step, since new columns are not created.
- trained
Has the step been prepared?
- columns, refs, group_refs
Populated by
prep(); not set directly.- skip
Should the step be skipped when baking? Must remain
FALSE.- id
A unique step identifier.
Why the half-saturation point is relative
Television spend might run to six figures a week and affiliate to three. An absolute half-saturation point is therefore a different parameter for every channel, which makes joint tuning across channels either meaningless or a separate parameter per column.
Expressing it as a fraction of each column's own reference level fixes this:
half_max = 0.4 means "half the ceiling is reached at 40% of this column's
reference level" and reads the same way for every channel, so a single
tunable parameter covers them all. With the default ref = "max" the
reference is the column's training maximum. After step_adstock() the
column holds adstocked values, so that is the peak adstocked value, not the
peak weekly spend. prep() stores one number per column, or per column and
group with by, learned from the training data only, and bake() applies
it unchanged. A test-set value above the training reference is not clipped:
it lands further up the curve.
Under the hood, half_max is converted to whichever native parameter the
chosen curve uses (the Hill and Michaelis–Menten half-points directly, and
\(\log 2 / x_{1/2}\) for the exponential rate), so the fraction means the
same thing across all three bounded curves.
Panel data
Without by, the reference level is computed over every row, so on a panel
it is set by the largest geography: a small one sits near the bottom of the
curve and never saturates. With by, each group's reference comes from its
own training rows. A group not seen during prep() uses the pooled
reference, the one computed over every training row, with a warning. So
does a group whose own training values give no positive reference, such as
one where a channel never ran; prep() warns about those.
Order
Put this step after step_adstock(), so that the curve acts on accumulated
exposure rather than on each period's spend alone. With the default
normalised kernel the result stays below the ceiling in either order; with
normalise = FALSE, saturating first would also let carryover accumulate
the capped values past the ceiling. See media_transform().
When step_adstock() keeps the raw spend (keep_original_cols = TRUE), the
adstocked values are in its new columns, so select those here, for example
with starts_with("adstock_").
Negative and missing values
Saturation curves are defined for non-negative media. Missing values are
treated as zero spend, and negative values are clamped to zero with a
warning. The commonest way to produce negatives is a step_normalize()
earlier in the recipe, which centres each column on its mean and therefore
sends about half of every column below zero. Saturate first, or normalise
something other than the media. Infinite values are an error.
Tidying
tidy() returns a tibble with one row per selected column, or per column
and group with by, and the columns terms, group (only with by),
type, half_max, shape, reference and id. half_max and shape
are NA where the curve ignores them, and before prep() when they are
marked with tune(). reference is the learned reference level, NA
before prep().
Examples
library(recipes)
data(mm_weekly)
rec <- recipe(revenue ~ ., data = mm_weekly) |>
step_adstock(tv, video, search, index = "date", by = "geo", decay = 0.7) |>
step_saturation(tv, video, search, half_max = 0.4, shape = 1.5) |>
prep()
out <- bake(rec, new_data = NULL)
range(out$tv)
#> [1] 0.0000000 0.7980959
tidy(rec, number = 2)
#> # A tibble: 3 × 6
#> terms type half_max shape reference id
#> <chr> <chr> <dbl> <dbl> <dbl> <chr>
#> 1 tv hill 0.4 1.5 3258. saturation_nPUaO
#> 2 video hill 0.4 1.5 880. saturation_nPUaO
#> 3 search hill 0.4 1.5 818. saturation_nPUaO
# One reference level per geography
rec_geo <- recipe(revenue ~ ., data = mm_weekly) |>
step_adstock(tv, index = "date", by = "geo", decay = 0.7) |>
step_saturation(tv, half_max = 0.4, shape = 1.5, by = "geo") |>
prep()
tidy(rec_geo, number = 2)
#> # A tibble: 3 × 7
#> terms group type half_max shape reference id
#> <chr> <chr> <chr> <dbl> <dbl> <dbl> <chr>
#> 1 tv north hill 0.4 1.5 2455. saturation_Q4dc6
#> 2 tv central hill 0.4 1.5 1732. saturation_Q4dc6
#> 3 tv south hill 0.4 1.5 3258. saturation_Q4dc6