Simulates a serological survey using user-specified inputs and models.
runserosim(
simulation_settings,
demography = NULL,
observation_times = NULL,
foe_pars,
biomarker_map,
model_pars,
exposure_model,
immunity_model,
antibody_model,
observation_model,
draw_parameters,
immune_histories_fixed = NULL,
VERBOSE = NULL,
attempt_precomputation = TRUE,
parallel = FALSE,
n_cores = 4,
parallel_packages = NULL,
...
)A list of parameters governing the simulation time step settings. Should contain integer entries for t_start and t_end
A tibble of demographic information for each individual in the simulation. At a minimum this tibble requires 1 column (i) where all individuals in the simulation are listed by row. This is used to calculate the sample population size. Additional variables can be added by the user, e.g., birth and removal times, see generate_pop_demography If not specified, the model will assume that birth time is the initial time point and removal time is the final time point across all individuals
A tibble for observation times with three variables: 1) i: individual; 2) t: the timepoint of an observation; 3) b: the biomarker being measured. Defaults to NULL, in which case all latent biomarker states are returned
Any object class (usually a 3D array, but may be a list or other object) providing the force of exposure for each exposure ID, group and time, or parameters of the model generating the FOEs
A tibble specifying the relationship between exposure IDs and biomarker IDs with two variables: 1) exposure_id: the numeric exposure ID; 2) biomarker_id: the numeric biomarker ID
A tibble of parameters needed for the antibody kinetics model, immunity model, observation model and the draw_parameters function
A function calculating the probability of exposure given the foe_pars array
A function determining the probability of an exposure leading to successful infection or vaccination for a given individual
A function determining the latent biomarker kinetics as a function of immune history and within-host kinetics parameters (model_pars)
A function generating observed biomarkers as a function of latent biomarkers and observation model parameters (model_pars)
A function to simulate parameters for the antibody model, immunity model and observation model from model_pars
(optional) Defaults to NULL. Otherwise a 3D array indicating the immune history (1 = exposed, 0 = not exposed) for each individual (dimension 1) at each time (dimension 2) for each exposure ID (dimension 3). Here, users can input pre-specified information if immune histories are known for an individual
(optional) Defaults to NULL. An integer specifying the frequency at which simulation progress updates are printed
If TRUE, attempts to perform as much pre-computation as possible for the exposure model to speed up the main simulation code. If FALSE, skips this step, which is advised when the simulation is expected to be very fast anyway
If TRUE, attempts to run serosim using parallel processes with the foreach and parallel packages. Defaults to FALSE
The number of cores to use if running in parallel. Defaults to 4
a character vector of R packages required for the models. Only needed if additional non-imported packages are required.
Any additional arguments needed for the models
a list containing the following elements: force of exposure, exposure probabilities, immune histories, antibody states, observed antibody states, and kinetics parameters
The runserosim function is designed as a plug-and-play multi-level model representing the different stages of the data-generating process for serological data. The user can specify inputs controlling population demography, simulation time period, observation times for each individual, force of exposure, and various model functions describing the link between infections and observed biomarker quantities. See README for full details of the workflow.
There are two optional flags to attempt speed ups with serosim: attempt_precomputation and parallel. attempt_precomputation will check how many interchangeable individuals there are and pre-compute exposure probabilities for these individuals if that would be quicker than solving for each individual separately. parallel uses the foreach package with dopar to run serosim for blocks of individuals on a socket cluster. The number of cores is set with the n_cores argument. If any additional packages are needed for the model, then the parallel_packages argument should be set.
## See package README.