superspreading is an R package that provides a set of functions to estimate and understand individual-level variation the in transmission of infectious diseases from data on secondary cases.

superspreading implements methods outlined in Lloyd-Smith et al. (2005), Adam J. Kucharski et al. (2020), and Kremer et al. (2021), as well as additional functions.

superspreading is developed at the Centre for the Mathematical Modelling of Infectious Diseases at the London School of Hygiene and Tropical Medicine as part of Epiverse-TRACE.

## Installation

The easiest way to install the development version of superspreading from GitHub is to use the pak package:

# check whether {pak} is installed
if(!require("pak")) install.packages("pak")

## Quick start

### Calculate the heterogeneity of transmission

Case study using data from early Ebola outbreak in Guinea in 2014, stratified by index and non-index cases, as in Adam J. Kucharski et al. (2016). Data on transmission from index and secondary cases for Ebola in 2014.

Source: Faye et al. (2015) & Althaus (2015).

{fitdistrplus} is a well-developed and stable R package that provides a variety of methods for fitting distribution models to data (Delignette-Muller and Dutang 2015). Therefore, it is used throughout the documentation of superspreading and is a recommended package for those wanting to fit distribution models, for example those supplied in superspreading (Poisson-lognormal and Poisson-Weibull). We recommend reading the fitdistrplus documentation (specifically ?fitdist) to explore the full range of functionality.

In this example we fit the negative binomial distribution to estimate the reproduction number (R, which is the mean of the distribution) and the dispersion (k, which a measure of the variance of the distribution). The parameters are estimated via maximum likelihood (the default method for fitdist()).

# we use {fitdistrplus} to fit the models

# transmission events from index cases
index_case_transmission <- c(2, 17, 5, 1, 8, 2, 14)

# transmission events from secondary cases
secondary_case_transmission <- c(
1, 2, 1, 4, 4, 1, 3, 3, 1, 1, 4, 9, 9, 1, 2, 1, 1, 1, 4, 3, 3, 4, 2, 5,
1, 2, 2, 1, 9, 1, 3, 1, 2, 1, 1, 2
)

# Format data into index and non-index cases
# total non-index cases
n_non_index <- sum(c(index_case_transmission, secondary_case_transmission))
# transmission from all non-index cases
non_index_cases <- c(
secondary_case_transmission,
rep(0, n_non_index - length(secondary_case_transmission))
)

# Estimate R and k for index and non-index cases
param_index <- fitdist(data = index_case_transmission, distr = "nbinom")
# rename size and mu to k and R
names(param_index$estimate) <- c("k", "R") param_index$estimate
#>        k        R
#> 1.596646 7.000771
param_non_index <- fitdist(data = non_index_cases, distr = "nbinom")
# rename size and mu to k and R
names(param_non_index$estimate) <- c("k", "R") param_non_index$estimate
#>         k         R
#> 0.1937490 0.6619608

The reproduction number (R) is higher for index cases than for non-index cases, but the heterogeneity in transmission is higher for non-index cases (i.e. k is lower).

### Calculate the probability of a large epidemic

Given the reproduction number (R) and the dispersion (k), the probability that a infectious disease will cause an epidemic, in other words the probability it does not go extinct, can be calculated using probability_epidemic(). Here we use probability_epidemic() for the parameters estimated in the above section for Ebola, assuming there are three initial infections seeding the potential outbreak.

# Compare probability of a large outbreak when k varies according to
# index/non-index values, assuming 3 initial spillover infections

initial_infections <- 3

# Probability of an epidemic using k estimated from index cases

R = param_index$estimate[["R"]], k = param_index$estimate[["k"]],
num_init_infect = initial_infections
)
#> [1] 0.9995781

# Probability of an epidemic using k estimated from non-index cases

R = param_non_index$estimate[["R"]], k = param_non_index$estimate[["k"]],
num_init_infect = initial_infections
)
#> [1] 0

The probability of causing a sustained outbreak is high for the index cases, but is zero for non-index cases (i.e. disease transmission will inevitably cease assuming transmission dynamics do not change).

## Package vignettes

More details on how to use superspreading can be found in the online documentation as package vignettes, under “Articles”.

### Visualisation and plotting functionality

superspreading does not provide plotting functions, instead we provide example code chunks in the package’s vignettes that can be used as a templates upon which data visualisations can be modified. We recommend users copy and edit the examples for their own purposes. (This is permitted under the package’s MIT license). By default code chunks for plotting are folded, in order to unfold them and see the code simply click the code button at the top left of the plot.

## Help

To report a bug please open an issue

## Contribute

Contributions to superspreading are welcomed. Please follow the package contributing guide.

## Code of Conduct

Please note that the {superspreading} project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

## Citing this package

#> To cite package 'superspreading' in publications use:
#>
#>   Lambert J, Kucharski A (2024). _superspreading: Estimate
#>   Individual-Level Variation in Transmission_. R package version
#>
#> A BibTeX entry for LaTeX users is
#>
#>   @Manual{,
#>     title = {superspreading: Estimate Individual-Level Variation in Transmission},
#>     author = {Joshua W. Lambert and Adam Kucharski},
#>     year = {2024},
#>     note = {R package version 0.1.0.9000,
#>     url = {https://github.com/epiverse-trace/superspreading},
#>   }

This project has some overlap with other R packages:

• {bpmodels} is another Epiverse-TRACE R package that analyses transmission chain data to infer the transmission process for either the size or length of transmission chains. Two main differences between the packages are: 1) superspreading has more functions to compute metrics that characterise outbreaks and superspreading events (e.g. probability_epidemic() & probability_extinct()); 2) bpmodels can simulate a branching process (chain_sim()) with a specified process (e.g. negative binomial).

## References

Althaus, Christian L. 2015. “Ebola Superspreading.” The Lancet Infectious Diseases 15 (5): 507–8. https://doi.org/10.1016/S1473-3099(15)70135-0.
Delignette-Muller, Marie Laure, and Christophe Dutang. 2015. “Fitdistrplus: An R Package for Fitting Distributions.” Journal of Statistical Software 64 (4). https://doi.org/10.18637/jss.v064.i04.
Faye, Ousmane, Pierre-Yves Boëlle, Emmanuel Heleze, Oumar Faye, Cheikh Loucoubar, N’Faly Magassouba, Barré Soropogui, et al. 2015. “Chains of Transmission and Control of Ebola Virus Disease in Conakry, Guinea, in 2014: An Observational Study.” The Lancet Infectious Diseases 15 (3): 320–26. https://doi.org/10.1016/S1473-3099(14)71075-8.
Kremer, Cécile, Andrea Torneri, Sien Boesmans, Hanne Meuwissen, Selina Verdonschot, Koen Vanden Driessche, Christian L. Althaus, Christel Faes, and Niel Hens. 2021. “Quantifying Superspreading for COVID-19 Using Poisson Mixture Distributions.” Scientific Reports 11 (1): 14107. https://doi.org/10.1038/s41598-021-93578-x.
Kucharski, Adam J., Rosalind M. Eggo, Conall H. Watson, Anton Camacho, Sebastian Funk, and W. John Edmunds. 2016. “Effectiveness of Ring Vaccination as Control Strategy for Ebola Virus Disease.” Emerging Infectious Diseases 22 (1): 105–8. https://doi.org/10.3201/eid2201.151410.
Kucharski, Adam J, Timothy W Russell, Charlie Diamond, Yang Liu, John Edmunds, Sebastian Funk, Rosalind M Eggo, et al. 2020. “Early Dynamics of Transmission and Control of COVID-19: A Mathematical Modelling Study.” The Lancet Infectious Diseases 20 (5): 553–58. https://doi.org/10.1016/S1473-3099(20)30144-4.
Lloyd-Smith, J. O., S. J. Schreiber, P. E. Kopp, and W. M. Getz. 2005. “Superspreading and the Effect of Individual Variation on Disease Emergence.” Nature 438 (7066): 355–59. https://doi.org/10.1038/nature04153.