Simulist- an R package to simulate linelists

[CarmenTamayo]

Simulist: tools to generate simulated linelist data

Description

This R package would provide tools to simulate epidemic's raw case data in the form of line lists, using model outputs, such as compartmental models, branching processes, or network models.

*Potential feature: this package could also include a function to simulate contact tracing data that complements the generated line lists.

R packages such as outbreak or ringbp , offer the possibility to simulate outbreak data (e.g., epicurves) and/or provide the user with a number of already simulated line lists to work with. However, currently available packages do not have the functionality to simulate line list data from scratch.

Simulist would allow users to generate line lists that are tailored to their specific circumstances, by easily being able to modify the number of epidemic cases, the dates of disease onset and case hospitalisation/death, as well as exposure dates. This way, the user would have full control over the simulated raw data and be able to incorporate changes as their models develop.

*If the functionality to generate contact tracing data is included in the package, end-users would be able to generate a contact database that matches the cases included in the simulated line list.

Target audience

• typical end-users: epidemiologists that want to simulate raw case data from an epidemic, either to test interventions such as contact tracing strategies or develop training materials for students or for academic use, e.g., workshops.

• potential contributors: members of the Epiverse team

• key collaborators: end-users to provide use cases and improve the functionality of the package

Interoperability

• inputs: a data.frame or tibble that contains the specified model's output, which must include information about the epidemic's incidence over time.

• outputs: a data.frame or tibble where rows represent epidemic cases and columns contain information about their dates of symptom onset and potential hospitalisations or deaths.

• imports:

  • epiparameter
  • bpmodels
  • epirecipes
  • ...

• used by:

  • linelist
  • readepi
  • ...

Usage

The code below illustrates a typical use of the package, using fictitious code and outputs if needed:

library(simulist)

# Use case 1: linelist simulation
model_output %>%
  add_delays() %>%
  convert_to_dates() %>%
  add_demographic_info(age, sex) %>%
  add_case_info(type, ct value) %>%
  add_case_names()


# Use case 2: contact database
simulated_linelist %>%
  extract_cases() %>%
  add_contacts(contact characteristics specification) %>%
  add_exposure_dates() %>%
  add_contact_names()

[jamesmbaazam]

Hi Carmen, I believe this is a great idea and I'm actually quite surprised that such a package doesn't already exist.

I think this package should make it easy to quickly (ease of use) and speedily (fast) synthesise the data. Building on the previous point, I, therefore, think that the piped operations you suggested under use-case 1 should rather run under the hood. An example set of operations under use-case 1 could be

case_time_series %>%
    expand_to_linelist() %>%
    summarise() %>%
    communicate()

[jamesmbaazam]

This potential package could address the issue in bpmodels.

[jamesmbaazam]

There is existing functionality out there that we might want to consider in developing this package:

• epidist via epidist::gen_data()
• EpiNow
• simulacr via simulacr::simulate_outbreak()

Most of these are either in dev but unstable or no longer in dev so, there is a case for developing simulist as it could be useful for internal use, teaching, and dev elsewhere.

[pratikunterwegs]

Just coming to this thread after discussion today - happy to help too with packaging up or reviewing, as required.

[joshwlambert]

Thanks @CarmenTamayo for posting this discussion, and thanks to @jamesmbaazam for input. Carmen and I have started developing the {simulist} package as part of the Epiverse-TRACE organisation.

We will work towards an MVP containing the functionality outlined in the above posts on this discussion. Once it is ready for feedback we will reach out to the rest of the team for input.

Please post comments on the issues section of the github repo and not here to keep the work as centralised as possible. I will close this thread once a working version of the package is up and running.

[joshwlambert]

The {simulist} package is now up and running and approaching an MVP. Therefore, I'm going to close this discussion board and all further comments can be send to the {simulist} GitHub repository issues page.