run_multiple: Run multiple simulations at once

In epiworldR: Fast Agent-Based Epi Models

Run multiple simulations at once

Description

The run_multiple function allows running multiple simulations at once. When available, users can take advantage of parallel computing to speed up the process.

Usage

run_multiple(
  m,
  ndays,
  nsims,
  seed = sample.int(10000, 1),
  saver = make_saver(),
  reset = TRUE,
  verbose = TRUE,
  nthreads = 1L
)

run_multiple_get_results(
  m,
  nthreads = min(2L, parallel::detectCores()),
  freader = NULL,
  ...
)

make_saver(..., fn = "")

Arguments

m, ndays, seed	See run.
nsims	Integer. Number of replicats
saver	An object of class epiworld_saver.
reset	When TRUE (default,) resets the simulation.
verbose	When TRUE (default,) prints a progress bar.
nthreads	Integer. Number of threads (passed to parallel::makeCluster()).
freader	A function to read the files. If NULL (default,) uses utils::read.table.
...	Additional arguments passed to freader.
fn	A file name pattern.

Details

Currently, the following elements can be saved:

Keyword	Description	Function
total_hist	History of the model (total numbers per time).	get_hist_total()
virus_info	Information about viruses.
virus_hist	Changes in viruses.	get_hist_virus()
tool_info	Information about tools.
tool_hist	Changes in tools.	get_hist_tool()
transmission	Transmission events.	get_transmissions()
transition	Transition matrices.	get_hist_transition_matrix()
reproductive	Reproductive number.	get_reproductive_number()
generation	Estimation of generation time.	get_generation_time()
active_cases	Number of active cases per virus.	get_active_cases()
outbreak_size	Size of outbreaks per virus.	get_outbreak_size()
hospitalizations	Number of hospitalizations per virus/tool.	get_hospitalizations()

An alternative to using the default utils::read.table function is to use data.table::fread from the data.table package. This can be done by specifying freader = data.table::fread and passing additional arguments (e.g., nThread = 2L) via .... This can significantly speed up the reading process, especially for large datasets.

If the model does not have, for example, tools, then the corresponding data frame will be empty (0 rows). A warning will be issued in this case when trying to retrieve or plot the results.

Value

• In the case of make_saver, an list of class epiworld_saver.

• The run_multiple function runs a specified number of simulations and returns a model object of class epiworld_model.

• The run_multiple_get_results function returns a named list with the data specified by make_saver. Each entry will be a data.frame (default), or the output of freader.

Data structures

The datasets generated by run_multiple_get_results have the following columns:

• total_hist: date (integer), nviruses (integer), state (character), counts (integer).

• virus_info: virus_id (integer), virus (character), virus_sequence (character), date_recorded (integer), parent (integer)

• virus_hist: date (integer), virus_id (integer), virus (character), n (integer).

• tool_info: id (integer), tool_name (character), tool_sequence (character), date_recorded (integer).

• tool_hist: date (integer), id (integer), state (character), n (integer).

• transmission: date (integer), virus_id (integer), virus (character), source_exposure_date (integer), source (integer), target (integer).

• transition: date (integer), from (character), to (character), counts (integer).

• reproductive: virus_id (integer), virus (character), source (integer), source_exposure_date (integer), rt (integer).

• generation: virus (integer), source (integer), source_exposure_date (integer), generation_time (integer).

• active_cases: date (integer), virus_id (integer), virus (character), active_cases (integer).

• outbreak_size: date (integer), virus_id (integer), virus (character), outbreak_size (integer).

• hospitalizations: date (integer), virus_id (integer), tool_id (integer), counts (integer), and weight (numeric).

An important difference from the function get_reproductive_number() is that the returned reproductive number here includes a -1 in the column source. This is the reproductive number of the model as an agent, a number that matches the initial number of infected agents at the start of the model.

Examples

model_sir <- ModelSIRCONN(
  name = "COVID-19",
  prevalence = 0.01,
  n = 1000,
  contact_rate = 2,
  transmission_rate = 0.9, recovery_rate = 0.1
)

# Generating a saver
saver <- make_saver("total_hist", "reproductive")

# Running and printing
run_multiple(model_sir, ndays = 100, nsims = 50, saver = saver, nthreads = 2)

# Retrieving the results
ans <- run_multiple_get_results(model_sir, nthreads = 2)

head(ans$total_hist)
head(ans$reproductive)

# Plotting
multi_sir <- ans$total_hist
multi_sir <- multi_sir[multi_sir$date <= 20, ]
plot(multi_sir)

epiworldR documentation built on Feb. 21, 2026, 9:07 a.m.