generate.simpr_spec: Generate simulated data from specification

Description

Use specification from specify or define to produce simulated data.

Usage

# S3 method for simpr_spec
generate(
  x,
  .reps,
  ...,
  .sim_name = "sim",
  .quiet = TRUE,
  .warn_on_error = TRUE,
  .stop_on_error = FALSE,
  .debug = FALSE,
  .progress = FALSE,
  .options = furrr_options(seed = TRUE)
)

Value

a simpr_sims object, which is a tibble with a row for each repetition (a total of rep

repetitions) for each combination of metaparameters and some extra metadata used by fit. The columns are rep for the repetition number, the names of the metaparameters, and a list-column (named by the argument

sim_name) containing the dataset for each repetition and metaparameter combination. simpr_sims objects can be manipulated elementwise by dplyr and

tidyr verbs: the command is applied to each element of the simulation list-column.

Arguments

x: a simpr_spec object generated by define or specify, containing the specifications of the simulation
.reps: number of replications to run (a whole number greater than 0)
...: filtering criteria for which rows to simulate, passed to filter. This is useful for reproducing just a few selected rows of a simulation without needing to redo the entire simulation, see vignette("Reproducing simulations"),
.sim_name: name of the list-column to be created, containing simulation results. Default is "sim"
.quiet: Should simulation errors be broadcast to the user as they occur?
.warn_on_error: Should there be a warning when simulation errors occur? See vignette("Managing simulation errors").
.stop_on_error: Should the simulation stop immediately when simulation errors occur?
.debug: Run simulation in debug mode, allowing objects, etc. to be explored for each generated variable specification.
.progress: A logical, for whether or not to print a progress bar for multiprocess, multisession, and multicore plans.
.options: The future specific options to use with the workers when using futures. This must be the result from a call to furrr_options(seed = TRUE).

Details

This is the third step in the simulation process: after specifying the population model and defining the metaparameters, if any, generate is the workhorse function that actually generates the simulated datasets, one for each replication and combination of metaparameters. You likely want to use the output of generate to fit model(s) with fit.

Errors you get using this function usually have to do with how you specified the simulation in specify and define.

Examples

Run this code

meta_list_out = specify(a = ~ MASS::mvrnorm(n, rep(0, 2), Sigma = S)) %>%
  define(n = c(10, 20, 30),
       S = list(independent = diag(2), correlated = diag(2) + 2)) %>%
  generate(1)

 ## View overall structure of the result and a single simulation output
 meta_list_out

 ## Changing .reps will change the number of replications and thus the number of
 ## rows in the output
 meta_list_2 = specify(a = ~ MASS::mvrnorm(n, rep(0, 2), Sigma = S)) %>%
  define(n = c(10, 20, 30),
       S = list(independent = diag(2), correlated = diag(2) + 2)) %>%
  generate(2)

 meta_list_2

 ## Fitting, tidying functions can be included in this step by running those functions and then
 ## generate.  This can save computation time when doing large
 ## simulations, especially with parallel processing
 meta_list_generate_after = specify(a = ~ MASS::mvrnorm(n, rep(0, 2), Sigma = S)) %>%
  define(n = c(10, 20, 30),
       S = list(independent = diag(2), correlated = diag(2) + 2)) %>%
  fit(lm = ~ lm(a_2 ~ a_1, data = .)) %>%
  tidy_fits %>%
  generate(1)

  meta_list_generate_after