doc: update demo.R

- adapted demo.R to match all new changes
- demo.R version bump to 3.12.0
- slight adaption of r&f plot title
- package documentation

Author: gufengzhou

R/R/calibration.R

@@ -85,7 +85,7 @@ robyn_calibrate <- function(
       curve_collect[[i]] <- robyn_calibrate_single_dim(
         df_curve = df_curve_i,
         curve_type,
-        force_shape = "c",
+        force_shape = "c", # assumption: reach saturation is always concave
         hp_bounds,
         max_trials,
         max_iters,
@@ -103,7 +103,8 @@ robyn_calibrate <- function(
       geom_point(aes(y = .data$response_cumulated, colour = .data$freq_bucket)) +
       geom_line(aes(y = .data$response_pred, colour = .data$freq_bucket), alpha = 0.5) +
       labs(
-        title = "Cumulative reach saturation fitting",
+        title = "Cumulative reach & frequency saturation fitting",
+        subtitle = "The dots are input R&F data. The lines are fitted curves.",
         x = "cumulative spend",
         y = "cumulative reach"
       ) +

R/R/inputs.R

@@ -468,39 +468,14 @@ Adstock: {x$adstock}
 #' hyperparameters that is inserted into \code{robyn_inputs(hyperparameters = ...)}
 #'
 #' @section Guide to setup hyperparameters:
-#'  \enumerate{
-#'    \item Get correct hyperparameter names:
-#'    All variables in \code{paid_media_vars} or \code{organic_vars} require hyperprameters
-#'    and will be transformed by adstock & saturation. Difference between \code{paid_media_vars}
-#'    and \code{organic_vars} is that \code{paid_media_vars} has spend that
-#'    needs to be specified in \code{paid_media_spends} specifically. Run \code{hyper_names()}
-#'    to get correct hyperparameter names. All names in hyperparameters must
-#'    equal names from \code{hyper_names()}, case sensitive.
-#'    \item Get guidance for setting hyperparameter bounds:
-#'    For geometric adstock, use theta, alpha & gamma. For both weibull adstock options,
-#'    use shape, scale, alpha, gamma.
-#'    \itemize{
-#'      \item 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)
-#'      \item 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
-#'      \item 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
-#'      \item 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
-#'    }
-#'    \item 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)
-#' }
+#' See section "Hyperparameter interpretation & recommendation" in demo
+#' https://github.com/facebookexperimental/Robyn/blob/main/demo/demo.R
 #'
 #' @section Helper plots:
 #' \describe{
-#'   \item{plot_adstock}{Get adstock transformation example plot,
+#'   \item{plot_adstock(TRUE)}{Get adstock transformation example plot,
 #' helping you understand geometric/theta and weibull/shape/scale transformation}
-#'   \item{plot_saturation}{Get saturation curve transformation example plot,
+#'   \item{plot_saturation(TRUE)}{Get saturation curve transformation example plot,
 #' helping you understand hill/alpha/gamma transformation}
 #' }
 #'
@@ -511,13 +486,13 @@ Adstock: {x$adstock}
 #' @param all_vars Used to check the penalties inputs, especially for refreshing models.
 #' @examples
 #' \donttest{
-#' media <- c("facebook_S", "print_S", "tv_S")
+#' media <- c("facebook_I", "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
+#'   facebook_I_alphas = c(0.5, 3), # example bounds for alpha
+#'   facebook_I_gammas = c(0.3, 1), # example bounds for gamma
+#'   facebook_I_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),
@@ -527,13 +502,13 @@ Adstock: {x$adstock}
 #' )
 #'
 #' # Define hyper_names for weibull adstock
-#' hyper_names(adstock = "weibull", all_media = media)
+#' hyper_names(adstock = "weibull_pdf", 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
+#'   facebook_I_alphas = c(0.5, 3), # example bounds for alpha
+#'   facebook_I_gammas = c(0.3, 1), # example bounds for gamma
+#'   facebook_I_shapes = c(0.0001, 2), # example bounds for shape
+#'   facebook_I_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),