A Function to Perform Scenario Analysis for a Generic Model Object.

This function uses parameter permutations produced by generate_parameter_permutations to simulate from a supplied model function. It can be used to examine multiple scenarios, with any number of parameter variations, for multiple samples.

scenario_analysis(
  parameter_df,
  variable_params = NULL,
  model = NULL,
  sim_fn = NULL,
  summary_fn = NULL,
  cores = 1,
  rerun = FALSE,
  verbose = FALSE,
  by_row = FALSE,
  test = FALSE,
  ...
)

Arguments

parameter_df	A dataframe of parameter permutations as produced by generate_parameter_permutations. Using the default options it will save results when run for the first time, and afterwards load them in.
variable_params	A character vector containing the names of the paramters that are varied in parameter_df.
model	A model compatible with your sim_fn.
sim_fn	A generic simulation function, with the first argument as the model object, a params argument, and a as.data.frame argument.
summary_fn	A function which accepts a single dataframe argument customised to fit with the standard output of scenario_analysis and your simulate_model function. Defaults to NULL for which no summarisation takes place. Warning: If a previous analysis has been saved, changing this option will not summarise the result. The analysis must be rerun.
cores	The number of cores to use for the scenario analysis, defaults to 1.
rerun	A logical indicating if the function should be rerun or saved results should be loaded. Defaults to FALSE.
verbose	Logical (defaults to FALSE) indicating if progress information should be printed to the console.
by_row	Logical (defaults to FALSE) indicating if inputed parameters should be inputed as a block to sim_fn or individually. If TRUE then function will always return a tibble. Does not currently work with sim_fn that produces multiple simulations for a single parameter set - for this scenario a block based approach or post processing is required.
test	A logical (defaults to FALSE) if TRUE function uses multicore functionality regardless of the number of cores specified.
...	Pass additional arguments to sim_fn. Only implemented when a single core is used.

Value

A tidy dataframe containing simulated model trajectories for each scenario varied parameter combination. Use unnest to examine all simulation results.

Examples

scenarios <- data.frame(scenario = c("test_1", "test_2"), scenario_param = c(0, 1))
variable_params <-  data.frame(variable = c(0, 0.5, 1))
fixed_params <- c(fixed_1 = 2, fixed_2 = c(1, 3, 4))
sample_params <- c(sample_1 = 2, sample_2 = c(2, 1))

parameter_df <- generate_parameter_permutations(variable_params, fixed_params, sample_params,
                                                excluded_params = c("variable"), scenarios,
                                                parameter_samples = 10)

## set up dummy simulation function (returning an empty dataframe)
dummy_sim_fn <- function(object, inits, params, times, as.data.frame) {
 x <- tibble::tibble()
 return(x)
}

## Set up dummy summary function
dummy_sum_fn <- function(df){
df <- dplyr::mutate(df, summarised_simulations = simulations)

return(df)
}
dummy_model <- function(){}

## Run scenario analysis
scenario_analysis(parameter_df, variable_params = "variable", model = dummy_model,
                  sim_fn = dummy_sim_fn, cores = 1, summary_fn = dummy_sum_fn)
#> # A tibble: 6 x 5
#>   scenario variable parameters        simulations      summarised_simulations
#>   <chr>       <dbl> <list>            <list>           <list>                
#> 1 test_1        0   <tibble [10 × 9]> <tibble [0 × 0]> <tibble [0 × 0]>      
#> 2 test_2        0   <tibble [10 × 9]> <tibble [0 × 0]> <tibble [0 × 0]>      
#> 3 test_1        0.5 <tibble [10 × 9]> <tibble [0 × 0]> <tibble [0 × 0]>      
#> 4 test_2        0.5 <tibble [10 × 9]> <tibble [0 × 0]> <tibble [0 × 0]>      
#> 5 test_1        1   <tibble [10 × 9]> <tibble [0 × 0]> <tibble [0 × 0]>      
#> 6 test_2        1   <tibble [10 × 9]> <tibble [0 × 0]> <tibble [0 × 0]>