diff --git a/R/offspring_distributions.R b/R/offspring_distributions.R index 91b35fae..0637a896 100644 --- a/R/offspring_distributions.R +++ b/R/offspring_distributions.R @@ -1,4 +1,4 @@ -#' Density of the poisson-lognormal compound distribution +#' Density of the Poisson-lognormal compound distribution #' #' @details #' The function is vectorised so a vector of quantiles can be input and the @@ -9,7 +9,7 @@ #' @param sdlog A `number` for the standard deviation of the distribution on #' the log scale. #' -#' @return A `numeric` vector of the density of the poisson-lognormal +#' @return A `numeric` vector of the density of the Poisson-lognormal #' distribution. #' @export #' @@ -34,7 +34,7 @@ dpoislnorm <- Vectorize(function(x, meanlog, sdlog) { }) -#' Cumulative distribution function of the poisson-lognormal compound +#' Cumulative distribution function of the Poisson-lognormal compound #' distribution #' #' @details @@ -63,7 +63,7 @@ ppoislnorm <- Vectorize(function(q, meanlog, sdlog) { sum(dpoislnorm(x = seq(0, q, by = 1), meanlog = meanlog, sdlog = sdlog)) }) -#' Density of the poisson-Weibull compound distribution +#' Density of the Poisson-Weibull compound distribution #' #' @details #' The function is vectorised so a vector of quantiles can be input and the @@ -73,7 +73,7 @@ ppoislnorm <- Vectorize(function(q, meanlog, sdlog) { #' @param shape A `number` for the shape parameter of the distribution. #' @param scale A `number` for the scale parameter of the distribution. #' -#' @return A `numeric` vector of the density of the poisson-Weibull +#' @return A `numeric` vector of the density of the Poisson-Weibull #' distribution. #' @export #' @@ -100,7 +100,7 @@ dpoisweibull <- Vectorize(function(x, shape, scale) { out }) -#' Cumulative distribution function of the poisson-Weibull compound +#' Cumulative distribution function of the Poisson-Weibull compound #' distribution #' #' @details diff --git a/R/proportion_transmission.R b/R/proportion_transmission.R index 8ea326c9..9233d13e 100644 --- a/R/proportion_transmission.R +++ b/R/proportion_transmission.R @@ -40,7 +40,7 @@ #' parameter \eqn{k}, which encodes all variation in infectious histories of #' individuals, including properties of the host and pathogen and environmental #' circumstances." The value of \eqn{k} corresponds to the shape parameters of -#' the gamma distribution which encodes the variation in the gamma-poisson +#' the gamma distribution which encodes the variation in the gamma-Poisson #' mixture a.k.a. the negative binomial. #' #' For `method = t_20`, we define the upper proportion of infectiousness, diff --git a/README.Rmd b/README.Rmd index 1d8bbc42..8dee6590 100644 --- a/README.Rmd +++ b/README.Rmd @@ -145,11 +145,11 @@ dynamics do not change). ## Package vignettes -More details on how to use `{superspreading}` can be found in the [online documentation as package vignettes](https://epiverse-trace.github.io/superspreading/), under "Articles". +More details on how to use `{superspreading}` can be found in the [online documentation as package vignettes](https://epiverse-trace.github.io/superspreading/), under [Articles](https://epiverse-trace.github.io/superspreading/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. +`{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). ## Help @@ -161,7 +161,7 @@ Contributions to `{superspreading}` are welcomed. Please follow the [package con ## Code of Conduct -Please note that the {superspreading} project is released with a +Please note that the `{superspreading}` project is released with a [Contributor Code of Conduct](https://github.com/epiverse-trace/.github/blob/main/CODE_OF_CONDUCT.md). By contributing to this project, you agree to abide by its terms. diff --git a/README.md b/README.md index 632177e8..51781622 100644 --- a/README.md +++ b/README.md @@ -183,7 +183,7 @@ inevitably cease assuming transmission dynamics do not change). More details on how to use `{superspreading}` can be found in the [online documentation as package vignettes](https://epiverse-trace.github.io/superspreading/), under -“Articles”. +[Articles](https://epiverse-trace.github.io/superspreading/articles/). ### Visualisation and plotting functionality @@ -191,9 +191,7 @@ vignettes](https://epiverse-trace.github.io/superspreading/), under 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. +is permitted under the package’s MIT license). ## Help @@ -208,7 +206,7 @@ guide](https://github.com/epiverse-trace/.github/blob/main/CONTRIBUTING.md). ## Code of Conduct -Please note that the {superspreading} project is released with a +Please note that the `{superspreading}` project is released with a [Contributor Code of Conduct](https://github.com/epiverse-trace/.github/blob/main/CODE_OF_CONDUCT.md). By contributing to this project, you agree to abide by its terms. diff --git a/inst/WORDLIST b/inst/WORDLIST index b987e5aa..b39b6337 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -38,6 +38,7 @@ Fitdistrplus frac Getz ggplot +ggtext Gostic Hanne Heleze @@ -70,6 +71,7 @@ MDN MERS Meuwissen mpox +nCoV N’Faly Natsal neq diff --git a/man/dpoislnorm.Rd b/man/dpoislnorm.Rd index aae7940d..09f0de20 100644 --- a/man/dpoislnorm.Rd +++ b/man/dpoislnorm.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/offspring_distributions.R \name{dpoislnorm} \alias{dpoislnorm} -\title{Density of the poisson-lognormal compound distribution} +\title{Density of the Poisson-lognormal compound distribution} \usage{ dpoislnorm(x, meanlog, sdlog) } @@ -15,11 +15,11 @@ dpoislnorm(x, meanlog, sdlog) the log scale.} } \value{ -A \code{numeric} vector of the density of the poisson-lognormal +A \code{numeric} vector of the density of the Poisson-lognormal distribution. } \description{ -Density of the poisson-lognormal compound distribution +Density of the Poisson-lognormal compound distribution } \details{ The function is vectorised so a vector of quantiles can be input and the diff --git a/man/dpoisweibull.Rd b/man/dpoisweibull.Rd index 80563bf4..38312fdb 100644 --- a/man/dpoisweibull.Rd +++ b/man/dpoisweibull.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/offspring_distributions.R \name{dpoisweibull} \alias{dpoisweibull} -\title{Density of the poisson-Weibull compound distribution} +\title{Density of the Poisson-Weibull compound distribution} \usage{ dpoisweibull(x, shape, scale) } @@ -14,11 +14,11 @@ dpoisweibull(x, shape, scale) \item{scale}{A \code{number} for the scale parameter of the distribution.} } \value{ -A \code{numeric} vector of the density of the poisson-Weibull +A \code{numeric} vector of the density of the Poisson-Weibull distribution. } \description{ -Density of the poisson-Weibull compound distribution +Density of the Poisson-Weibull compound distribution } \details{ The function is vectorised so a vector of quantiles can be input and the diff --git a/man/ppoislnorm.Rd b/man/ppoislnorm.Rd index f3663c4b..7bc5b08b 100644 --- a/man/ppoislnorm.Rd +++ b/man/ppoislnorm.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/offspring_distributions.R \name{ppoislnorm} \alias{ppoislnorm} -\title{Cumulative distribution function of the poisson-lognormal compound +\title{Cumulative distribution function of the Poisson-lognormal compound distribution} \usage{ ppoislnorm(q, meanlog, sdlog) @@ -19,7 +19,7 @@ the log scale.} A \code{numeric} vector of the distribution function. } \description{ -Cumulative distribution function of the poisson-lognormal compound +Cumulative distribution function of the Poisson-lognormal compound distribution } \details{ diff --git a/man/ppoisweibull.Rd b/man/ppoisweibull.Rd index 0b284128..45c5bfe8 100644 --- a/man/ppoisweibull.Rd +++ b/man/ppoisweibull.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/offspring_distributions.R \name{ppoisweibull} \alias{ppoisweibull} -\title{Cumulative distribution function of the poisson-Weibull compound +\title{Cumulative distribution function of the Poisson-Weibull compound distribution} \usage{ ppoisweibull(q, shape, scale) @@ -18,7 +18,7 @@ ppoisweibull(q, shape, scale) A \code{numeric} vector of the distribution function. } \description{ -Cumulative distribution function of the poisson-Weibull compound +Cumulative distribution function of the Poisson-Weibull compound distribution } \details{ diff --git a/man/proportion_transmission.Rd b/man/proportion_transmission.Rd index 2db4c151..c5e817b5 100644 --- a/man/proportion_transmission.Rd +++ b/man/proportion_transmission.Rd @@ -89,7 +89,7 @@ probability distribution with population mean \eqn{R_0} and dispersion parameter \eqn{k}, which encodes all variation in infectious histories of individuals, including properties of the host and pathogen and environmental circumstances." The value of \eqn{k} corresponds to the shape parameters of -the gamma distribution which encodes the variation in the gamma-poisson +the gamma distribution which encodes the variation in the gamma-Poisson mixture a.k.a. the negative binomial. For \code{method = t_20}, we define the upper proportion of infectiousness, diff --git a/vignettes/design-principles.Rmd b/vignettes/design-principles.Rmd index e6473d88..93638a4a 100644 --- a/vignettes/design-principles.Rmd +++ b/vignettes/design-principles.Rmd @@ -20,7 +20,7 @@ This document is primarily intended to be read by those interested in understand ## Scope -The {superspreading} package aims to provide a range of summary metrics to characterise individual-level variation in disease transmission and its impact on the growth or decline of an epidemic. These include calculating the probability an outbreak becomes an epidemic (`probability_epidemic()`), or conversely goes extinct (`probability_extinct()`), the probability an outbreak can be contained (`probability_contain()`), the proportion of cases in cluster of a given size (`proportion_cluster_size()`), and the proportion of cases that cause a proportion of transmission (`proportion_transmission()`). +The {superspreading} package aims to provide a range of summary metrics to characterise individual-level variation in disease transmission and its impact on the growth or decline of an epidemic. These include calculating the probability an outbreak becomes an epidemic (`probability_epidemic()`), or conversely goes extinct (`probability_extinct()`), the probability an outbreak can be contained (`probability_contain()`), the probability of a pathogen evolving and emerging, the proportion of cases in cluster of a given size (`proportion_cluster_size()`), and the proportion of cases that cause a proportion of transmission (`proportion_transmission()`). The other aspect of the package is to provide probability density functions and cumulative distribution functions to compute the likelihood for distribution models to estimate heterogeneity in individual-level disease transmission that are not available in R (i.e. base R). At present we include two models: Poisson-lognormal (`dpoislnorm()` & `ppoislnorm()`) and Poisson-Weibull (`dpoisweibull()` & `ppoisweibull()`) distributions. @@ -38,7 +38,7 @@ The distribution functions return a vector of `numeric`s of equal length to the - The distribution functions are vectorised (i.e. wrapped in `Vectorize()`). This enables them to be used identically to base R distribution functions. -- Native interoperability with `` objects, from the {epiparameter} package is enabled for `probability_*()` and `proportion_*()` via the `offspring_dist` argument. This allows user to pass in a single object and the parameters required by the {superspreading} function will be extracted, if these are not available within the `` object the function returns an informative error. The `offspring_dist` argument is after `...` to ensure users specify the argument in full and not accidentally provide data to this argument. +- Native interoperability with `` objects, from the {epiparameter} package is enabled for `probability_*()` and `proportion_*()` via the `offspring_dist` argument. This allows user to pass in a single object and the parameters required by the {superspreading} function will be extracted, if these are not available within the `` object the function returns an informative error. The `offspring_dist` argument is after `...` to ensure users specify the argument in full and not accidentally provide data to this argument. The exception is `probability_emergence()` which does not have an `offspring_dist` argument and thus no interoperability with {epiparameter} due to the function using two reproduction numbers so handling multiple `` objects was judged to add too much complexity for the benefit. - Internal functions have a dot (`.`) prefix, exported functions do not. @@ -50,10 +50,11 @@ The aim is to restrict the number of dependencies to a minimal required set for * {stats} * [{checkmate}](https://CRAN.R-project.org/package=checkmate) +* [{rlang}](https://CRAN.R-project.org/package=rlang) -{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. +{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. {rlang} is used to accept [dynamic dots](https://rlang.r-lib.org/reference/dyn-dots.html) in various {superspreading} functions. -Suggested dependencies (not including package documentation ({knitr}, {rmarkdown}), testing ({spelling} and {testthat}), and plotting ({ggplot2})) are: [{epiparameter}](https://github.com/epiverse-trace/epiparameter), used to easily access epidemiological parameters from the package's library, and [{fitdistrplus}](https://CRAN.R-project.org/package=fitdistrplus), used for model fitting methods. +Suggested dependencies are used for package documentation, including building vignettes ([{knitr}]( https://CRAN.R-project.org/package=knitr), [{rmarkdown}](https://CRAN.R-project.org/package=rmarkdown)), data wrangling ([{dplyr}](https://CRAN.R-project.org/package=dplyr), [{purrr}](https://CRAN.R-project.org/package=purrr)), plotting ([{ggplot2}](https://CRAN.R-project.org/package=ggplot2), [{scales}](https://CRAN.R-project.org/package=scales), [{ggtext}](https://CRAN.R-project.org/package=ggtext)), loading epidemiological parameters from [{epiparameter}](https://CRAN.R-project.org/package=epiparameter), and model fitting with [{fitdistrplus}](https://CRAN.R-project.org/package=fitdistrplus). There are also suggested dependencies for testing and spell checking ([{testthat}](https://CRAN.R-project.org/package=testthat), [{spelling}](https://CRAN.R-project.org/package=spelling)). ## Contribute diff --git a/vignettes/epidemic_risk.Rmd b/vignettes/epidemic_risk.Rmd index ad1b34f0..cdf0cf9c 100644 --- a/vignettes/epidemic_risk.Rmd +++ b/vignettes/epidemic_risk.Rmd @@ -45,7 +45,7 @@ library(ggtext) ``` Early in the COVID-19 epidemic, a number of studies including @kucharskiEarlyDynamicsTransmission2020 investigated -whether data on SARS-CoV-2 incidence had evidence of superspreading events. These events are often estimated as some measure of overdispersion. This was in light of evidence that other corona virus +whether data on SARS-CoV-2 incidence had evidence of superspreading events. These events are often estimated as some measure of overdispersion. This was in light of evidence that other coronavirus outbreaks (Severe acute respiratory syndrome (SARS) and Middle East respiratory syndrome (MERS)) had superspreading events. The detection of variability in individual-transmission is important in understanding or predicting the likelihood of transmission establishing @@ -53,7 +53,7 @@ when imported into a new location (e.g. country). First we set up the parameters to use for calculating the probability of an epidemic. In this case we are varying the heterogeneity of transmission (`k`) -and number of initial infections (`a`). +and number of initial infections (`num_init_infect`). ```{r, prep-dispersion-plot} epidemic_params <- expand.grid( @@ -92,7 +92,7 @@ epidemic_params <- cbind(epidemic_params, prob_epidemic) ``` To visualise the influence of transmission variation (`k`) we subset the results -to only include those with a single initial infection seeding transmission (`a = 1`). +to only include those with a single initial infection seeding transmission (`num_init_infect = 1`). ```{r, subset-prob-epidemic} # subset data for a single initial infection @@ -143,7 +143,7 @@ ggplot(data = homogeneity) + ``` The degree of variability in transmission increases as $k$ decreases [@lloyd-smithSuperspreadingEffectIndividual2005]. -So the probability of a large outbreak is smaller for smaller values of $k$, meaning that if COVID-19 +So the probability of a large outbreak is smaller for smaller values of $k$, for a given value of $R$, meaning that if COVID-19 is more similar to SARS than MERS it will be less likely to establish and cause an outbreak if introduced into a newly susceptible population. @@ -155,7 +155,7 @@ introductions, the higher the chance one will lead to an epidemic. introductions <- subset(epidemic_params, k == 0.5) ``` -```{r, plot-introductions, fig.cap="The probability that an a number of introduction events will cause a sustained outbreak (transmission chain). The number of disease introductions is plotted on the x-axis and probability of outbreak -- calculated using `probability_epidemic()` -- is on the y-axis. This plot is reproduced from Kucharski et al. (2020) figure 3B."} +```{r, plot-introductions, fig.cap="The probability that a number of introduction events will cause a sustained outbreak (transmission chain). The number of disease introductions is plotted on the x-axis and probability of outbreak -- calculated using `probability_epidemic()` -- is on the y-axis. This plot is reproduced from Kucharski et al. (2020) figure 3B."} #| fig.alt: > #| A scatter plot showing the relationship between the number of #| introductions of an infectious disease (x-axis, ranging from 0 to 10) and @@ -227,13 +227,9 @@ ggplot(data = epidemic_params) + In the above plot we drop the uncertainty around each point and assume a known value of $R$ in order to more clearly show the pattern. -Applications that make it easy to explore this functionality and compare between existing -parameter estimates of offspring distributions are also useful. An example of this is the -[Shiny app developed by the Centre for Mathematical Modelling of Infectious diseases](https://cmmid.github.io/visualisations/new-outbreak-probability) at the London -School of Hygiene and Tropical Medicine, for comparing SARS-like and MERS-like scenarios, -as well as random mixing. +These calculations enable us to understand epidemics and applications, such as Shiny apps, to explore this functionality and compare between existing parameter estimates of offspring distributions are also useful. An example application called [Probability of a large 2019-nCoV outbreak following introduction of cases](https://cmmid.github.io/visualisations/), that is no longer maintained, was developed by the Centre for Mathematical Modelling of Infectious diseases at the London School of Hygiene and Tropical Medicine, for comparing SARS-like and MERS-like scenarios, as well as random mixing during the COVID-19 pandemic. -Conversely to the probability of an epidemics, the probability that an outbreak will +Conversely to the probability of an epidemic, the probability that an outbreak will go extinct (i.e. transmission will subside), can also be plotted for different values of $R$. @@ -308,12 +304,12 @@ contains a library of epidemiological parameters included offspring distribution Equipped with these parameter estimates, metrics that provide an intuitive understanding of transmission patterns can be tabulated. For example the proportion of transmission events in a given cluster size can be calculated using the {superspreading} function `proportion_cluster_size()`. -This calculates the proportion of new cases that originated within a transmission event of a +This calculates the proportion of new cases that originate within a transmission cluster of a given size. In other words, what proportion of all transmission events were part of secondary case clusters (i.e. from the same primary case) of at least, for example, five cases. This calculation is useful to inform backwards contact tracing efforts. -In this example we look at clusters of at least five, ten and twenty-five secondary cases, at +In this example we look at clusters of at least 5, 10 and 25 secondary cases, at different numbers of initial infections and for two reproduction numbers to see how this affects cluster sizes. diff --git a/vignettes/estimate_individual_level_transmission.Rmd b/vignettes/estimate_individual_level_transmission.Rmd index ac70ef1b..aa4b2be3 100644 --- a/vignettes/estimate_individual_level_transmission.Rmd +++ b/vignettes/estimate_individual_level_transmission.Rmd @@ -43,7 +43,7 @@ library(ggplot2) ## Transmission data -For this example we use transmission chain data from @fayeChainsTransmissionControl2015 from the Ebola virus disease outbreak in West Africa, between the period from February to August 2014. Specifically, this data reconstructs the pathway of Ebola transmission in Conakry, Guinea. +For this example we use transmission chain data from @fayeChainsTransmissionControl2015 from the Ebola virus disease (EVD) outbreak in West Africa, between the period from February to August 2014. Specifically, this data reconstructs the pathway of Ebola transmission in Conakry, Guinea. This data has been used by @althausEbolaSuperspreading2015 to show that the Ebola outbreak in Conakry displayed signatures of overdispersion (i.e. superspreading events), and by @kucharskiEffectivenessRingVaccination2016 to determine the effectiveness of ring- and mass-vaccination campaigns for ongoing Ebola outbreaks. @@ -90,7 +90,7 @@ The best performing model, for both AIC and BIC comparison, is the negative bino AIC and BIC are model fitting metrics (information criterion) to determine the model that best fits the data while penalising model complexity to prevent overfitting and allows comparison of models with a different number of parameters. In this case the Poisson -and Geometric models have a single parameter, whereas the Negative binomial has two +and geometric models have a single parameter, whereas the negative binomial has two parameters. ```{r, nbinom-estim} @@ -230,7 +230,7 @@ The Poisson-Gamma distribution is the same as the negative binomial distribution Hereafter we refer to it is the negative binomial. ::: -R has the density functions and cumulative distribution functions for the poisson +R has the density functions and cumulative distribution functions for the Poisson (`dpois()` and `ppois()`), geometric (`dgeom()` and `pgeom()`) and negative binomial (`dnbinom()` and `pnbinom()`) distributions, but does not supply Poisson compound distributions. @@ -304,7 +304,7 @@ dist_compare_data <- data.frame( ) ``` -```{r, plot-dists, fig.cap="Number of secondary cases from the empirical data (bar plot) and the density of the negative binomial (orange) and poisson-Weibull (pink) with the maximum likelihood estimates when fit to the empirical data (points and line)."} +```{r, plot-dists, fig.cap="Number of secondary cases from the empirical data (bar plot) and the density of the negative binomial (orange) and poisson-Weibull (yellow) with the maximum likelihood estimates when fit to the empirical data (points and line)."} #| fig.alt: > #| A histogram showing the frequency distribution of the number of secondary #| cases (x-axis, ranging from 0 to 20) versus frequency (y-axis, ranging diff --git a/vignettes/heterogeneous_network_outbreaks.Rmd b/vignettes/heterogeneous_network_outbreaks.Rmd index 03b45aa4..e2fe0445 100644 --- a/vignettes/heterogeneous_network_outbreaks.Rmd +++ b/vignettes/heterogeneous_network_outbreaks.Rmd @@ -131,7 +131,7 @@ ggplot(data = res) + Another study that showed the network effects on transmission of an STI was @endoHeavytailedSexualContact2022, who estimated that Mpox (or monkeypox) could spread throughout a network on men who have sex with men (MSM), but would have lower transmissibility in the wider population. Using the Natsal UK data [@mercerChangesSexualAttitudes2013] on same- and opposite-sex sexual partnerships for the age range of 18 to 44, they show that the disease transmission for MSM is greater than for a non-MSM transmission network. Because Mpox has a relatively short infectious period, this study assumed that contacts remained fixed during the period of infection, and hence used a next generation matrix approach more akin to the group-specific transmission defined in the [finalsize package](https://epiverse-trace.github.io/finalsize/). -For comparison, we produce a figure similar to @endoHeavytailedSexualContact2022, using `calc_network_R()` instead to show how highly connected individuals -- who are more likely to acquire and pass on infection -- alter the estimated $R_0$ compared to the simpler assumption of $R_0 = SAR \times contacts$, under the assumptions described above. +For comparison, we produce a figure similar to @endoHeavytailedSexualContact2022, using `calc_network_R()` instead to show how highly connected individuals -- who are more likely to acquire and pass on infection -- alter the estimated $R_0$ compared to the simpler assumption of $R_0 = SAR \times contacts$, under the assumptions described above, where $SAR$ is the secondary attack rate. ```{r, calc-r-mpox} beta <- seq(0.001, 1, length.out = 1000) diff --git a/vignettes/superspreading.Rmd b/vignettes/superspreading.Rmd index c1c28369..938bbcf6 100644 --- a/vignettes/superspreading.Rmd +++ b/vignettes/superspreading.Rmd @@ -63,11 +63,11 @@ Here we use $R$ to represent the reproduction number (number of secondary cases typical case). Depending on the situation, this may be equivalent to the basic reproduction number ($R_0$, representing transmission in a fully susceptible population) or the effective reproduction number at a given point in time ($R_t$, representing the extent of transmission -at time $t$). Either can be input into the functions provided by {superspreading} +at time $t$). Either can be input into the functions provided by {superspreading}. ::: The `probability_epidemic()` function in {superspreading} can calculate -this probability. $k$ is the dispersion parameter of a negative binomial distribution +the probability of sustained transmission. $k$ is the dispersion parameter of a negative binomial distribution and controls the variability of individual-level transmission. ```{r, prob-epidemic-k} @@ -77,7 +77,7 @@ probability_epidemic(R = 1.5, k = 0.1, num_init_infect = 1) ``` In the above code, $k$ values above one represent low heterogeneity (in the case -$k \rightarrow \infty$ it is a poisson distribution), and as $k$ decreases, +$k \rightarrow \infty$ it is a Poisson distribution), and as $k$ decreases, heterogeneity increases. When $k$ equals 1, the distribution is geometric. Values of $k$ less than one indicate overdispersion of disease transmission, a signature of superspreading. @@ -96,8 +96,7 @@ Any value of $R$ less than or equal to one will have zero probability of causing a sustained epidemic. Finally, the probability that a new infection will cause a large epidemic is influenced by the -number of initial infections seeding the outbreak. We define -`a` to be this number of initial infections. +number of initial infections (`num_init_infect`) seeding the outbreak. ```{r, prob-epidemic-a} probability_epidemic(R = 1.5, k = 1, num_init_infect = 1) @@ -107,7 +106,7 @@ probability_epidemic(R = 1.5, k = 1, num_init_infect = 100) ## Empirical superspreading -Given `probability_epidemic()` it is possible to determine the probability of +Using `probability_epidemic()` it is possible to determine the probability of an epidemic for diseases for which parameters of an offspring distribution have been estimated. An offspring distribution is simply the distribution of the number of secondary infections caused by a primary infection. It is the distribution @@ -161,6 +160,6 @@ We can see that the probability of an epidemic given the estimates of @lloyd-smithSuperspreadingEffectIndividual2005 is greater for Ebola than SARS. This is due to the offspring distribution of Ebola having a larger dispersion (dispersion $k$ = `r evd_params[["dispersion"]]`), compared to SARS, which has a relatively -small dispersion ($k$ = `r sars_params[["dispersion"]]`). +small dispersion ($k$ = `r sars_params[["dispersion"]]`), with relatively similar values of $R$ (Ebola $R =$ `r evd_params[["mean"]]`, SARS $R =$ `r sars_params[["mean"]]`). ## References