Robyn (version 3.11.1)

robyn_refresh: Build Refresh Model

Description

robyn_refresh() builds updated models based on the previously built models saved in the Robyn.RDS object specified in robyn_object. For example, when updating the initial build with 4 weeks of new data, robyn_refresh() consumes the selected model of the initial build, sets lower and upper bounds of hyperparameters for the new build around the selected hyperparameters of the previous build, stabilizes the effect of baseline variables across old and new builds, and regulates the new effect share of media variables towards the latest spend level. It returns the aggregated results with all previous builds for reporting purposes and produces reporting plots.

You must run robyn_save() to select and save an initial model first, before refreshing.

When should robyn_refresh() NOT be used: The robyn_refresh() function is suitable for updating within "reasonable periods". Two situations are considered better to rebuild model instead of refreshing:

1. Most data is new: If initial model was trained with 100 weeks worth of data but we add +50 weeks of new data.

2. New variables are added: If initial model had less variables than the ones we want to start using on new refresh model.

Usage

robyn_refresh(
  json_file = NULL,
  robyn_object = NULL,
  dt_input = NULL,
  dt_holidays = Robyn::dt_prophet_holidays,
  refresh_steps = 4,
  refresh_mode = "manual",
  refresh_iters = 1000,
  refresh_trials = 3,
  bounds_freedom = NULL,
  plot_folder = NULL,
  plot_pareto = TRUE,
  version_prompt = FALSE,
  export = TRUE,
  calibration_input = NULL,
  objective_weights = NULL,
  ...
)
# S3 method for robyn_refresh
print(x, ...)
# S3 method for robyn_refresh
plot(x, ...)

Value

List. The Robyn object, class robyn_refresh.

List. Same as robyn_run() but with refreshed models.

Arguments

json_file

Character. JSON file to import previously exported inputs or recreate a model. To generate this file, use robyn_write(). If you didn't export your data in the json file as "raw_data", dt_input must be provided; dt_holidays input is optional.

robyn_object

Character or List. Path of the Robyn.RDS object that contains all previous modeling information or the imported list.

dt_input

data.frame. Should include all previous data and newly added data for the refresh.

dt_holidays

data.frame. Raw input holiday data. Load standard Prophet holidays using data("dt_prophet_holidays").

refresh_steps

Integer. It controls how many time units the refresh model build move forward. For example, refresh_steps = 4 on weekly data means the InputCollect$window_start & InputCollect$window_end move forward 4 weeks. If refresh_steps is smaller than the number of newly provided data points, then Robyn would only use the first N steps of the new data.

refresh_mode

Character. Options are "auto" and "manual". In auto mode, the robyn_refresh() function builds refresh models with given refresh_steps repeatedly until there's no more data available. I manual mode, the robyn_refresh() only moves forward refresh_steps only once. "auto" mode has been deprecated when using json_file input.

refresh_iters

Integer. Iterations per refresh. Rule of thumb is, the more new data added, the more iterations needed. More reliable recommendation still needs to be investigated.

refresh_trials

Integer. Trials per refresh. Defaults to 5 trials. More reliable recommendation still needs to be investigated.

bounds_freedom

Numeric. Percentage of freedom we'd like to allow for the new hyperparameters values compared with the model to be refreshed. If set to NULL (default) the value will be calculated as refresh_steps / rollingWindowLength. Applies to all hyperparameters.

plot_folder

Character. Path for saving plots and files. Default to robyn_object and saves plot in the same directory as robyn_object.

plot_pareto

Boolean. Set to FALSE to deactivate plotting and saving model one-pagers. Used when testing models.

version_prompt

Logical. If FALSE, the model refresh version will be selected based on the smallest combined error of normalized NRMSE, DECOMP.RSSD, MAPE. If TRUE, a prompt will be presented to the user to select one of the refreshed models (one-pagers and Pareto CSV files will already be generated).

export

Boolean. Export outcomes into local files?

calibration_input

data.frame. Optional. Provide experimental results to calibrate. Your input should include the following values for each experiment: channel, liftStartDate, liftEndDate, liftAbs, spend, confidence, metric. You can calibrate any spend or organic variable with a well designed experiment. You can also use experimental results from multiple channels; to do so, provide concatenated channel value, i.e. "channel_A+channel_B". Check "Guide for calibration source" section.

objective_weights

Numeric vector. Default to NULL to give equal weights to all objective functions. Order: NRMSE, DECOMP.RSSD, MAPE (when calibration data is provided). When you are not calibrating, only the first 2 values for objective_weights must be defined, i.e. set c(2, 1) to give double weight to the 1st (NRMSE). This is an experimental feature. There's no research on optimal weight setting. Subjective weights might strongly bias modeling results.

...

Additional parameters to overwrite original custom parameters passed into initial model.

x

robyn_refresh() output.

Examples

if (FALSE) {
# Loading dummy data
data("dt_simulated_weekly")
data("dt_prophet_holidays")
# Set the (pre-trained and exported) Robyn model JSON file
json_file <- "~/Robyn_202208081444_init/RobynModel-2_55_4.json"

# Run \code{robyn_refresh()} with 13 weeks cadence in auto mode
Robyn <- robyn_refresh(
  json_file = json_file,
  dt_input = dt_simulated_weekly,
  dt_holidays = Robyn::dt_prophet_holidays,
  refresh_steps = 13,
  refresh_mode = "auto",
  refresh_iters = 200,
  refresh_trials = 5
)

# Run \code{robyn_refresh()} with 4 weeks cadence in manual mode
json_file2 <- "~/Robyn_202208081444_init/Robyn_202208090847_rf/RobynModel-1_2_3.json"
Robyn <- robyn_refresh(
  json_file = json_file2,
  dt_input = dt_simulated_weekly,
  dt_holidays = Robyn::dt_prophet_holidays,
  refresh_steps = 4,
  refresh_mode = "manual",
  refresh_iters = 200,
  refresh_trials = 5
)
}