Simulate multiple data sets, caching the result on disk

Description

A caching wrapper around sim_pop_data_multi(), which dominates the runtime of most simulation studies. The first call simulates and saves; later calls with the same arguments load the saved result instead of re-simulating.

Usage

sim_pop_data_multi_cached(
  ...,
  cache_path = "cache/",
  cache_id = "sim_pop_data_multi",
  cache_rerun = FALSE,
  cache_verbose = TRUE,
  cache_extra = NULL
)

Arguments

…	Arguments passed on to sim_pop_data_multi nclus number of clusters rng_seed starting seed for random number generator, passed to rngtools::RNGseq() sample_sizes sample sizes to simulate lambdas incidence rate, in events/person*year num_cores number of cores to use for parallel computations verbose whether to report verbose information sim_function which function to use: sim_pop_data() or sim_pop_data_2()
cache_path	a character() of length 1: the directory in which to store cache files. A trailing slash is added if absent (see .validate_cache_path()). Results are written to cache_path/cache_id/.
cache_id	a character() of length 1: a stable identifier for this cache entry. Distinct calls sharing a cache_path need distinct cache_ids.
cache_rerun	a logical() of length 1: whether to discard any existing cache and recompute. The freshly computed result is saved, so later calls with cache_rerun = FALSE reuse it.
cache_verbose	a logical() of length 1: whether to report cache hits and misses via cli::cli_inform().
cache_extra	an object folded into the cache key alongside the arguments. NULL (the default) keys the cache on the arguments alone. See the note on implementation changes in sim_pop_data_multi_cached().

Details

The cache is keyed on the arguments, so changing any of them (a new lambdas vector, a different nclus) recomputes automatically, and restoring the old arguments reuses the old result. Argument order and formatting do not matter.

The cache is not keyed on the implementation. If sim_pop_data_multi() or the functions it calls change, an existing cache stays valid as far as this wrapper is concerned. Pass cache_rerun = TRUE once to refresh it, or fold a version into the key with, for example, cache_extra = utils::packageVersion(“serocalculator”). That is deliberately not the default: a development version bumps often, which would discard the cache on nearly every commit.

Value

a tibble::tibble(), as returned by sim_pop_data_multi().

See Also

est_seroincidence_by_cached()

Examples

library("serocalculator")


antibodies <- c("HlyE_IgA", "HlyE_IgG")

# Examples must not write into the user's working directory, so send the
# cache to a temporary one. `cache_path` gains its trailing slash
# automatically.
cache_dir <- file.path(tempdir(), "serocalculator-example-cache")

sim_df <- sim_pop_data_multi_cached(
  curve_params = typhoid_curves_nostrat_100,
  lambdas = c(0.05, 0.1),
  nclus = 2,
  sample_sizes = 50,
  age_range = c(0, 10),
  antigen_isos = antibodies,
  num_cores = 1,
  add_noise = TRUE,
  noise_limits = rbind(
    HlyE_IgA = c(min = 0, max = 0.5),
    HlyE_IgG = c(min = 0, max = 0.5)
  ),
  format = "long",
  cache_path = cache_dir
)

nrow(sim_df)

[1] 400

# Calling again with the same arguments loads the saved result instead of
# re-simulating.
sim_df2 <- sim_pop_data_multi_cached(
  curve_params = typhoid_curves_nostrat_100,
  lambdas = c(0.05, 0.1),
  nclus = 2,
  sample_sizes = 50,
  age_range = c(0, 10),
  antigen_isos = antibodies,
  num_cores = 1,
  add_noise = TRUE,
  noise_limits = rbind(
    HlyE_IgA = c(min = 0, max = 0.5),
    HlyE_IgG = c(min = 0, max = 0.5)
  ),
  format = "long",
  cache_path = cache_dir
)

identical(sim_df, sim_df2)

[1] TRUE