The R package

The R package in question is {ringbp}. The package has two pieces of functionality: 1) to simulate an infectious disease outbreak using a branching process model with non-pharmaceutical interventions; and 2) to calculate the proportion of simulated outbreaks that are contained (i.e. do not cause a large sustained human-to-human epidemic). The utility of the package’s general model framework has been shown by serving as a template for other epidemiological research such as post-exposure prophylaxis, network effects on control (Firth et al. 2020) and the impact of self-reporting and isolation adherence (Davis et al. 2020).

The problem

It is understandable that because {ringbp} was written in haste to produce insights to inform pandemic response it did not adhere to all software best practices. Usability, documentation, testing, code style and (computational) performance could be improved. Certain aspects of model code, like parameterisations, were hard-coded, not providing users the full flexibility that the model could allow.

Epiverse contribution

In the recent months Epiverse has collaborated with {ringbp} developers Seb Funk (also a member of Epiverse) and Carl Pearson (external collaborator), based at the London School of Hygiene and Tropical Medicine and University of North Carolina, respectively, to try and improve the R package, both internally and from the user-experience. The following sections will give brief summaries of some of the collaborative developments.

scenario_sim(
  n.sim = 5,
  num.initial.cases = 5,
  cap_max_days = 365,
  cap_cases = 2000,
  r0isolated = 0,
  r0community = 2.5,
  disp.iso = 1,
  disp.com = 0.16,
  k = 0.7,
  delay_shape = 2.5,
  delay_scale = 5,
  prop.asym = 0,
  prop.ascertain = 0
)

scenario_sim(
 n = 5,
 initial_cases = 5,
 offspring = offspring_opts(
   community = \(n) rnbinom(n = n, mu = 2.5, size = 0.16),
   isolated = \(n) rnbinom(n = n, mu = 0, size = 1),
   asymptomatic = \(n) rnbinom(n = n, mu = 2.5, size = 0.16)
  ),
 delays = delay_opts(
   incubation_period = \(n) rweibull(n = n, shape = 2.32, scale = 6.49),
   onset_to_isolation = \(n) rweibull(n = n, shape = 2.5, scale = 5)
  ),
 event_probs = event_prob_opts(
   asymptomatic = 0,
   presymptomatic_transmission = 0.3,
   symptomatic_ascertained = 0
  ),
 interventions = intervention_opts(quarantine = TRUE),
 sim = sim_opts(
   cap_max_days = 365,
   cap_cases = 2000
  )
)

The new API gives the user more control over the model’s parameterisation. The incubation period is now specified by the user instead of being set to an estimate for COVID-19. The way offspring and delay distribution functions are specified also means that any distributional or non-parametric form can be supplied, relaxing the assumption that the onset-to-isolation has to be a Weibull distribution.

Users can now specify the proportion of presymptomatic transmission rather than having to understand the skew normal parameterisation used by the simulation model, making it easier to get started with the package for new users.

Lastly on user-facing changes, the naming and style of function arguments has been standardised for consistent use of snakecase style and abbreviations.

@param sim a `list` with class `<ringbp_sim_opts>`: the simulation control
  options for the \pkg{ringbp} model, returned by [sim_opts()]

Conclusion

The {ringbp} R package implements a simple but informative model for infectious disease transmission and interventions. When originally written it included many well-developed aspects, but the time constraints of real-time outbreak response meant several improvements were possible.

Epiverse-TRACE has the opportunity to not only develop new tooling for pandemic preparedness and response, but to contribute to the ecosystem of open-source software in infectious disease epidemiology. We hope that by covering the collaborative developments of {ringbp}, it can illustrate the benefits of bringing software up to date with best practices, and make tools available, accessible and robust when a new epidemic or pandemic occurs, in turn hopefully removing the need for redeveloping similar software in the future.

Enhancing the accessibility of software for users and developers by improving its documentation and user interface will hopefully provide a gateway for more external contributors to engage with the project. In the public health landscape of temporal surges in capacity and priorities, better enabling community contributions to open-source software should aid software sustainability.

All of the changes discussed in this blog post can be found in the {ringbp} news. For details of developments see the pull request history of {ringbp} on GitHub.

Acknowledgements

Thanks to Seb Funk and Carl Pearson for helpful feedback when drafting this post and for their collaboration on the {ringbp} project.