simulist v0.3.0

new-release
Author

The Epiverse-TRACE development team

Published

June 3, 2024

We are very excited to announce the release of a new simulist version v0.3.0. Here is an automatically generated summary of the changes in this version.

The third release of the simulist R package contains a range of new features, enhancements, documentation and unit tests.

The headline changes to the package are:

New features

External

  • onset_to_hosp and onset_to_death arguments can now take NA as input and will return a column of NAs in the line list columns date_admission and date_outcome (#98).

  • An onset_to_recovery argument has been added to the simulation functions, sim_linelist() and sim_outbreak(), and so the recovery date can be explicitly given in the line list data (#99).

  • The line list simulation can now use a time-varying case fatality risk. The create_config() function now returns a $time_varying_death_risk list element, which is NULL by default but can take an R function to enable the fatality risk of cases to change over the epidemic (#101).

  • A new vignette, time-varying-cfr.Rmd, has been added to the package to describe how to use the time-varying case fatality risk functionality and describe a few different time-varying functions that can be used (#101).

  • A new vignette, wrangling-linelist.Rmd, has been added to go over some of the common post-processing steps that might be required after simulating line list or contact tracing data. This vignette is short and currently only contains a single post-processing example, more examples will be added over time (#104).

  • The README now has a section on related projects to provide an overview of packages that simulate line list data, or are related to simulist. This section contains a disclosure widget containing a feature table providing a high-level description of the features and development status of each related package (#110).

  • A Key features section and Complimentary R packages section has been added to the README (#134).

  • Updated package architecture diagram in the design-principles.Rmd vignette (#113).

Internal

  • The .add_deaths() function has been replaced by the .add_outcome() function which can simulate death and recovery times (#99).

  • .cross_check_sim_input() function has been added to the package to ensure user input is coherent across arguments (#98).

  • .anonymise() function has been added to convert individual’s names into alphanumeric codes to anonymise individuals in line list and contact tracing data (#106).

Breaking changes

  • The simulation functions are now parameterised with an infectious period (infect_period argument) instead of a contact interval (contact_interval argument). This moves away from parameterising the simulation with the time delay between a person becoming infected and having contact with a susceptible individual, and instead uses an infectious period distribution within which contacts are uniformly distributed in time (#96).

  • The simulation functions can now set a maximum as well as a minimum outbreak size. The min_outbreak_size argument in the exported sim_*() functions has been renamed outbreak_size and takes a numeric vector of two elements, the minimum and maximum outbreak size. The maximum outbreak size is a soft limit due to the stochastic nature of the branching process model, so epidemiological data returned can contain more cases and/or contacts that the maximum in outbreak_size but in these case a warning is returned explaining to the user how many cases/contacts are being returned (#93).

  • The add_ct argument in sim_linelist() and sim_outbreak() has been removed. The functionality is now equivalent to add_ct = TRUE in the previous simulist version. The add_ct argument was removed to move the package to always returning <data.frame>s with the same number of columns, for consistency and predictability (#104).

  • The add_names argument in the simulation functions has been renamed to anonymise. The new argument controls whether names are given to each case (anonymise = FALSE, default behaviour) or whether fixed length hexadecimal codes are given to each case (anonymise = TRUE), this ensures the returned <data.frame> has the same number of columns (#106).

Bug fixes

  • .sim_network_bp() now indexes the time vector correctly. Previously a vector indexing bug meant the epidemic would not progress through time (#95).

Deprecated and defunct

  • None

Acknowledgements

Many thanks to the contributors to this release, either from issues, code contributions, reviews or discussions (listed in alphabetical order):

@adamkucharski, @avallecam, @Bisaloo, @CarmenTamayo, @chartgerink, @jamesmbaazam, @ntncmch, @PaulC91, @pratikunterwegs, and @sbfnk.

Reuse

Citation

BibTeX citation:
@online{epiverse-trace_development_team2024,
  author = {Epiverse-TRACE development team, The},
  title = {Simulist V0.3.0},
  date = {2024-06-03},
  url = {https://epiverse-trace.github.io/posts/simulist_v0.3.0},
  langid = {en}
}
For attribution, please cite this work as:
Epiverse-TRACE development team, The. 2024. “Simulist V0.3.0.” June 3, 2024. https://epiverse-trace.github.io/posts/simulist_v0.3.0.