Run a Parallelized Monte Carlo Simulation

future_mc runs a Monte Carlo simulation study for a user-specified function and the desired parameter grids.

Usage

future_mc(
  fun,
  repetitions,
  param_list = NULL,
  param_table = NULL,
  parallelisation_plan = list(strategy = future::multisession),
  parallelisation_options = list(),
  check = TRUE,
  parallel = TRUE,
  ...
)

Arguments

fun: The function to be evaluated. See details.
repetitions: An integer that specifies the number of Monte Carlo iterations
param_list: A list whose components are named after the parameters of fun which should vary for the different Monte Carlo Simulations. Each component is a vector containing the desired grid values for that parameter. The Monte Carlo Simulation is run for all possible combinations of that parameter list.
param_table: Alternative to param_list. A data.frame or data.table containing a pre-built grid of values, where the columns are the parameters of fun which should vary for the different Monte Carlo Simulations. This is useful if you only want to run a Monte Carlo Simulation for a subset of all possible combinations.
parallelisation_plan: A list whose components are named after possible parameters of future::plan() specifying the parallelisation plan which should be used in the Monte Carlo Simulation. Default is strategy = multisession.
parallelisation_options: A list whose components are named after possible parameters of furrr::furrr_options() for fine tuning functions, such as furrr::future_map(). Default is seed = TRUE as long as not specified differently in order to assure reproducibility.
check: Boolean that specifies whether a single test-iteration should be run for each parameter combination in order to check for possible occuring errors in fun. Default is TRUE.
parallel: Boolean that specifies whether the Monte Carlo simulation should be run in parallel. Default is TRUE.
...: Additional parameters that are passed on to fun and which are not part of the parameter grid.

Value

A list of type mc containing the following objects:

output: A tibble containing the return value of fun for each iteration and parameter combination
parameter: A tibble which shows the different parameter combinations
simple_output: A boolean value indicating whether the return value of fun is a named list of scalars or not
nice_names: A character vector containing "nice names" for the different parameter setups
calculation_time: The calculation time needed to run the whole Monte Carlo Simulation
n_results: A numeric value indicating the number of results
seed: The value which is used for the parameter seed in furrr::furrr_options()
fun: The user-defined function fun
repetitions: The number of repetitions run for each parameter setup
parallel: Boolean whether the Monte Carlo Simulation was run in parallel or not
plan: A list that specified the parallelisation plan via future::plan()

Details

The user defined function fun handles (if specified) the generation of data, the application of the method of interest and the evaluation of the result for a single repetition and parameter combination. future_mc handles the generation of loops over the desired parameter grids and the repetition of the Monte Carlo experiment for each of the parameter constellations.

There are four formal requirements that fun has to fulfill:

The arguments of fun which are present in param_list need to be scalar values.
The value returned by fun has to be a named list and must have the same components for each iteration and parameter combination.
The names of the returned values and those of the arguments contained in param_list need to be different. Moreover, they cannot be "params", "repetitions" or "setup"
Every variable used inside fun has either to be defined inside fun or given as an argument through the ... argument. In particular, fun cannot use variables which are only defined in the global environment.

In order to use the comfort functions plot.mc(), summary.mc(), plot.summary.mc(), and tidy_mc_latex() the value returned by fun has to be a named list of scalars.

Examples


test_func <- function(param = 0.1, n = 100, x1 = 1, x2 = 2) {
  data <- rnorm(n, mean = param) + x1 + x2
  stat <- mean(data)
  stat_2 <- var(data)

  if (x2 == 5) {
    stop("x2 can't be 5!")
  }

  return(list(mean = stat, var = stat_2))
}

param_list <- list(
  param = seq(from = 0, to = 1, by = 0.5),
  x1 = 1:2
)

set.seed(101)
test_mc <- future_mc(
  fun = test_func,
  repetitions = 1000,
  param_list = param_list,
  n = 10,
  x2 = 2
)
#> Running single test-iteration for each parameter combination...
#> 
#>  Test-run successfull: No errors occurred!
#> Running whole simulation: Overall 6 parameter combinations are simulated ...
#> 
#>  Simulation was successfull!
#>  Running time: 00:00:00.968766