mrgsim.parallel (version 0.3.0)

bg_mrgsim_d: Run mrgsim in the background

Description

This function uses callr::r_bg() to simulate a dataset in the background, optionally in parallel and optionally saving the results directly to disk in fst, arrow or rds format. Parallelization can be mediated by the parallel package on unix or macos or future on any os.

Usage

bg_mrgsim_d(
  mod,
  data,
  nchunk = 1,
  ...,
  .locker = NULL,
  .tag = NULL,
  .format = c("fst", "feather", "parquet", "rds"),
  .wait = TRUE,
  .seed = FALSE,
  .cores = 1,
  .plan = NULL
)

Value

An r_process object; see callr::r_bg(). Call process$get_result() to get the actual result (see details). If a .locker path is supplied, the simulated data is saved to disk and a list of file names is returned.

Arguments

mod

A model object.

data

Data set to simulate; see mrgsolve::data_set().

nchunk

Number of chunks in which to split the data set; chunking will be based on the ID column, which is required in data.

...

Arguments passed to mrgsolve::mrgsim().

.locker

A directory for saving simulated data; use this to collect results from several different runs in a single folder.

.tag

A name to use for the current run; results are saved under .tag in .locker folder.

.format

The output format for saving simulations; using format fst will allow saved results to be read with fst::read_fst(); using format arrow will allow saved results to be read with arrow::open_dataset() with format = "feather" or format = "parquet"; note that fst is installed with mrgsim.parallel but arrow may need explicit installation.

.wait

If FALSE, the function returns immediately; if TRUE, then wait until the background job is finished.

.seed

A numeric value used to set the seed for the simulation; this is the only way to control the random number generation for your simulation.

.cores

The number of cores to parallelize across; pass 1 to run the simulation sequentially.

.plan

The name of a future::plan() strategy; if passed, the parallelization will be handled by the future package.

Details

bg_mrgsim_d() returns a processx::process object (follow that link to see a list of methods). You will have to call process$get_result() to retrieve the result. When an output .locker is not specified, simulated data are returned; when an output .locker is specified, the path to the fst file on disk is returned. The fst files should be read with fst::read_fst(). When the results are not saved to .locker, you will get a single data frame when nchunk is 1 or a list of data frames when nchunk is greater than 1. It is safest to call dplyr::bind_rows() or something equivalent on the result if you are expecting data frame.

See Also

future_mrgsim_d(), internalize_fst(), list_fst(), head_fst(), setup_locker()

Examples

mod <- mrgsolve::house(delta = 24, end = 168)
data <- mrgsolve::expand.ev(
  amt = c(100, 300, 450), 
  ID = 1:100, 
  ii = 24, 
  addl = 6
)
data <- dplyr::mutate(data, dose = amt)
process <- bg_mrgsim_d(
  mod, 
  data, 
  carry_out = "dose", 
  outvars = "CP",
  .wait = TRUE
) 
process$get_result()
 
 
ds <- file.path(tempdir(), "sims")
files <- bg_mrgsim_d(
  mod, data, carry_out = "dose", 
  .wait = TRUE, 
  .locker = ds,
  .format = "fst"
)
files
sims <- internalize_fst(ds)
head(sims)