Robyn (version 3.11.1)

hyper_names: Get correct hyperparameter names

Description

Output all hyperparameter names and help specifying the list of hyperparameters that is inserted into robyn_inputs(hyperparameters = ...)

Usage

hyper_names(adstock, all_media, all_vars = NULL)

Value

Character vector. Names of hyper-parameters that should be defined.

Arguments

adstock

Character. Default to InputCollect$adstock. Accepts "geometric", "weibull_cdf" or "weibull_pdf"

all_media

Character vector. Default to InputCollect$all_media. Includes InputCollect$paid_media_spends and InputCollect$organic_vars.

all_vars

Used to check the penalties inputs, especially for refreshing models.

Guide to setup hyperparameters

1. Get correct hyperparameter names: All variables in paid_media_vars or organic_vars require hyperprameters and will be transformed by adstock & saturation. Difference between paid_media_vars and organic_vars is that paid_media_vars has spend that needs to be specified in paid_media_spends specifically. Run hyper_names() to get correct hyperparameter names. All names in hyperparameters must equal names from hyper_names(), case sensitive.

2. Get guidance for setting hyperparameter bounds: For geometric adstock, use theta, alpha & gamma. For both weibull adstock options, use shape, scale, alpha, gamma.

   • Theta: In geometric adstock, theta is decay rate. guideline for usual media genre: TV c(0.3, 0.8), OOH/Print/Radio c(0.1, 0.4), digital c(0, 0.3)

   • Shape: In weibull adstock, shape controls the decay shape. Recommended c(0.0001, 2). The larger, the more S-shape. The smaller, the more L-shape. Channel-type specific values still to be investigated

   • Scale: In weibull adstock, scale controls the decay inflexion point. Very conservative recommended bounce c(0, 0.1), because scale can increase adstocking half-life greatly. Channel-type specific values still to be investigated

   • Gamma: In s-curve transformation with hill function, gamma controls the inflexion point. Recommended bounce c(0.3, 1). The larger the gamma, the later the inflection point in the response curve

3. Set each hyperparameter bounds. They either contains two values e.g. c(0, 0.5), or only one value (in which case you've "fixed" that hyperparameter)

Helper plots

plot_adstock

Get adstock transformation example plot, helping you understand geometric/theta and weibull/shape/scale transformation

plot_saturation

Get saturation curve transformation example plot, helping you understand hill/alpha/gamma transformation

Examples

# \donttest{
media <- c("facebook_S", "print_S", "tv_S")
hyper_names(adstock = "geometric", all_media = media)

hyperparameters <- list(
  facebook_S_alphas = c(0.5, 3), # example bounds for alpha
  facebook_S_gammas = c(0.3, 1), # example bounds for gamma
  facebook_S_thetas = c(0, 0.3), # example bounds for theta
  print_S_alphas = c(0.5, 3),
  print_S_gammas = c(0.3, 1),
  print_S_thetas = c(0.1, 0.4),
  tv_S_alphas = c(0.5, 3),
  tv_S_gammas = c(0.3, 1),
  tv_S_thetas = c(0.3, 0.8)
)

# Define hyper_names for weibull adstock
hyper_names(adstock = "weibull", all_media = media)

hyperparameters <- list(
  facebook_S_alphas = c(0.5, 3), # example bounds for alpha
  facebook_S_gammas = c(0.3, 1), # example bounds for gamma
  facebook_S_shapes = c(0.0001, 2), # example bounds for shape
  facebook_S_scales = c(0, 0.1), # example bounds for scale
  print_S_alphas = c(0.5, 3),
  print_S_gammas = c(0.3, 1),
  print_S_shapes = c(0.0001, 2),
  print_S_scales = c(0, 0.1),
  tv_S_alphas = c(0.5, 3),
  tv_S_gammas = c(0.3, 1),
  tv_S_shapes = c(0.0001, 2),
  tv_S_scales = c(0, 0.1)
)
# }