Design Principles for {simulist} • simulist

This vignette outlines the design decisions that have been taken during the development of the {simulist} R package, and provides some of the reasoning, and possible pros and cons of each decision.

This document is primarily intended to be read by those interested in understanding the code within the package and for potential package contributors.

Scope

The {simulist} package aims to simulate data on infectious disease outbreaks, primarily line list data, but also contacts data. Each of these output types have an associated exported function: sim_linelist() and sim_contacts(). There is also a function to simulate and output both of these data types, sim_outbreak(). This latter function is useful for interoperability with the {epicontacts} R package (see visualisation vignette), and provides linked line list and contacts datasets, which are common in outbreaks, such as the MERS dataset within the {outbreaks} R package.

Output

The simulation functions either return a <data.frame> or a list of <data.frame>s. This consistency across functions of a well-known data structure makes it easy to understand for users.

Package architecture

Design decisions

When using age-stratified risks of hospitalisation and deaths (see Age-stratified hospitalisation and death risks vignette for details) there is an interaction between function arguments. The <data.frame> that defines the age-stratification in hosp_risk, hosp_death_risk and non_hosp_death_risk arguments gives the lower bound of the age groups. The upper bound of the age groups is derived from the next lower bound, but the upper bound oldest age group is defined by the upper age given to the population_age argument. This interaction of arguments is not ideal, as it can be more difficult to understand for users (as outlined in The Tidy Design book), however, the interaction does not change the interpretation of each argument which would be more convoluted. This design decision was taken when we changed the structure of the <data.frame> accepted as input to the *_risk arguments from having two columns for a lower and upper age limit, to a single column of lower age bounds. This change was made in pull request #14 and follows the design of {socialmixr} for defining age bounds. The newer structure is judged to be preferred as it prevents input errors by the user when the age bounds are overlapping or non-contiguous (i.e. missing age groups).
The column names of the contact relationships (edges of the network) are called from and to. Names of the contacts table match {epicontacts} <epicontacts> objects. If the column names of the two contacts provided to epicontacts::make_epicontacts() arguments from and to are not from and to they will be silently renamed in the resulting <epicontacts> object. By making these column names from and to when output from sim_contacts() or sim_outbreak() it prevents any confusion when used with {epicontacts}. This naming is also preferred as they are usefully descriptive.
Exported functions that simulate data use the naming convention sim_*() (where * is the placeholder). Internal functions that simulate have a dot (.) prefix (e.g. .sim_internal()). Functions that create fixed data structures (i.e. data factory functions) have the naming convention (create_*() or .create_*()).
The use of a config argument in the simulation function is to reduce the number of arguments in the exported functions and provide as simple a user-interface as possible. The choice of what gets an argument in the function body and what is confined to config list is based on preconceived frequency of use, importance and technical detail. That is to say, settings that are unlikely to be changed by the user or if they are changed require an advanced understanding of the simulation model are placed within the config, and given default values with create_config().
Input checking of the config list takes place within the call stack of exported sim_*() functions when certain elements of the config list are used, and not in the create_config() function. Therefore, it is possible to create an invalid config list with create_config(). An example of throwing an error from an internal function of the simulation is if config$network is not "adjusted" or "unadjusted", or is NULL it will error in .sim_network_bp().
The column names of the line list data produced by sim_linelist() and sim_outbreak() matches the tag names used in the {linelist} R package (an Epiverse-TRACE R package). This is for continuity of design more than any functional reason. The line list data from {simulist} functions is not tagged sensu {linelist} tagging. There is an inconsistent use of hospitalisation and admission; in the simulated line list it is date_admission, but internally the package uses hospitalisation (e.g. .add_hospitalisation()). This is because I think hospitalisation is more descriptive but date_admission is used by {linelist}.
{simulist} implements its own branching process model (.sim_network_bp()) which tracks contacts of infectious individuals. This is a simple random network model, but for future versions of {simulist} we will make the code modular in order to accept other simulations models. This will remove the burden on {simulist} to simulate from a range of model types.
The sim_linelist(), sim_contacts() and sim_outbreak() do not have arguments that change the dimensions of the <data.frame> returned by the functions (or in the case of sim_outbreak() a list of two <data.frame>s). Instead, we recommend modifying the line list or contact tracing data after the simulation, and provide a vignette to guide users on common data wrangling tasks in wrangling-linelist.Rmd. Not including arguments that can remove or add columns to the output <data.frame>s reduces the complexity of the functions; and by limiting the simulation function arguments to only parameterise, and not change the dimensionality of, the simulated data, the package is more robust to being used in pipelines or other automated approaches, where the data needs to be predictably formatted.
Several parts of the {simulist} codebase use indices for determining which individual are infected, allocation to vectors, and other uses. R’s subsetting ([) can use logical vectors or numeric vectors, but in {simulist} these are differentiated by the names *_idx for variables holding a numeric vector of indices, and *_lgl_idx for a logical vector of indices. This makes it safer and more readable to call functions like sum() or which() on index vectors.

Dependencies

The aim is to restrict the number of dependencies to a minimal required set for ease of maintenance. The current hard dependencies are:

{stats} is distributed with the R language so is viewed as a lightweight dependency, that should already be installed on a user’s machine if they have R. {checkmate} is an input checking package widely used across Epiverse-TRACE packages. {epiparameter} is used to easily access epidemiological parameters from the package’s library, the package is currently unstable and actively developed, however, by using it in another package it can inform the development path of {epiparameter}. {randomNames} provides a utility function for generating random names for case and contact data. The functionality could be replicated in {simulist}, however the {randomNames} package is maintained and contains a range of name generation settings which warrants its use as a dependency.

The soft dependencies (and their minimum version requirements) are:

{knitr}, {rmarkdown}, are all used for generating documentation. {spelling} and {testthat} are used for testing the code base. {ggplot2} is used for plotting within the vignettes. {incidence2} and {epicontacts} are used in vignettes to demonstrate interoperability with downstream packages, with a focus on data visualisation.

Contribute

There are no special requirements to contributing to {simulist}, please follow the package contributing guide.