diff --git a/pkgdown.yml b/pkgdown.yml
index b9f8225..6e97f0b 100644
--- a/pkgdown.yml
+++ b/pkgdown.yml
@@ -8,7 +8,7 @@ articles:
heterogeneous_network_outbreaks: heterogeneous_network_outbreaks.html
proportion_transmission: proportion_transmission.html
superspreading: superspreading.html
-last_built: 2024-10-10T15:30Z
+last_built: 2024-10-10T16:53Z
urls:
reference: https://epiverse-trace.github.io/superspreading/reference
article: https://epiverse-trace.github.io/superspreading/articles
diff --git a/reference/probability_contain.html b/reference/probability_contain.html
index fe6bbdd..24db0f9 100644
--- a/reference/probability_contain.html
+++ b/reference/probability_contain.html
@@ -162,7 +162,7 @@
Arguments...
<dynamic-dots> Named elements to replace
-default arguments in chain_sim(). See details.
+default arguments in .chain_sim(). See details.
case_threshold
@@ -197,7 +197,7 @@ Value
Details
When using simulate = TRUE, the default arguments to simulate the
-transmission chains with chain_sim() are 1e5 replicates,
+transmission chains with .chain_sim() are 1e5 replicates,
a negative binomial (nbinom) offspring distribution, parameterised with
R (and pop_control if > 0) and k.
When setting the outbreak_time argument, the generation_time argument is
diff --git a/search.json b/search.json
index 08e6f35..f45ae47 100644
--- a/search.json
+++ b/search.json
@@ -1 +1 @@
-[{"path":"https://epiverse-trace.github.io/superspreading/LICENSE.html","id":null,"dir":"","previous_headings":"","what":"MIT License","title":"MIT License","text":"Copyright (c) 2022 superspreading authors Permission hereby granted, free charge, person obtaining copy software associated documentation files (“Software”), deal Software without restriction, including without limitation rights use, copy, modify, merge, publish, distribute, sublicense, /sell copies Software, permit persons Software furnished , subject following conditions: copyright notice permission notice shall included copies substantial portions Software. SOFTWARE PROVIDED “”, WITHOUT WARRANTY KIND, EXPRESS IMPLIED, INCLUDING LIMITED WARRANTIES MERCHANTABILITY, FITNESS PARTICULAR PURPOSE NONINFRINGEMENT. EVENT SHALL AUTHORS COPYRIGHT HOLDERS LIABLE CLAIM, DAMAGES LIABILITY, WHETHER ACTION CONTRACT, TORT OTHERWISE, ARISING , CONNECTION SOFTWARE USE DEALINGS SOFTWARE.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/articles/design-principles.html","id":"scope","dir":"Articles","previous_headings":"","what":"Scope","title":"Design Principles for {superspreading}","text":"{superspreading} package aims provide range summary metrics characterise individual-level variation disease transmission impact growth decline epidemic. include calculating probability outbreak becomes epidemic (probability_epidemic()), conversely goes extinct (probability_extinct()), probability outbreak can contained (probability_contain()), proportion cases cluster given size (proportion_cluster_size()), proportion cases cause proportion transmission (proportion_transmission()). aspect package provide probability density functions cumulative distribution functions compute likelihood distribution models estimate heterogeneity individual-level disease transmission available R (.e. base R). present include two models: Poisson-lognormal (dpoislnorm() & ppoislnorm()) Poisson-Weibull (dpoisweibull() & ppoisweibull()) distributions. package implements branching process simulation based bpmodels::chain_sim() enable numerical calculation probability containment within outbreak time outbreak duration threshold. future function removed favour using package implementing branching process models dependency. package mostly focused analytical functions derived branching process models. package provides functions calculate variation individual-level transmission provide functions inference, currently relies {fitdistrplus} fitting models.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/articles/design-principles.html","id":"output","dir":"Articles","previous_headings":"","what":"Output","title":"Design Principles for {superspreading}","text":"Functions name probability_*() return single numeric. Functions name proportion_*() return many rows combinations input values (see expand.grid()). consistency simple well-known data structure makes easy users apply functions different scenarios. distribution functions return vector numerics equal length input vector. behaviour base R distribution functions.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/articles/design-principles.html","id":"design-decisions","dir":"Articles","previous_headings":"","what":"Design decisions","title":"Design Principles for {superspreading}","text":"proportion_*() functions return proportion column(s) containing character strings, formatted percentage sign (%) default. reasoned {superspreading} likely used either stand-alone package, terminus epidemiological analysis pipeline, thus outputs {superspreading} functions passed functions. instances proportions need passed another calculation plotting purposes format_prop argument can switched FALSE numeric column proportions returned. distribution functions vectorised (.e. wrapped Vectorize()). enables used identically base R distribution functions. Native interoperability objects, {epiparameter} package enabled probability_*() proportion_*() via offspring_dist argument. allows user pass single object parameters required {superspreading} function extracted, available within object function returns informative error. offspring_dist argument ... ensure users specify argument full accidentally provide data argument. Internal functions dot (.) prefix, exported functions .","code":""},{"path":"https://epiverse-trace.github.io/superspreading/articles/design-principles.html","id":"dependencies","dir":"Articles","previous_headings":"","what":"Dependencies","title":"Design Principles for {superspreading}","text":"aim restrict number dependencies minimal required set ease maintenance. current hard dependencies : {stats} {checkmate} {stats} distributed R language viewed lightweight dependency, already installed user’s machine R. {checkmate} input checking package widely used across Epiverse-TRACE packages. Suggested dependencies (including package documentation ({knitr}, {rmarkdown}), testing ({spelling} {testthat}), plotting ({ggplot2})) : {epiparameter}, used easily access epidemiological parameters package’s library, {fitdistrplus}, used model fitting methods.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/articles/design-principles.html","id":"contribute","dir":"Articles","previous_headings":"","what":"Contribute","title":"Design Principles for {superspreading}","text":"special requirements contributing {superspreading}, please follow package contributing guide.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/articles/epidemic_risk.html","id":"superspreading-in-decision-making","dir":"Articles","previous_headings":"","what":"Superspreading in decision making","title":"Epidemic Risk","text":"One first tasks outbreak establish whether estimates individual-level transmission variability reported, either outbreak previous outbreak pathogen. Alternatively, outbreak novel pathogen, parameters similar pathogens can searched . accomplished another Epiverse-TRACE R package: {epiparameter}. package contains library epidemiological parameters included offspring distribution parameter estimates uncertainty obtained published literature. aids collation establishes baseline understanding transmission. Similar collation transmission clusters COVID-19. Equipped parameter estimates, metrics provide intuitive understanding transmission patterns can tabulated. example proportion transmission events given cluster size can calculated using {superspreading} function proportion_cluster_size(). calculates proportion new cases originated within transmission event given size. words, proportion transmission events part secondary case clusters (.e. primary case) least, example, five cases. calculation useful inform backwards contact tracing efforts. example look clusters least five, ten twenty-five secondary cases, different numbers initial infections two reproduction numbers see affects cluster sizes. results show level heterogeneity individual-level transmission increases, larger percentage cases come larger cluster sizes, large clusters can produced RR higher even low levels transmission variation. indicates whether preventing gatherings certain size can reduce epidemic preventing potential superspreading events. data settings transmission known, priority can given restricting particular types gatherings effectively bring reproduction number.","code":"# For R = 0.8 proportion_cluster_size( R = 0.8, k = seq(0.1, 1, 0.1), cluster_size = c(5, 10, 25) ) #> R k prop_5 prop_10 prop_25 #> 1 0.8 0.1 66.8% 38.7% 7.36% #> 2 0.8 0.2 48.6% 18% 0.786% #> 3 0.8 0.3 37.7% 9.37% 0.197% #> 4 0.8 0.4 30.3% 5.24% 0.0325% #> 5 0.8 0.5 24.5% 3.07% 0% #> 6 0.8 0.6 21.2% 1.68% 0% #> 7 0.8 0.7 18.2% 1.11% 0% #> 8 0.8 0.8 16% 0.925% 0% #> 9 0.8 0.9 14.5% 0.6% 0% #> 10 0.8 1.0 12.7% 0.445% 0% # For R = 3 proportion_cluster_size( R = 3, k = seq(0.1, 1, 0.1), cluster_size = c(5, 10, 25) ) #> R k prop_5 prop_10 prop_25 #> 1 3 0.1 90.3% 78.4% 50.5% #> 2 3 0.2 84.1% 64.8% 27.1% #> 3 3 0.3 79.5% 55.2% 15.8% #> 4 3 0.4 75.9% 47.6% 9.35% #> 5 3 0.5 73.1% 42.1% 6.09% #> 6 3 0.6 70.5% 36.8% 3.57% #> 7 3 0.7 68.2% 32.7% 2.04% #> 8 3 0.8 66.3% 29.6% 1.63% #> 9 3 0.9 64.7% 26.7% 0.95% #> 10 3 1.0 63.1% 23.9% 0.695%"},{"path":"https://epiverse-trace.github.io/superspreading/articles/epidemic_risk.html","id":"controls-on-transmission","dir":"Articles","previous_headings":"","what":"Controls on transmission","title":"Epidemic Risk","text":"work identifying prevalence overdispersion individual-level transmission, Lloyd-Smith et al. (2005) also showed effect control measures probability containment. defined containment size transmission chain reaching 100 cases. assumed implementation control measures individual population level. {superspreading} provides probability_contain() calculate probability outbreak go extinct reaching threshold size. probability outbreak contained (.e. exceed 100 cases) variety population-level control measures. probability containment calculated using probability_contain(). plot reproduced Lloyd-Smith et al. (2005) figure 3C.","code":"contain_params <- expand.grid( R = 3, k = c(0.1, 0.5, 1, Inf), num_init_infect = 1, control = seq(0, 1, 0.05) ) prob_contain <- apply(contain_params, 1, function(x) { probability_contain( R = x[[\"R\"]], k = x[[\"k\"]], num_init_infect = x[[\"num_init_infect\"]], pop_control = x[[\"control\"]] ) }) contain_params <- cbind(contain_params, prob_contain) # plot probability of epidemic across introductions for multiple k ggplot(data = contain_params) + geom_point( mapping = aes( x = control, y = prob_contain, colour = factor(k) ) ) + scale_y_continuous( name = \"Probability of containment\", limits = c(0, 1) ) + scale_x_continuous(name = \"Control measures (*c*)\", n.breaks = 6) + labs(colour = \"Dispersion (*k*)\") + scale_colour_viridis_d() + theme_bw() + theme( axis.title.x = element_markdown(), legend.title = element_markdown() )"},{"path":[]},{"path":"https://epiverse-trace.github.io/superspreading/articles/estimate_individual_level_transmission.html","id":"transmission-data","dir":"Articles","previous_headings":"","what":"Transmission data","title":"Estimate individual-level transmission","text":"example use transmission chain data Faye et al. (2015) Ebola virus disease outbreak West Africa, period February August 2014. Specifically, data reconstructs pathway Ebola transmission Conakry, Guinea. data used Althaus (2015) show Ebola outbreak Conakry displayed signatures overdispersion (.e. superspreading events), Kucharski et al. (2016) determine effectiveness ring- mass-vaccination campaigns ongoing Ebola outbreaks. best performing model, AIC BIC comparison, negative binomial. AIC BIC model fitting metrics (information criterion) determine model best fits data penalising model complexity prevent overfitting allows comparison models different number parameters. case Poisson Geometric models single parameter, whereas Negative binomial two parameters. parameter negative binomial show overdispersion (size dispersion parameter kk, mu mean, RR) transmission thus EVD transmission chain data shows superspreading events possible realisation EVD transmission dynamics. values match reported Althaus (2015) reproduce figure 1 paper display tail distribution superspreading events can possible. Number secondary cases empirical data (bar plot) density negative binomial maximum likelihood estimates fit empirical data (points line). plot reproduced Althaus (2015) figure 1. Next partitioned data index cases secondary cases following Kucharski et al. (2016). fit negative binomial model index non-index case transmission events.","code":"# total number of cases (i.e. individuals in transmission chain) n <- 152 # number of secondary cases for all cases all_cases_transmission <- c( 1, 2, 2, 5, 14, 1, 4, 4, 1, 3, 3, 8, 2, 1, 1, 4, 9, 9, 1, 1, 17, 2, 1, 1, 1, 4, 3, 3, 4, 2, 5, 1, 2, 2, 1, 9, 1, 3, 1, 2, 1, 1, 2 ) # add zeros for each cases that did not cause a secondary case # (i.e. cases that did not transmit) all_cases <- c( all_cases_transmission, rep(0, n - length(all_cases_transmission)) ) # fit a standard set of offspring distribution models: # - Poisson # - Geometric # - Negative Binomial pois_fit <- fitdist(data = all_cases, distr = \"pois\") geom_fit <- fitdist(data = all_cases, distr = \"geom\") nbinom_fit <- fitdist(data = all_cases, distr = \"nbinom\") model_tbl <- ic_tbl(pois_fit, geom_fit, nbinom_fit) col.names <- gsub( pattern = \"^Delta\", replacement = \"$\\\\\\\\Delta$\", x = colnames(model_tbl) ) col.names <- gsub(pattern = \"^w\", replacement = \"$w$\", x = col.names) knitr::kable(model_tbl, col.names = col.names, row.names = FALSE, digits = 1) nbinom_fit$estimate #> size mu #> 0.1814260 0.9537995 # tally cases tally <- table(all_cases) # pad with zeros when number of cases not in tally num_cases <- rep(0, 21) names(num_cases) <- as.character(seq(0, 20, 1)) num_cases[names(tally)] <- tally # convert cases to proportional of total cases to plot on the same scale as # the density prop_num_cases <- num_cases / sum(num_cases) # create data frame with proportion of cases, density and number of secondary # cases nbinom_data <- data.frame( x = seq(0, 20, 1), prop_num_cases = prop_num_cases, density = dnbinom( x = seq(0, 20, 1), size = nbinom_fit$estimate[[\"size\"]], mu = nbinom_fit$estimate[[\"mu\"]] ) ) # make plot ggplot(data = nbinom_data) + geom_col( mapping = aes(x = x, y = prop_num_cases), fill = \"cyan3\", colour = \"black\" ) + geom_point( mapping = aes(x = x, y = density), colour = \"#f58231\", size = 2 ) + geom_line( mapping = aes(x = x, y = density), colour = \"#f58231\" ) + scale_x_continuous(name = \"Number of secondary cases\") + scale_y_continuous(name = \"Frequency\") + theme_bw() index_case_transmission <- c(2, 17, 5, 1, 8, 2, 14) 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\" ) param_index #> Fitting of the distribution ' nbinom ' by maximum likelihood #> Parameters: #> estimate Std. Error #> size 1.596646 1.025029 #> mu 7.000771 2.320850 param_non_index <- fitdist( data = non_index_cases, distr = \"nbinom\" ) param_non_index #> Fitting of the distribution ' nbinom ' by maximum likelihood #> Parameters: #> estimate Std. Error #> size 0.1937490 0.05005421 #> mu 0.6619608 0.14197451"},{"path":"https://epiverse-trace.github.io/superspreading/articles/estimate_individual_level_transmission.html","id":"superspreading-using-alternative-distributions","dir":"Articles","previous_headings":"","what":"Superspreading using alternative distributions","title":"Estimate individual-level transmission","text":"Advanced options section vignette discusses alternative transmission models quantify overdispersion may considered advanced comparison example. Research subsequent Lloyd-Smith et al. (2005) shown contact data infectious disease outbreaks often shows signatures overdispersion can therefore cause superspreading events. However, overdispersion can modelled distributions negative binomial. Kremer et al. (2021) showed SARS-CoV-2 superspreading may better modelled Poisson mixture distribution (Poisson compound distribution). Four Poisson mixture distribution applied: Poisson-Gamma, Poisson-Lognormal, Poisson-Weibull, Poisson-Generalised-Gamma; finding Poisson-lognormal Poisson-Weibull fit best three data sets. Poisson-Gamma distribution negative binomial distribution. Hereafter refer negative binomial. R density functions cumulative distribution functions poisson (dpois() ppois()), geometric (dgeom() pgeom()) negative binomial (dnbinom() pnbinom()) distributions, supply Poisson compound distributions. {superspreading} R package supply density cumulative distribution functions Poisson-lognormal (dpoislnorm() ppoislnorm()) Poisson-Weibull (dpoisweibull() ppoisweibull()). functions can used {fitdistrplus}, shown distributions . negative binomial still best performing fitting model, even addition Poisson-lognormal Poisson-Weibull models. Although second best model, Poisson-Weibull, performs similarly well negative binomial (Δ\\DeltaAIC < 2 & Δ\\DeltaBIC < 2). plot density distribution given maximum likelihood estimates inspect differences two distributions. Number secondary cases empirical data (bar plot) density negative binomial (orange) poisson-Weibull (pink) maximum likelihood estimates fit empirical data (points line). fit model similar, expected close AIC BIC (models numbers free parameters). Poisson-Weibull compound distribution can adequately capture overdispersion EVD transmission data. noticeable difference models fitting number cases caused single secondary cases. negative binomial matches empirical data, whereas Poisson-Weibull slightly overestimates number. Overall, {superspreading} {fitdistrplus} (another fitting package choice) can used estimate understand individual-level transmission dynamics transmission chain data available.","code":"# fit an expanded set of offspring distribution models: # - Poisson # - Geometric # - Negative Binomial # - Poisson-lognormal compound # - Poisson-Weibull compound pois_fit <- fitdist(data = all_cases, distr = \"pois\") geom_fit <- fitdist(data = all_cases, distr = \"geom\") nbinom_fit <- fitdist(data = all_cases, distr = \"nbinom\") poislnorm_fit <- fitdist( data = all_cases, distr = \"poislnorm\", start = list(meanlog = 1, sdlog = 1) ) poisweibull_fit <- fitdist( data = all_cases, distr = \"poisweibull\", start = list(shape = 1, scale = 1) ) model_tbl <- ic_tbl( pois_fit, geom_fit, nbinom_fit, poislnorm_fit, poisweibull_fit ) col.names <- gsub( pattern = \"^Delta\", replacement = \"$\\\\\\\\Delta$\", x = colnames(model_tbl) ) col.names <- gsub(pattern = \"^w\", replacement = \"$w$\", x = col.names) knitr::kable(model_tbl, col.names = col.names, row.names = FALSE, digits = 1) # create data frame with proportion of cases, density of each distribution dist_compare_data <- data.frame( x = seq(0, 20, 1), prop_num_cases = c(prop_num_cases, rep(0, 21)), dens = c( dnbinom( x = seq(0, 20, 1), size = nbinom_fit$estimate[[\"size\"]], mu = nbinom_fit$estimate[[\"mu\"]] ), poisweibull_density = dpoisweibull( x = seq(0, 20, 1), shape = poisweibull_fit$estimate[[\"shape\"]], scale = poisweibull_fit$estimate[[\"scale\"]] ) ), dist = c(rep(\"Negative Binomial\", 21), rep(\"Poisson-Weibull\", 21)) ) # make plot ggplot(data = dist_compare_data) + geom_col( mapping = aes(x = x, y = prop_num_cases), fill = \"cyan3\", colour = \"black\" ) + geom_point( mapping = aes( x = x, y = dens, colour = dist ), size = 2 ) + geom_line(mapping = aes(x = x, y = dens, colour = dist)) + scale_x_continuous(name = \"Number of secondary cases\") + scale_y_continuous(name = \"Frequency\") + scale_colour_manual( name = \"Distribution\", values = c(\"#f58231\", \"#ffe119\") ) + theme_bw() + theme(legend.position = \"top\")"},{"path":[]},{"path":[]},{"path":"https://epiverse-trace.github.io/superspreading/articles/proportion_transmission.html","id":"definitions","dir":"Articles","previous_headings":"","what":"Definitions","title":"Methods for calculating the proportion of transmission","text":"formula p80p_{80} method stated Endo et al. (2020) : 1−p80=∫0XNB(⌊x⌋;k,(k(R0)+k)dx 1 - p_{80} = \\int^{X}_{0} \\text{NB} ( \\lfloor x \\rfloor; k, \\left( \\frac{k}{(R_0) + k} \\right) dx XX satisfies 1−0.8=1R0∫0X⌊x⌋NB(⌊x⌋;k,kR0+k)dx 1 - 0.8 = \\frac{1}{R_0} \\int^{X}_{0} \\lfloor x \\rfloor \\text{NB} \\left( \\lfloor x \\rfloor; k, \\frac{k}{R_0 + k} \\right) dx Additionally, Endo et al. (2020) showed : 1R0∫0X⌊x⌋NB(⌊x⌋;k,kR0+k)dx=∫0X−1NB(⌊x⌋;k+1,kR0+k) \\frac{1}{R_0} \\int^{X}_{0} \\lfloor x \\rfloor \\text{NB} \\left( \\lfloor x \\rfloor; k, \\frac{k}{R_0 + k} \\right) dx = \\int^{X-1}_{0} \\text{NB} \\left( \\lfloor x \\rfloor; k + 1, \\frac{k}{R_0 + k} \\right) t20t_{20} method calculates, stated Lloyd-Smith et al. (2005): “expected proportion transmission due infectious 20% cases, t20t_{20}”, given t20=1−Ftrans(x20)t_{20} = 1 - F_{trans}(x_{20}), FtransF_{trans} defined : Ftrans(x)=1R0∫0xufv(u)du F_{trans}(x) = \\frac{1}{R_0} \\int^{x}_{0} u f_v (u) du fν(x)f_\\nu(x) probability density function (pdf) gamma distribution individual reproduction number ν\\nu. methods proportion transmission can modified using percent_transmission argument proportion_transmission() fixed 80 20, respectively, p80p_{80} t20t_{20}. two methods calculating p80p_{80} method, analytically given Endo et al. (2020), numerically sampling negative binomial distribution (proportion_transmission(..., simulate = TRUE). purpose vignette compare methods term analytical calculation p80p_{80}, numerical calculation p80simp_{80}^{sim}. Now p80p_{80} t20t_{20} methods defined ’ll explore functionality , characteristics compare , making note unexpected behaviour watch . First load {superspreading}, {ggplot2}, {purrr} {dplyr} R packages.","code":"library(superspreading) library(ggplot2) library(purrr) library(dplyr) #> #> Attaching package: 'dplyr' #> The following objects are masked from 'package:stats': #> #> filter, lag #> The following objects are masked from 'package:base': #> #> intersect, setdiff, setequal, union"},{"path":"https://epiverse-trace.github.io/superspreading/articles/proportion_transmission.html","id":"exploring-each-method","dir":"Articles","previous_headings":"","what":"Exploring each method","title":"Methods for calculating the proportion of transmission","text":"show proportion transmission using methods can load estimates RR kk estimated Lloyd-Smith et al. (2005), stored library epidemiological parameters {epiparameter} R package, interoperability {epiparameter} {superspreading} directly supply parameters offspring distributions ( objects) offspring_dist argument proportion_transmission(). create table estimates mean (RR) dispersion (kk) disease Lloyd-Smith et al. (2005). Using parameter estimates negative binomial offspring distribution disease can append calculated proportion transmission caused infectious 20% cases, using t20t_{20} method, calculated proportion transmission causing 80% onward transmission, using p80p_{80} method. can seen table offspring distribution smaller dispersion (kk) parameter proportion cases produced infectious 20% cases high, proportion cases produce 80% transmission low. estimates SARS demonstrate point. metrics lead conclusion disease transmission dynamics 2003 SARS outbreak Singapore heterogeneous superspreading important aspect outbreak. variability individual-level transmission comes modelling individual reproduction number, ν\\nu gamma distribution, instead assuming individual-level reproduction number equal individuals, result Poisson offspring distribution (see Lloyd-Smith et al. (2005) Supplementary Material information). visualise inherent variability resulting gamma-distributed reproduction number compares assumption homogeneous population can plot expected proportion transmission proportion infectious cases. need write couple custom functions. can now reproduce Figure 1b Lloyd-Smith et al. (2005) using offspring distribution parameters obtained . plot shows variability transmission owing gamma-distributed individual reproduction number (ν\\nu). take slice plot proportion infectious cases equals 0.2 (shown dashed line) can calculate proportion transmission caused infectious 20% cases using proportion_tranmission(..., method = \"t_20\") function. plot replicates Figure 1c Lloyd-Smith et al. (2005). shows different diseases different proportion transmission infectious 20% owing varying degrees overdispersion (kk). plot uses RR 2, however, one characteristic t20t_{20} method different values RR influence proportion transmission, plot look identical value RR. shown equation defining t20t_{20} method integral divided R0R_0 fν(u)f_{\\nu}(u) control proportion transmission. case p80p_{80}, changes RR kk influence proportion transmission. One thing mentioned interpretation p80p_{80} t20t_{20} methods interchangeable, additionally, t80t_{80} p20p_{20} equal. Stated differently, p80p_{80} method calculate proportion transmission cause 20% cases, t20t_{20} method calculate proportion transmission caused infectious 80% equivalent. also case 1−p80≠t201 - p_{80} \\neq t_{20}, thus 1−t20≠p801 - t_{20} \\neq p_{80}. vary RR kk show setting p80p_{80} method percent_transmission = 0.2, t20t_{20} method percent_transmission = 0.8 two interchangeably interpreted outlined box . show 1−p80≠t201 - p_{80} \\neq t_{20} 1−t20≠p801 - t_{20} \\neq p_{80}. t20t_{20} method allows true homogeneity k→∞k \\rightarrow \\infty (t20=20%t_{20} = 20\\%), whereas p80p_{80} method allow true homogeneity (p80≠80%p_{80} \\neq 80\\%).","code":"library(epiparameter) offspring_dists <- epiparameter_db( epi_name = \"offspring distribution\" ) #> Returning 10 results that match the criteria (10 are parameterised). #> Use subset to filter by entry variables or single_epiparameter to return a single entry. #> To retrieve the citation for each use the 'get_citation' function diseases <- vapply(offspring_dists, `[[`, FUN.VALUE = character(1), \"disease\") offspring_dists <- offspring_dists[!duplicated(diseases)] diseases <- diseases[!duplicated(diseases)] offspring_dist_params <- vapply( offspring_dists, get_parameters, FUN.VALUE = numeric(2) ) offspring_dist_params <- data.frame( disease = diseases, t(offspring_dist_params) ) offspring_dist_params #> disease mean dispersion #> 1 SARS 1.63 0.16 #> 2 Smallpox 3.19 0.37 #> 3 Mpox 0.32 0.58 #> 4 Pneumonic Plague 1.32 1.37 #> 5 Hantavirus Pulmonary Syndrome 0.70 1.66 #> 6 Ebola Virus Disease 1.50 5.10 offspring_dist_params$t20 <- do.call( rbind, apply( offspring_dist_params, MARGIN = 1, function(x) { proportion_transmission( R = as.numeric(x[2]), k = as.numeric(x[3]), percent_transmission = 0.2, method = \"t_20\", format_prop = FALSE ) } ) )[, 3] offspring_dist_params$p80 <- do.call( rbind, apply( offspring_dist_params, MARGIN = 1, function(x) { proportion_transmission( R = as.numeric(x[2]), k = as.numeric(x[3]), percent_transmission = 0.8, method = \"p_80\", format_prop = FALSE ) } ) )[, 3] offspring_dist_params #> disease mean dispersion t20 p80 #> 1 SARS 1.63 0.16 0.8825175 0.1300095 #> 2 Smallpox 3.19 0.37 0.7125723 0.2405781 #> 3 Mpox 0.32 0.58 0.6201376 0.1609538 #> 4 Pneumonic Plague 1.32 1.37 0.4737949 0.3392229 #> 5 Hantavirus Pulmonary Syndrome 0.70 1.66 0.4476538 0.3023708 #> 6 Ebola Virus Disease 1.50 5.10 0.3363023 0.4315065 # nolint start for `:::` get_infectious_curve <- function(R, k) { # upper limit of x when y = 0 upper_u <- superspreading:::solve_for_u(prop = 0, R = R, k = k) upper_u <- round(upper_u) u_seq <- superspreading:::lseq(from = 1e-5, to = upper_u, length.out = 500) res <- lapply(u_seq, function(upper) { integrate( function(u) u * superspreading:::fvx(x = u, R, k), lower = 0, upper = upper )$value / R }) expected_v_more_than_x <- 1 - unlist(res) proportion_more_than_x <- 1 - superspreading:::pgammaRk(u_seq, R = R, k = k) data.frame( exp_t = expected_v_more_than_x, prop_i = proportion_more_than_x ) } # nolint end infect_curve <- map(offspring_dist_params %>% group_split(disease), function(x) { get_infectious_curve(R = x$mean, k = x$dispersion) %>% mutate( disease = x$disease, R = x$mean, k = x$dispersion ) }) infect_curve <- do.call(rbind, infect_curve) ggplot( data = infect_curve, aes(x = prop_i, y = exp_t, colour = disease) ) + geom_line() + geom_abline(slope = 1) + geom_vline(xintercept = 0.2, linetype = 2, alpha = 0.2) + scale_x_continuous(breaks = seq(0, 1, by = 0.2)) + theme_classic() + theme( aspect.ratio = 1, legend.position = \"right\" ) + annotate( geom = \"text\", angle = 45, size = 2.5, x = 0.5, y = 0.5, vjust = 1.5, label = \"Homogeneous population\" ) + labs( x = \"Proportion of infectious cases (ranked)\", y = \"Expected proportion of transmission\", colour = \"\" ) + coord_cartesian(expand = FALSE) k_seq <- superspreading:::lseq(from = 0.01, to = 100, length.out = 1000) # nolint y <- map_dbl( k_seq, function(x) { proportion_transmission( R = 2, k = x, percent_transmission = 0.2, method = \"t_20\", format_prop = FALSE )[, 3] } ) prop_t20 <- data.frame(k_seq, y) ggplot() + geom_line(data = prop_t20, mapping = aes(x = k_seq, y = y)) + geom_point( data = offspring_dist_params, mapping = aes( x = dispersion, y = t20, fill = disease ), shape = 21, size = 3 ) + geom_hline(yintercept = c(0.2, 0.8), linetype = 2, alpha = 0.2) + theme_classic() + theme( aspect.ratio = 1 ) + scale_y_continuous( name = paste( \"Proportion of transmission expected from\", \"the most infectious 20% of cases\", sep = \" \\n\" ), limits = c(0, 1), breaks = seq(0, 1, by = 0.2) ) + scale_x_log10(name = \"Dispersion parameter\", expand = c(0, 0)) + labs(fill = \"\") # For k = 0.5 proportion_transmission( R = 0.1, k = 0.5, percent_transmission = 0.8, method = \"t_20\" ) #> R k prop_80 #> 1 0.1 0.5 99.6% proportion_transmission( R = 1, k = 0.5, percent_transmission = 0.8, method = \"t_20\" ) #> R k prop_80 #> 1 1 0.5 99.6% proportion_transmission( R = 5, k = 0.5, percent_transmission = 0.8, method = \"t_20\" ) #> R k prop_80 #> 1 5 0.5 99.6% # For k = 2 proportion_transmission( R = 0.1, k = 2, percent_transmission = 0.8, method = \"t_20\" ) #> R k prop_80 #> 1 0.1 2 94.9% proportion_transmission( R = 1, k = 2, percent_transmission = 0.8, method = \"t_20\" ) #> R k prop_80 #> 1 1 2 94.9% proportion_transmission( R = 5, k = 2, percent_transmission = 0.8, method = \"t_20\" ) #> R k prop_80 #> 1 5 2 94.9% # For k = 0.5 proportion_transmission( R = 0.1, k = 0.5, percent_transmission = 0.8, method = \"p_80\" ) #> R k prop_80 #> 1 0.1 0.5 6.71% proportion_transmission( R = 1, k = 0.5, percent_transmission = 0.8, method = \"p_80\" ) #> R k prop_80 #> 1 1 0.5 22.6% proportion_transmission( R = 5, k = 0.5, percent_transmission = 0.8, method = \"p_80\" ) #> R k prop_80 #> 1 5 0.5 29.3% # For k = 2 proportion_transmission( R = 0.1, k = 2, percent_transmission = 0.8, method = \"p_80\" ) #> R k prop_80 #> 1 0.1 2 7.3% proportion_transmission( R = 1, k = 2, percent_transmission = 0.8, method = \"p_80\" ) #> R k prop_80 #> 1 1 2 35.6% proportion_transmission( R = 5, k = 2, percent_transmission = 0.8, method = \"p_80\" ) #> R k prop_80 #> 1 5 2 48.9% # R = 1, k = 0.5 proportion_transmission( R = 1, k = 0.5, percent_transmission = 0.2, method = \"p_80\" ) #> R k prop_20 #> 1 1 0.5 2.45% proportion_transmission( R = 1, k = 0.5, percent_transmission = 0.8, method = \"t_20\" ) #> R k prop_80 #> 1 1 0.5 99.6% # R = 3, k = 2 proportion_transmission( R = 3, k = 2, percent_transmission = 0.2, method = \"p_80\" ) #> R k prop_20 #> 1 3 2 5.86% proportion_transmission( R = 3, k = 2, percent_transmission = 0.8, method = \"t_20\" ) #> R k prop_80 #> 1 3 2 94.9% 1 - proportion_transmission( R = 1, k = 0.5, percent_transmission = 0.8, method = \"p_80\", format_prop = FALSE )[, 3] #> [1] 0.7735753 proportion_transmission( R = 1, k = 0.5, percent_transmission = 0.2, method = \"t_20\" ) #> R k prop_20 #> 1 1 0.5 65% 1 - proportion_transmission( R = 1, k = 0.5, percent_transmission = 0.2, method = \"t_20\", format_prop = FALSE )[, 3] #> [1] 0.3501798 proportion_transmission( R = 1, k = 0.5, percent_transmission = 0.8, method = \"p_80\" ) #> R k prop_80 #> 1 1 0.5 22.6% proportion_transmission( R = 1, k = Inf, percent_transmission = 0.8, method = \"p_80\" ) #> Infinite values of k are being approximated by 1e5 for calculations. #> R k prop_80 #> 1 1 1e+05 43.2% proportion_transmission( R = 1, k = Inf, percent_transmission = 0.8, method = \"t_20\" ) #> Infinite values of k are being approximated by 1e5 for calculations. #> R k prop_80 #> 1 1 1e+05 80.1%"},{"path":"https://epiverse-trace.github.io/superspreading/articles/superspreading.html","id":"definition","dir":"Articles","previous_headings":"","what":"Definition","title":"Getting started with {superspreading}","text":"Superspreading describes individual heterogeneity disease transmission, individuals transmit many infectees infectors infect zero individuals (Lloyd-Smith et al. 2005).","code":""},{"path":"https://epiverse-trace.github.io/superspreading/articles/superspreading.html","id":"probability-of-epidemic","dir":"Articles","previous_headings":"","what":"Probability of epidemic","title":"Getting started with {superspreading}","text":"probability novel disease cause epidemic (.e. sustained transmission population) determined nature diseases’ transmission heterogeneity. variability may intrinsic property disease, product human behaviour social mixing patterns. given value RR, variability high, probability outbreak cause epidemic lower superspreading events rare. Whereas lower variability probability higher individuals closer mean (RR). use RR represent reproduction number (number secondary cases caused typical case). Depending situation, may equivalent basic reproduction number (R0R_0, representing transmission fully susceptible population) effective reproduction number given point time (RtR_t, representing extent transmission time tt). Either can input functions provided {superspreading} probability_epidemic() function {superspreading} can calculate probability. kk dispersion parameter negative binomial distribution controls variability individual-level transmission. code, kk values one represent low heterogeneity (case k→∞k \\rightarrow \\infty poisson distribution), kk decreases, heterogeneity increases. kk equals 1, distribution geometric. Values kk less one indicate overdispersion disease transmission, signature superspreading. value RR increases, causes probability epidemic increase, kk remains . value RR less equal one zero probability causing sustained epidemic. Finally, probability new infection cause large epidemic influenced number initial infections seeding outbreak. define number initial infections.","code":"probability_epidemic(R = 1.5, k = 1, num_init_infect = 1) #> [1] 0.3333333 probability_epidemic(R = 1.5, k = 0.5, num_init_infect = 1) #> [1] 0.2324081 probability_epidemic(R = 1.5, k = 0.1, num_init_infect = 1) #> [1] 0.06765766 probability_epidemic(R = 0.5, k = 1, num_init_infect = 1) #> [1] 0 probability_epidemic(R = 1.0, k = 1, num_init_infect = 1) #> [1] 0 probability_epidemic(R = 1.5, k = 1, num_init_infect = 1) #> [1] 0.3333333 probability_epidemic(R = 5, k = 1, num_init_infect = 1) #> [1] 0.8 probability_epidemic(R = 1.5, k = 1, num_init_infect = 1) #> [1] 0.3333333 probability_epidemic(R = 1.5, k = 1, num_init_infect = 10) #> [1] 0.9826585 probability_epidemic(R = 1.5, k = 1, num_init_infect = 100) #> [1] 1"},{"path":"https://epiverse-trace.github.io/superspreading/articles/superspreading.html","id":"empirical-superspreading","dir":"Articles","previous_headings":"","what":"Empirical superspreading","title":"Getting started with {superspreading}","text":"Given probability_epidemic() possible determine probability epidemic diseases parameters offspring distribution estimated. offspring distribution simply distribution number secondary infections caused primary infection. distribution RR, mean distribution given RR. can use {epiparameter} load offspring distributions multiple diseases evaluate likely cause epidemics. parameters distribution can extracted: example assume initial pool infectors one (num_init_infect = 1) can easily adjusted case evidence larger initial seeding infections, whether animal--human spillover imported cases outside area interest. can see probability epidemic given estimates Lloyd-Smith et al. (2005) greater Ebola SARS. due offspring distribution Ebola larger dispersion (dispersion kk = 5.1), compared SARS, relatively small dispersion (kk = 0.16).","code":"sars <- epiparameter_db( disease = \"SARS\", epi_name = \"offspring distribution\", single_epiparameter = TRUE ) #> Using Lloyd-Smith J, Schreiber S, Kopp P, Getz W (2005). \"Superspreading and #> the effect of individual variation on disease emergence.\" _Nature_. #> doi:10.1038/nature04153 .. #> To retrieve the citation use the 'get_citation' function evd <- epiparameter_db( disease = \"Ebola Virus Disease\", epi_name = \"offspring distribution\", single_epiparameter = TRUE ) #> Using Lloyd-Smith J, Schreiber S, Kopp P, Getz W (2005). \"Superspreading and #> the effect of individual variation on disease emergence.\" _Nature_. #> doi:10.1038/nature04153 .. #> To retrieve the citation use the 'get_citation' function sars_params <- get_parameters(sars) sars_params #> mean dispersion #> 1.63 0.16 evd_params <- get_parameters(evd) evd_params #> mean dispersion #> 1.5 5.1 family(sars) #> [1] \"nbinom\" probability_epidemic( R = sars_params[[\"mean\"]], k = sars_params[[\"dispersion\"]], num_init_infect = 1 ) #> [1] 0.1198705 family(evd) #> [1] \"nbinom\" probability_epidemic( R = evd_params[[\"mean\"]], k = evd_params[[\"dispersion\"]], num_init_infect = 1 ) #> [1] 0.5092324"},{"path":[]},{"path":"https://epiverse-trace.github.io/superspreading/authors.html","id":null,"dir":"","previous_headings":"","what":"Authors","title":"Authors and Citation","text":"Joshua W. Lambert. Author, maintainer, copyright holder. Adam Kucharski. Author, copyright holder. Dillon C. Adam. Author. Sebastian Funk. Contributor, copyright holder. .chain_sim uses code bpmodels::chain_sim Pratik Gupte. Reviewer. Hugo Gruson. Reviewer. James M. Azam. Reviewer, contributor.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/authors.html","id":"citation","dir":"","previous_headings":"","what":"Citation","title":"Authors and Citation","text":"Lambert J, Kucharski , Adam D (2024). superspreading: Estimate Individual-Level Variation Transmission. R package version 0.2.0.9000, https://epiverse-trace.github.io/superspreading/, https://github.com/epiverse-trace/superspreading.","code":"@Manual{, title = {superspreading: Estimate Individual-Level Variation in Transmission}, author = {Joshua W. Lambert and Adam Kucharski and Dillon C. Adam}, year = {2024}, note = {R package version 0.2.0.9000, https://epiverse-trace.github.io/superspreading/}, url = {https://github.com/epiverse-trace/superspreading}, }"},{"path":"https://epiverse-trace.github.io/superspreading/index.html","id":"superspreading-estimate-individual-level-variation-in-transmission-","dir":"","previous_headings":"","what":"Estimate Individual-Level Variation in Transmission","title":"Estimate Individual-Level Variation in Transmission","text":"superspreading R package provides set functions estimate understand individual-level variation transmission infectious diseases data secondary cases. superspreading implements methods outlined Lloyd-Smith et al. (2005), Adam J. Kucharski et al. (2020), Kremer et al. (2021), well additional functions. superspreading developed Centre Mathematical Modelling Infectious Diseases London School Hygiene Tropical Medicine part Epiverse-TRACE.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/index.html","id":"installation","dir":"","previous_headings":"","what":"Installation","title":"Estimate Individual-Level Variation in Transmission","text":"easiest way install development version superspreading GitHub use pak package:","code":"# check whether {pak} is installed if(!require(\"pak\")) install.packages(\"pak\") pak::pak(\"epiverse-trace/superspreading\")"},{"path":"https://epiverse-trace.github.io/superspreading/index.html","id":"quick-start","dir":"","previous_headings":"","what":"Quick start","title":"Estimate Individual-Level Variation in Transmission","text":"","code":"library(superspreading)"},{"path":"https://epiverse-trace.github.io/superspreading/index.html","id":"calculate-the-heterogeneity-of-transmission","dir":"","previous_headings":"Quick start","what":"Calculate the heterogeneity of transmission","title":"Estimate Individual-Level Variation in Transmission","text":"Case study using data early Ebola outbreak Guinea 2014, stratified index non-index cases, Adam J. Kucharski et al. (2016). Data transmission index secondary cases Ebola 2014. Source: Faye et al. (2015) & Althaus (2015). {fitdistrplus} well-developed stable R package provides variety methods fitting distribution models data (Delignette-Muller Dutang 2015). Therefore, used throughout documentation superspreading recommended package wanting fit distribution models, example supplied superspreading (Poisson-lognormal Poisson-Weibull). recommend reading fitdistrplus documentation (specifically ?fitdist) explore full range functionality. example fit negative binomial distribution estimate reproduction number (RR, mean distribution) dispersion (kk, measure variance distribution). parameters estimated via maximum likelihood (default method fitdist()). reproduction number (RR) higher index cases non-index cases, heterogeneity transmission higher non-index cases (.e. kk lower).","code":"# we use {fitdistrplus} to fit the models library(fitdistrplus) #> Loading required package: MASS #> Loading required package: survival # 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"},{"path":"https://epiverse-trace.github.io/superspreading/index.html","id":"calculate-the-probability-of-a-large-epidemic","dir":"","previous_headings":"Quick start","what":"Calculate the probability of a large epidemic","title":"Estimate Individual-Level Variation in Transmission","text":"Given reproduction number (RR) dispersion (kk), probability infectious disease cause epidemic, words probability go extinct, can calculated using probability_epidemic(). use probability_epidemic() parameters estimated section Ebola, assuming three initial infections seeding potential outbreak. probability causing sustained outbreak high index cases, zero non-index cases (.e. disease transmission inevitably cease assuming transmission dynamics change).","code":"# 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 probability_epidemic( R = param_index$estimate[[\"R\"]], k = param_index$estimate[[\"k\"]], num_init_infect = initial_infections ) #> [1] 0.9995741 # Probability of an epidemic using k estimated from non-index cases probability_epidemic( R = param_non_index$estimate[[\"R\"]], k = param_non_index$estimate[[\"k\"]], num_init_infect = initial_infections ) #> [1] 0"},{"path":"https://epiverse-trace.github.io/superspreading/index.html","id":"package-vignettes","dir":"","previous_headings":"","what":"Package vignettes","title":"Estimate Individual-Level Variation in Transmission","text":"details use superspreading can found online documentation package vignettes, “Articles”.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/index.html","id":"visualisation-and-plotting-functionality","dir":"","previous_headings":"Package vignettes","what":"Visualisation and plotting functionality","title":"Estimate Individual-Level Variation in Transmission","text":"superspreading provide plotting functions, instead provide example code chunks package’s vignettes can used templates upon data visualisations can modified. recommend users copy edit examples purposes. (permitted package’s MIT license). default code chunks plotting folded, order unfold see code simply click code button top left plot.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/index.html","id":"help","dir":"","previous_headings":"","what":"Help","title":"Estimate Individual-Level Variation in Transmission","text":"report bug please open issue","code":""},{"path":"https://epiverse-trace.github.io/superspreading/index.html","id":"contribute","dir":"","previous_headings":"","what":"Contribute","title":"Estimate Individual-Level Variation in Transmission","text":"Contributions superspreading welcomed. Please follow package contributing guide.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/index.html","id":"code-of-conduct","dir":"","previous_headings":"","what":"Code of Conduct","title":"Estimate Individual-Level Variation in Transmission","text":"Please note {superspreading} project released Contributor Code Conduct. contributing project, agree abide terms.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/index.html","id":"citing-this-package","dir":"","previous_headings":"","what":"Citing this package","title":"Estimate Individual-Level Variation in Transmission","text":"","code":"citation(\"superspreading\") #> To cite package 'superspreading' in publications use: #> #> Lambert J, Kucharski A, Adam D (2024). _superspreading: Estimate #> Individual-Level Variation in Transmission_. R package version #> 0.2.0.9000, https://epiverse-trace.github.io/superspreading/, #> . #> #> A BibTeX entry for LaTeX users is #> #> @Manual{, #> title = {superspreading: Estimate Individual-Level Variation in Transmission}, #> author = {Joshua W. Lambert and Adam Kucharski and Dillon C. Adam}, #> year = {2024}, #> note = {R package version 0.2.0.9000, #> https://epiverse-trace.github.io/superspreading/}, #> url = {https://github.com/epiverse-trace/superspreading}, #> }"},{"path":"https://epiverse-trace.github.io/superspreading/index.html","id":"related-projects","dir":"","previous_headings":"","what":"Related projects","title":"Estimate Individual-Level Variation in Transmission","text":"project overlap R packages: {bpmodels} another Epiverse-TRACE R package analyses transmission chain data infer transmission process either size length transmission chains. Two main differences packages : 1) superspreading functions compute metrics characterise outbreaks superspreading events (e.g. probability_epidemic() & probability_extinct()); 2) {bpmodels} can simulate branching process (chain_sim()) specified process (e.g. negative binomial).","code":""},{"path":[]},{"path":"https://epiverse-trace.github.io/superspreading/reference/calc_network_R.html","id":null,"dir":"Reference","previous_headings":"","what":"Calculate the reproduction number (\\(R\\)) for a (heterogeneous) network — calc_network_R","title":"Calculate the reproduction number (\\(R\\)) for a (heterogeneous) network — calc_network_R","text":"calculation reproduction number adjusting heterogeneity number contacts.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/calc_network_R.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Calculate the reproduction number (\\(R\\)) for a (heterogeneous) network — calc_network_R","text":"","code":"calc_network_R( mean_num_contact, sd_num_contact, infect_duration, prob_transmission, age_range )"},{"path":"https://epiverse-trace.github.io/superspreading/reference/calc_network_R.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Calculate the reproduction number (\\(R\\)) for a (heterogeneous) network — calc_network_R","text":"mean_num_contact numeric, mean (average) number new contacts per unit time. sd_num_contact numeric, standard deviation number new contacts per unit time. infect_duration numeric, duration infectiousness. prob_transmission numeric probability transmission per contact, also known \\(\\beta\\). age_range numeric vector two elements, lower upper age limits individuals network.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/calc_network_R.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Calculate the reproduction number (\\(R\\)) for a (heterogeneous) network — calc_network_R","text":"named numeric vector length 2, unadjusted (R) network adjusted (R_net) estimates \\(R\\).","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/calc_network_R.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Calculate the reproduction number (\\(R\\)) for a (heterogeneous) network — calc_network_R","text":"","code":"# example using NATSAL data calc_network_R( mean_num_contact = 14.1, sd_num_contact = 69.6, infect_duration = 1, prob_transmission = 1, age_range = c(16, 74) ) #> R R_net #> 0.2431034 6.1665077"},{"path":"https://epiverse-trace.github.io/superspreading/reference/dot-chain_sim.html","id":null,"dir":"Reference","previous_headings":"","what":"Simulate transmission chains using a stochastic branching process — .chain_sim","title":"Simulate transmission chains using a stochastic branching process — .chain_sim","text":"Code modified bpmodels::chain_sim() function. function chain_sim() function bpmodels reused permission licensed MIT bpmodels. bpmodels CRAN retired.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dot-chain_sim.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Simulate transmission chains using a stochastic branching process — .chain_sim","text":"","code":".chain_sim( n, offspring, stat = c(\"size\", \"length\"), stat_threshold = Inf, generation_time, tf = Inf, ... )"},{"path":"https://epiverse-trace.github.io/superspreading/reference/dot-chain_sim.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Simulate transmission chains using a stochastic branching process — .chain_sim","text":"n Number simulations run. offspring Offspring distribution: character string corresponding R distribution function (e.g., \"pois\" Poisson, rpois() R function generate Poisson random numbers). stat String; Statistic calculate. Can one : \"size\": total number offspring. \"length\": total number ancestors. stat_threshold size length simulation results set Inf. Defaults Inf, resulting results ever set Inf generation_time generation time generator function; name user-defined named anonymous function one argument n, representing number generation times generate. tf End time (generation_time interval given). ... Parameters offspring distribution required R.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dot-chain_sim.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Simulate transmission chains using a stochastic branching process — .chain_sim","text":" columns n (simulation ID), id (unique ID within simulation individual element chain), ancestor (ID ancestor element), generation. time column also appended generation_time interval supplied serial.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dot-chain_sim.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Simulate transmission chains using a stochastic branching process — .chain_sim","text":"Sebastian Funk, James M. Azam, Joshua W. Lambert","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dot-fit.html","id":null,"dir":"Reference","previous_headings":"","what":"Optimise a function using either numerical optimisation or grid search — .fit","title":"Optimise a function using either numerical optimisation or grid search — .fit","text":"Optimise function using either numerical optimisation grid search","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dot-fit.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Optimise a function using either numerical optimisation or grid search — .fit","text":"","code":".fit(func, fit_method = c(\"optim\", \"grid\"), ...)"},{"path":"https://epiverse-trace.github.io/superspreading/reference/dot-fit.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Optimise a function using either numerical optimisation or grid search — .fit","text":"func function. fit_method character string, either \"optim\" \"grid\". ... Named elements replace default optimisation settings either optim() grid search. See details.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dot-fit.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Optimise a function using either numerical optimisation or grid search — .fit","text":"single numeric.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dot-fit.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Optimise a function using either numerical optimisation or grid search — .fit","text":"Arguments passed dots depend whether fit_method set \"optim\" \"grid\". \"optim\", arguments passed optim(), \"grid\", variable arguments lower, upper (lower upper bounds grid search parameter optimised, defaults lower = 0.001 upper = 0.999), \"res\" (resolution grid, default res = 0.001).","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dpoislnorm.html","id":null,"dir":"Reference","previous_headings":"","what":"Density of the poisson-lognormal compound distribution — dpoislnorm","title":"Density of the poisson-lognormal compound distribution — dpoislnorm","text":"Density poisson-lognormal compound distribution","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dpoislnorm.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Density of the poisson-lognormal compound distribution — dpoislnorm","text":"","code":"dpoislnorm(x, meanlog, sdlog)"},{"path":"https://epiverse-trace.github.io/superspreading/reference/dpoislnorm.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Density of the poisson-lognormal compound distribution — dpoislnorm","text":"x number quantile distribution. meanlog number mean distribution log scale. sdlog number standard deviation distribution log scale.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dpoislnorm.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Density of the poisson-lognormal compound distribution — dpoislnorm","text":"numeric vector density poisson-lognormal distribution.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dpoislnorm.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Density of the poisson-lognormal compound distribution — dpoislnorm","text":"function vectorised vector quantiles can input output equal length.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dpoislnorm.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Density of the poisson-lognormal compound distribution — dpoislnorm","text":"","code":"dpoislnorm(x = 10, meanlog = 1, sdlog = 2) #> [1] 0.01626334 dpoislnorm(x = 1:10, meanlog = 1, sdlog = 2) #> [1] 0.14112152 0.08990619 0.06345106 0.04780697 0.03765325 0.03061694 #> [7] 0.02550065 0.02164138 0.01864488 0.01626334"},{"path":"https://epiverse-trace.github.io/superspreading/reference/dpoisweibull.html","id":null,"dir":"Reference","previous_headings":"","what":"Density of the poisson-Weibull compound distribution — dpoisweibull","title":"Density of the poisson-Weibull compound distribution — dpoisweibull","text":"Density poisson-Weibull compound distribution","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dpoisweibull.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Density of the poisson-Weibull compound distribution — dpoisweibull","text":"","code":"dpoisweibull(x, shape, scale)"},{"path":"https://epiverse-trace.github.io/superspreading/reference/dpoisweibull.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Density of the poisson-Weibull compound distribution — dpoisweibull","text":"x number quantile distribution. shape number shape parameter distribution. scale number scale parameter distribution.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dpoisweibull.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Density of the poisson-Weibull compound distribution — dpoisweibull","text":"numeric vector density poisson-Weibull distribution.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dpoisweibull.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Density of the poisson-Weibull compound distribution — dpoisweibull","text":"function vectorised vector quantiles can input output equal length.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dpoisweibull.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Density of the poisson-Weibull compound distribution — dpoisweibull","text":"","code":"dpoisweibull(x = 10, shape = 1, scale = 2) #> [1] 0.00578051 dpoisweibull(x = 1:10, shape = 1, scale = 2) #> [1] 0.222222222 0.148148148 0.098765432 0.065843621 0.043895748 0.029263832 #> [7] 0.019509221 0.013006147 0.008670765 0.005780510"},{"path":"https://epiverse-trace.github.io/superspreading/reference/gamma.html","id":null,"dir":"Reference","previous_headings":"","what":"Defines the gamma functions in terms of the mean reproductive number (R) and the dispersion parameter (k) — gamma","title":"Defines the gamma functions in terms of the mean reproductive number (R) and the dispersion parameter (k) — gamma","text":"dgammaRk() gamma density function pgammaRk() gamma distribution function fvx() fore gamma probability density function (pdf) describing individual reproductive number \\(\\nu\\) given R0 k","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/gamma.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Defines the gamma functions in terms of the mean reproductive number (R) and the dispersion parameter (k) — gamma","text":"","code":"dgammaRk(x, R, k) pgammaRk(x, R, k) fvx(x, R, k)"},{"path":"https://epiverse-trace.github.io/superspreading/reference/gamma.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Defines the gamma functions in terms of the mean reproductive number (R) and the dispersion parameter (k) — gamma","text":"R number specifying R parameter (.e. average secondary cases per infectious individual). k number specifying k parameter (.e. overdispersion offspring distribution fitted negative binomial).","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/ic_tbl.html","id":null,"dir":"Reference","previous_headings":"","what":"Helper function to create a model comparison table — ic_tbl","title":"Helper function to create a model comparison table — ic_tbl","text":"helper function creating model comparison primarily use superspreading vignettes. designed specifically handling fitdistrplus::fitdist() output generalised function. See bbmle::ICtab() general use function create information criteria tables.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/ic_tbl.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Helper function to create a model comparison table — ic_tbl","text":"","code":"ic_tbl(..., sort_by = c(\"AIC\", \"BIC\", \"none\"))"},{"path":"https://epiverse-trace.github.io/superspreading/reference/ic_tbl.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Helper function to create a model comparison table — ic_tbl","text":"... dots One model fit results fitdistrplus::fitdist(). sort_by character string specifying information criterion order table , either \"AIC\" (default), \"BIC\", \"none\" (.e. ordering).","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/ic_tbl.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Helper function to create a model comparison table — ic_tbl","text":".","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/ic_tbl.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Helper function to create a model comparison table — ic_tbl","text":"","code":"if (requireNamespace(\"fitdistrplus\", quietly = TRUE)) { cases <- rnbinom(n = 100, mu = 5, size = 0.7) pois_fit <- fitdistrplus::fitdist(data = cases, distr = \"pois\") geom_fit <- fitdistrplus::fitdist(data = cases, distr = \"geom\") nbinom_fit <- fitdistrplus::fitdist(data = cases, distr = \"nbinom\") ic_tbl(pois_fit, geom_fit, nbinom_fit) } #> distribution AIC DeltaAIC wAIC BIC DeltaBIC #> 1 nbinom 538.9290 0.000000 9.415687e-01 544.1393 0.000000 #> 2 geom 544.4884 5.559391 5.843130e-02 547.0936 2.954221 #> 3 pois 937.8823 398.953300 2.199093e-87 940.4875 396.348130 #> wBIC #> 1 8.141357e-01 #> 2 1.858643e-01 #> 3 6.995101e-87"},{"path":"https://epiverse-trace.github.io/superspreading/reference/lseq.html","id":null,"dir":"Reference","previous_headings":"","what":"Generates a log scaled sequence of real numbers — lseq","title":"Generates a log scaled sequence of real numbers — lseq","text":"Generates log scaled sequence real numbers","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/lseq.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Generates a log scaled sequence of real numbers — lseq","text":"","code":"lseq(from, to, length.out)"},{"path":"https://epiverse-trace.github.io/superspreading/reference/lseq.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Generates a log scaled sequence of real numbers — lseq","text":", starting (maximal) end values sequence. length 1 unless just supplied unnamed argument. length.desired length sequence. non-negative number, seq seq.int rounded fractional.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/lseq.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Generates a log scaled sequence of real numbers — lseq","text":"seq.int default method seq numeric arguments return vector type \"integer\" \"double\": programmers rely . seq_along seq_len return integer vector, unless long vector double.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/ppoislnorm.html","id":null,"dir":"Reference","previous_headings":"","what":"Cumulative distribution function of the poisson-lognormal compound distribution — ppoislnorm","title":"Cumulative distribution function of the poisson-lognormal compound distribution — ppoislnorm","text":"Cumulative distribution function poisson-lognormal compound distribution","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/ppoislnorm.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Cumulative distribution function of the poisson-lognormal compound distribution — ppoislnorm","text":"","code":"ppoislnorm(q, meanlog, sdlog)"},{"path":"https://epiverse-trace.github.io/superspreading/reference/ppoislnorm.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Cumulative distribution function of the poisson-lognormal compound distribution — ppoislnorm","text":"q number quantile distribution. meanlog number mean distribution log scale. sdlog number standard deviation distribution log scale.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/ppoislnorm.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Cumulative distribution function of the poisson-lognormal compound distribution — ppoislnorm","text":"numeric vector distribution function.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/ppoislnorm.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Cumulative distribution function of the poisson-lognormal compound distribution — ppoislnorm","text":"function vectorised vector quantiles can input output equal length.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/ppoislnorm.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Cumulative distribution function of the poisson-lognormal compound distribution — ppoislnorm","text":"","code":"ppoislnorm(q = 10, meanlog = 1, sdlog = 2) #> [1] 0.74796 ppoislnorm(q = 1:10, meanlog = 1, sdlog = 2) #> [1] 0.3964753 0.4863815 0.5498326 0.5976395 0.6352928 0.6659097 0.6914104 #> [8] 0.7130517 0.7316966 0.7479600"},{"path":"https://epiverse-trace.github.io/superspreading/reference/ppoisweibull.html","id":null,"dir":"Reference","previous_headings":"","what":"Cumulative distribution function of the poisson-Weibull compound distribution — ppoisweibull","title":"Cumulative distribution function of the poisson-Weibull compound distribution — ppoisweibull","text":"Cumulative distribution function poisson-Weibull compound distribution","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/ppoisweibull.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Cumulative distribution function of the poisson-Weibull compound distribution — ppoisweibull","text":"","code":"ppoisweibull(q, shape, scale)"},{"path":"https://epiverse-trace.github.io/superspreading/reference/ppoisweibull.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Cumulative distribution function of the poisson-Weibull compound distribution — ppoisweibull","text":"q number quantile distribution. shape number shape parameter distribution. scale number scale parameter distribution.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/ppoisweibull.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Cumulative distribution function of the poisson-Weibull compound distribution — ppoisweibull","text":"numeric vector distribution function.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/ppoisweibull.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Cumulative distribution function of the poisson-Weibull compound distribution — ppoisweibull","text":"function vectorised vector quantiles can input output equal length.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/ppoisweibull.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Cumulative distribution function of the poisson-Weibull compound distribution — ppoisweibull","text":"","code":"ppoisweibull(q = 10, shape = 1, scale = 2) #> [1] 0.988439 ppoisweibull(q = 1:10, shape = 1, scale = 2) #> [1] 0.5555556 0.7037037 0.8024691 0.8683128 0.9122085 0.9414723 0.9609816 #> [8] 0.9739877 0.9826585 0.9884390"},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_contain.html","id":null,"dir":"Reference","previous_headings":"","what":"Probability that an outbreak will be contained — probability_contain","title":"Probability that an outbreak will be contained — probability_contain","text":"Outbreak containment defined outbreak extinction simulate = FALSE. simulate = FALSE, probability_contain() equivalent calling probability_extinct(). simulate = TRUE, outbreak containment defined case_threshold (default = 100) outbreak_time arguments. Firstly, case_threshold sets size transmission chain outbreak considered contained. Secondly, outbreak_time sets time duration start outbreak within outbreak contained onwards transmission beyond time. setting outbreak_time, generation_time also required. case_threshold outbreak_time can jointly set. Overall, simulate = TRUE, containment defined size time duration transmission chain reaching case_threshold outbreak_time, respectively.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_contain.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Probability that an outbreak will be contained — probability_contain","text":"","code":"probability_contain( R, k, num_init_infect, ind_control = 0, pop_control = 0, simulate = FALSE, ..., case_threshold = 100, outbreak_time = Inf, generation_time = NULL, offspring_dist )"},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_contain.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Probability that an outbreak will be contained — probability_contain","text":"R number specifying R parameter (.e. average secondary cases per infectious individual). k number specifying k parameter (.e. overdispersion offspring distribution fitted negative binomial). num_init_infect integer (least \"integerish\" stored double) specifying number initial infections. ind_control numeric specifying strength individual-level control measures. 0 (default) 1 (maximum). pop_control numeric specifying strength population-level control measures. 0 (default) 1 (maximum). simulate logical boolean determining whether probability containment calculated analytically numerically using stochastic branching process model. Default FALSE calls probability_extinct(), setting TRUE uses branching process enables setting case_threshold, outbreak_time generation_time arguments. ... Named elements replace default arguments chain_sim(). See details. case_threshold number threshold number cases epidemic considered contained. case_threshold used simulate = TRUE. outbreak_time number time since start outbreak determine outbreaks contained within given period time. outbreak_time used simulate = TRUE. generation_time function generate generation times. function must single argument return numeric vector generation times. See details example. function can defined anonymous. generation_time used simulate = TRUE. offspring_dist object. S3 class working epidemiological parameters/distributions, see epiparameter::epiparameter().","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_contain.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Probability that an outbreak will be contained — probability_contain","text":"number probability containment.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_contain.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Probability that an outbreak will be contained — probability_contain","text":"using simulate = TRUE, default arguments simulate transmission chains chain_sim() 1e5 replicates, negative binomial (nbinom) offspring distribution, parameterised R (pop_control > 0) k. setting outbreak_time argument, generation_time argument also required. generation_time argument requires random number generator function. example, assume generation time lognormally distributed meanlog = 1 sdlog = 1.5, can define function pass generation_time :","code":"function(x) rlnorm(x, meanlog = 1, sdlog = 1.5)"},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_contain.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Probability that an outbreak will be contained — probability_contain","text":"Lloyd-Smith, J. O., Schreiber, S. J., Kopp, P. E., & Getz, W. M. (2005) Superspreading effect individual variation disease emergence. Nature, 438(7066), 355-359. doi:10.1038/nature04153","code":""},{"path":[]},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_contain.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Probability that an outbreak will be contained — probability_contain","text":"","code":"# population-level control measures probability_contain(R = 1.5, k = 0.5, num_init_infect = 1, pop_control = 0.1) #> [1] 0.8213172 # individual-level control measures probability_contain(R = 1.5, k = 0.5, num_init_infect = 1, ind_control = 0.1) #> [1] 0.8391855 # both levels of control measures probability_contain( R = 1.5, k = 0.5, num_init_infect = 1, ind_control = 0.1, pop_control = 0.1 ) #> [1] 0.8915076 # multi initial infections with population-level control measures probability_contain(R = 1.5, k = 0.5, num_init_infect = 5, pop_control = 0.1) #> [1] 0.3737271 # probability of containment within a certain amount of time # this requires parameterising a generation time gt <- function(n) { rlnorm(n, meanlog = 1, sdlog = 1.5) } probability_contain( R = 1.5, k = 0.5, num_init_infect = 1, simulate = TRUE, case_threshold = 100, outbreak_time = 20, generation_time = gt ) #> [1] 0.67173"},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_epidemic.html","id":null,"dir":"Reference","previous_headings":"","what":"Calculate the probability a disease will cause an outbreak based on R, k and initial cases — probability_epidemic","title":"Calculate the probability a disease will cause an outbreak based on R, k and initial cases — probability_epidemic","text":"Calculates probability branching process cause epidemic (.e. probability fail go extinct) based R, k initial cases.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_epidemic.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Calculate the probability a disease will cause an outbreak based on R, k and initial cases — probability_epidemic","text":"","code":"probability_epidemic( R, k, num_init_infect, ind_control = 0, pop_control = 0, ..., offspring_dist )"},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_epidemic.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Calculate the probability a disease will cause an outbreak based on R, k and initial cases — probability_epidemic","text":"R number specifying R parameter (.e. average secondary cases per infectious individual). k number specifying k parameter (.e. overdispersion offspring distribution fitted negative binomial). num_init_infect integer (least \"integerish\" stored double) specifying number initial infections. ind_control numeric specifying strength individual-level control measures. 0 (default) 1 (maximum). pop_control numeric specifying strength population-level control measures. 0 (default) 1 (maximum). ... Named elements replace default optimisation settings. Currently \"fit_method\" accepted can either \"optim\" (default) \"grid\" numerical optimisation routine grid search, respectively. offspring_dist object. S3 class working epidemiological parameters/distributions, see epiparameter::epiparameter().","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_epidemic.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Calculate the probability a disease will cause an outbreak based on R, k and initial cases — probability_epidemic","text":"value probability large epidemic.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_epidemic.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Calculate the probability a disease will cause an outbreak based on R, k and initial cases — probability_epidemic","text":"Lloyd-Smith, J. O., Schreiber, S. J., Kopp, P. E., & Getz, W. M. (2005) Superspreading effect individual variation disease emergence. Nature, 438(7066), 355-359. doi:10.1038/nature04153 Kucharski, . J., Russell, T. W., Diamond, C., Liu, Y., Edmunds, J., Funk, S. & Eggo, R. M. (2020). Early dynamics transmission control COVID-19: mathematical modelling study. Lancet Infectious Diseases, 20(5), 553-558. doi:10.1016/S1473-3099(20)30144-4","code":""},{"path":[]},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_epidemic.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Calculate the probability a disease will cause an outbreak based on R, k and initial cases — probability_epidemic","text":"","code":"probability_epidemic(R = 1.5, k = 0.1, num_init_infect = 10) #> [1] 0.5036888"},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_extinct.html","id":null,"dir":"Reference","previous_headings":"","what":"Calculate the probability a branching process will go extinct based on R, k and initial cases — probability_extinct","title":"Calculate the probability a branching process will go extinct based on R, k and initial cases — probability_extinct","text":"Calculates probability branching process causes epidemic go extinct. complement probability disease causing epidemic (probability_epidemic()).","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_extinct.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Calculate the probability a branching process will go extinct based on R, k and initial cases — probability_extinct","text":"","code":"probability_extinct( R, k, num_init_infect, ind_control = 0, pop_control = 0, ..., offspring_dist )"},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_extinct.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Calculate the probability a branching process will go extinct based on R, k and initial cases — probability_extinct","text":"R number specifying R parameter (.e. average secondary cases per infectious individual). k number specifying k parameter (.e. overdispersion offspring distribution fitted negative binomial). num_init_infect integer (least \"integerish\" stored double) specifying number initial infections. ind_control numeric specifying strength individual-level control measures. 0 (default) 1 (maximum). pop_control numeric specifying strength population-level control measures. 0 (default) 1 (maximum). ... Named elements replace default optimisation settings. Currently \"fit_method\" accepted can either \"optim\" (default) \"grid\" numerical optimisation routine grid search, respectively. offspring_dist object. S3 class working epidemiological parameters/distributions, see epiparameter::epiparameter().","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_extinct.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Calculate the probability a branching process will go extinct based on R, k and initial cases — probability_extinct","text":"value probability going extinct.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_extinct.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Calculate the probability a branching process will go extinct based on R, k and initial cases — probability_extinct","text":"Lloyd-Smith, J. O., Schreiber, S. J., Kopp, P. E., & Getz, W. M. (2005). Superspreading effect individual variation disease emergence. Nature, 438(7066), 355-359. doi:10.1038/nature04153","code":""},{"path":[]},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_extinct.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Calculate the probability a branching process will go extinct based on R, k and initial cases — probability_extinct","text":"","code":"probability_extinct(R = 1.5, k = 0.1, num_init_infect = 10) #> [1] 0.4963112"},{"path":"https://epiverse-trace.github.io/superspreading/reference/proportion_cluster_size.html","id":null,"dir":"Reference","previous_headings":"","what":"Estimate what proportion of new cases originated within a transmission event of a given size — proportion_cluster_size","title":"Estimate what proportion of new cases originated within a transmission event of a given size — proportion_cluster_size","text":"Calculates proportion new cases originated transmission event given size. can useful inform backwards contact tracing efforts, .e. many cases associated large clusters. define cluster transmission primary case least one secondary case.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/proportion_cluster_size.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Estimate what proportion of new cases originated within a transmission event of a given size — proportion_cluster_size","text":"","code":"proportion_cluster_size( R, k, cluster_size, ..., offspring_dist, format_prop = TRUE )"},{"path":"https://epiverse-trace.github.io/superspreading/reference/proportion_cluster_size.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Estimate what proportion of new cases originated within a transmission event of a given size — proportion_cluster_size","text":"R number specifying R parameter (.e. average secondary cases per infectious individual). k number specifying k parameter (.e. overdispersion offspring distribution fitted negative binomial). cluster_size number cluster size threshold. ... dots used, extra arguments supplied cause warning. offspring_dist object. S3 class working epidemiological parameters/distributions, see epiparameter::epiparameter(). format_prop logical determining whether proportion column returned function formatted string percentage sign (%), (TRUE, default), numeric (FALSE).","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/proportion_cluster_size.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Estimate what proportion of new cases originated within a transmission event of a given size — proportion_cluster_size","text":" value proportion new cases part transmission event threshold given value R k.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/proportion_cluster_size.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Estimate what proportion of new cases originated within a transmission event of a given size — proportion_cluster_size","text":"function calculates proportion secondary cases caused transmission events certain size. calculate proportion transmission events cause cluster secondary cases certain size. words number cases threshold divided total number cases, number transmission events certain threshold divided number transmission events.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/proportion_cluster_size.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Estimate what proportion of new cases originated within a transmission event of a given size — proportion_cluster_size","text":"","code":"R <- 2 k <- 0.1 cluster_size <- 10 proportion_cluster_size(R = R, k = k, cluster_size = cluster_size) #> R k prop_10 #> 1 2 0.1 68.8% # example with a vector of k k <- c(0.1, 0.2, 0.3, 0.4, 0.5) proportion_cluster_size(R = R, k = k, cluster_size = cluster_size) #> R k prop_10 #> 1 2 0.1 69.1% #> 2 2 0.2 51% #> 3 2 0.3 38.1% #> 4 2 0.4 31.3% #> 5 2 0.5 25.4% # example with a vector of cluster sizes cluster_size <- c(5, 10, 25) proportion_cluster_size(R = R, k = k, cluster_size = cluster_size) #> R k prop_5 prop_10 prop_25 #> 1 2 0.1 85.7% 68.8% 34.1% #> 2 2 0.2 76.4% 51% 13.9% #> 3 2 0.3 69.4% 39.2% 5.83% #> 4 2 0.4 63.8% 30.4% 2.92% #> 5 2 0.5 59.7% 24.9% 1.39%"},{"path":"https://epiverse-trace.github.io/superspreading/reference/proportion_transmission.html","id":null,"dir":"Reference","previous_headings":"","what":"Estimate what proportion of cases cause a certain proportion of transmission — proportion_transmission","title":"Estimate what proportion of cases cause a certain proportion of transmission — proportion_transmission","text":"Calculates proportion cases cause certain percentage transmission. commonly estimated proportion cases cause 80% transmission (.e. secondary cases). can calculated using proportion_transmission() varying values \\(R\\) different values percentage transmission. two methods calculating proportion transmission, \\(p_{80}\\) (default) \\(t_{20}\\), see method argument details information.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/proportion_transmission.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Estimate what proportion of cases cause a certain proportion of transmission — proportion_transmission","text":"","code":"proportion_transmission( R, k, percent_transmission, method = c(\"p_80\", \"t_20\"), simulate = FALSE, ..., offspring_dist, format_prop = TRUE )"},{"path":"https://epiverse-trace.github.io/superspreading/reference/proportion_transmission.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Estimate what proportion of cases cause a certain proportion of transmission — proportion_transmission","text":"R number specifying R parameter (.e. average secondary cases per infectious individual). k number specifying k parameter (.e. overdispersion offspring distribution fitted negative binomial). percent_transmission number percentage transmission proportion cases produced. method character string defining method used calculate proportion transmission. Options \"p_80\" (default) \"t_20\". See details information methods. simulate logical whether calculation done numerically (.e. simulate secondary contacts) analytically. Default FALSE uses analytical calculation. ... dots used, extra arguments supplied cause warning. offspring_dist object. S3 class working epidemiological parameters/distributions, see epiparameter::epiparameter(). format_prop logical determining whether proportion column returned function formatted string percentage sign (%), (TRUE, default), numeric (FALSE).","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/proportion_transmission.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Estimate what proportion of cases cause a certain proportion of transmission — proportion_transmission","text":" value proportion cases given value R k.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/proportion_transmission.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Estimate what proportion of cases cause a certain proportion of transmission — proportion_transmission","text":"Calculates expected proportion transmission given proportion infectious cases. two methods calculate distinct formulations, \\(p_{80}\\) \\(t_{20}\\) can specified method argument. method = p_80 calculates relative transmission heterogeneity offspring distribution secondary cases, \\(Z\\), upper proportion distribution comprise \\(x\\%\\) total number cases given R0 k, \\(x\\) typically defined 0.8 80%. e.g. 80% transmissions generated upper 20% cases, p_80 = 0.2, per 80/20 rule. formulation, changes R can significant effect estimate \\(p_80\\) even k constant. Importantly, formulation allow true homogeneity k = Inf .e. \\(p_{80} = 0.8\\). method = t_20 calculates similar ratio, instead terms theoretical individual reproductive number infectiousness given R0 k. individual reproductive number, 'v', described Lloyd-Smith JO et al. (2005), \"random variable representing expected number secondary cases caused particular infected individual. Values v drawn continuous gamma probability distribution population mean R0 dispersion parameter k, encodes variation infectious histories individuals, including properties host pathogen environmental circumstances.\" value k corresponds shape parameters gamma distribution encodes variation gamma-poisson mixture aka negative binomial method = t_20, define upper proportion infectiousness, typically 0.2 .e. upper 20% infectious cases, per 80/20 rule. e.g. infectious 20% cases, expected produce 80% infections, t_20 = 0.8. Unlike method = p_80, changes R effect estimate t_80 k constant, R still required underlying calculation. formulation allow true homogeneity k = Inf .e. t_20 = 0.2, t_80 = 0.8. Multiple values R k can supplied every combination returned. numerical calculation method = p_80 uses random number generation simulate secondary contacts answers may minimally vary calls. number simulation replicates fixed 1e5.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/proportion_transmission.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Estimate what proportion of cases cause a certain proportion of transmission — proportion_transmission","text":"analytical calculation : Endo, ., Abbott, S., Kucharski, . J., & Funk, S. (2020) Estimating overdispersion COVID-19 transmission using outbreak sizes outside China. Wellcome Open Research, 5. doi:10.12688/wellcomeopenres.15842.3 \\(t_{20}\\) method follows formula defined section 2.2.5 supplementary material : Lloyd-Smith JO, Schreiber SJ, Kopp PE, Getz WM. Superspreading effect individual variation disease emergence. Nature. 2005 Nov;438(7066):355–9. doi:10.1038/nature04153 original code \\(t_{20}\\) method ongoing work originating https://github.com/dcadam/kt : Adam D, Gostic K, Tsang T, Wu P, Lim WW, Yeung , et al. Time-varying transmission heterogeneity SARS COVID-19 Hong Kong. 2022. doi:10.21203/rs.3.rs-1407962/v1","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/proportion_transmission.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Estimate what proportion of cases cause a certain proportion of transmission — proportion_transmission","text":"","code":"# example of single values of R and k percent_transmission <- 0.8 # 80% of transmission R <- 2 k <- 0.5 proportion_transmission( R = R, k = k, percent_transmission = percent_transmission ) #> R k prop_80 #> 1 2 0.5 26.4% # example with multiple values of k k <- c(0.1, 0.2, 0.3, 0.4, 0.5, 1) proportion_transmission( R = R, k = k, percent_transmission = percent_transmission ) #> R k prop_80 #> 1 2 0.1 9.21% #> 2 2 0.2 15.6% #> 3 2 0.3 20.3% #> 4 2 0.4 23.8% #> 5 2 0.5 26.4% #> 6 2 1.0 35.6% # example with vectors of R and k R <- c(1, 2, 3) proportion_transmission( R = R, k = k, percent_transmission = percent_transmission ) #> R k prop_80 #> 1 1 0.1 8.69% #> 2 2 0.1 9.21% #> 3 3 0.1 9.39% #> 4 1 0.2 14.3% #> 5 2 0.2 15.6% #> 6 3 0.2 16% #> 7 1 0.3 18.2% #> 8 2 0.3 20.3% #> 9 3 0.3 21% #> 10 1 0.4 20.8% #> 11 2 0.4 23.8% #> 12 3 0.4 25% #> 13 1 0.5 22.6% #> 14 2 0.5 26.4% #> 15 3 0.5 28% #> 16 1 1.0 30% #> 17 2 1.0 35.6% #> 18 3 1.0 37.8%"},{"path":"https://epiverse-trace.github.io/superspreading/reference/superspreading-package.html","id":null,"dir":"Reference","previous_headings":"","what":"superspreading: Estimate Individual-Level Variation in Transmission — superspreading-package","title":"superspreading: Estimate Individual-Level Variation in Transmission — superspreading-package","text":"Implements functions estimate individual-level variation transmission.","code":""},{"path":[]},{"path":"https://epiverse-trace.github.io/superspreading/reference/superspreading-package.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"superspreading: Estimate Individual-Level Variation in Transmission — superspreading-package","text":"Maintainer: Joshua W. Lambert joshua.lambert@lshtm.ac.uk (ORCID) [copyright holder] Authors: Adam Kucharski adam.kucharski@lshtm.ac.uk (ORCID) [copyright holder] Dillon C. Adam dcadam@hku.hk (ORCID) contributors: Sebastian Funk sebastian.funk@lshtm.ac.uk (ORCID) (.chain_sim uses code bpmodels::chain_sim) [contributor, copyright holder] Pratik Gupte pratik.gupte@lshtm.ac.uk (ORCID) [reviewer] Hugo Gruson hugo@data.org (ORCID) [reviewer] James M. Azam james.azam@lshtm.ac.uk (ORCID) [reviewer, contributor]","code":""},{"path":[]},{"path":"https://epiverse-trace.github.io/superspreading/news/index.html","id":"superspreading-020","dir":"Changelog","previous_headings":"","what":"superspreading 0.2.0","title":"superspreading 0.2.0","text":"Second minor release superspreading. release enhances functions added v0.1.0 adds two new exported functions, two new vignettes.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/news/index.html","id":"new-features-0-2-0","dir":"Changelog","previous_headings":"","what":"New features","title":"superspreading 0.2.0","text":"new function (calc_network_R()) estimate reproduction number heterogeneous networks vignette outlining use cases function existing epidemiological literature added (#71). probability_epidemic() probability_extinct() now individual-level population-level control joint framework (#70). proportion_*() functions can now return proportion columns output numeric new argument format_prop set FALSE (#72). new design principles vignette document package development added (#68). Added helper function (ic_tbl()) improve model comparison tables (#65). probability_*() functions now accept dynamic dots ({rlang} added dependency) (#82).","code":""},{"path":"https://epiverse-trace.github.io/superspreading/news/index.html","id":"breaking-changes-0-2-0","dir":"Changelog","previous_headings":"","what":"Breaking changes","title":"superspreading 0.2.0","text":"ind_control pop_control arguments replace control control_type arguments probability_contain(); argument default num_init_infect removed (#70). Changed epidist argument offspring_dist follow Epiverse style (affects several functions) (#64). Argument proportion_transmission() renamed sim simulate (#81).","code":""},{"path":"https://epiverse-trace.github.io/superspreading/news/index.html","id":"minor-changes-0-2-0","dir":"Changelog","previous_headings":"","what":"Minor changes","title":"superspreading 0.2.0","text":"New package hex logo (#73). Updated continuous integration package infrastructure (#67). Improved function documentation (#63). Optimisation now uses optim() default (#82). Testing suite now uses snapshot testing regression tests (#84).","code":""},{"path":"https://epiverse-trace.github.io/superspreading/news/index.html","id":"bug-fixes-0-2-0","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"superspreading 0.2.0","text":"None {superspreading} functions. Update {epiparameter} use vignette tests (#62).","code":""},{"path":"https://epiverse-trace.github.io/superspreading/news/index.html","id":"deprecated-and-defunct-0-2-0","dir":"Changelog","previous_headings":"","what":"Deprecated and defunct","title":"superspreading 0.2.0","text":"None","code":""},{"path":"https://epiverse-trace.github.io/superspreading/news/index.html","id":"superspreading-010","dir":"Changelog","previous_headings":"","what":"superspreading 0.1.0","title":"superspreading 0.1.0","text":"Initial release superspreading, R package estimate individual-level variation disease transmission provide summary metrics superspreading events.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/news/index.html","id":"new-features-0-1-0","dir":"Changelog","previous_headings":"","what":"New features","title":"superspreading 0.1.0","text":"Offspring distributions, available base R, fit transmission data. Functions calculate probability infectious disease cause epidemic, go extinct contained. Summary metric functions calculate proportion cases cause certain proportion secondary transmission, well proportion cases within clusters certain size. Three vignettes, including: introduction package, estimating individual-level transmission data, effect superspreading epidemic risk. Unit tests documentation files. Continuous integration workflows R package checks, rendering README.md, calculating test coverage, deploying pkgdown website.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/news/index.html","id":"breaking-changes-0-1-0","dir":"Changelog","previous_headings":"","what":"Breaking changes","title":"superspreading 0.1.0","text":"None","code":""},{"path":"https://epiverse-trace.github.io/superspreading/news/index.html","id":"bug-fixes-0-1-0","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"superspreading 0.1.0","text":"None","code":""},{"path":"https://epiverse-trace.github.io/superspreading/news/index.html","id":"deprecated-and-defunct-0-1-0","dir":"Changelog","previous_headings":"","what":"Deprecated and defunct","title":"superspreading 0.1.0","text":"None","code":""}]
+[{"path":"https://epiverse-trace.github.io/superspreading/LICENSE.html","id":null,"dir":"","previous_headings":"","what":"MIT License","title":"MIT License","text":"Copyright (c) 2022 superspreading authors Permission hereby granted, free charge, person obtaining copy software associated documentation files (“Software”), deal Software without restriction, including without limitation rights use, copy, modify, merge, publish, distribute, sublicense, /sell copies Software, permit persons Software furnished , subject following conditions: copyright notice permission notice shall included copies substantial portions Software. SOFTWARE PROVIDED “”, WITHOUT WARRANTY KIND, EXPRESS IMPLIED, INCLUDING LIMITED WARRANTIES MERCHANTABILITY, FITNESS PARTICULAR PURPOSE NONINFRINGEMENT. EVENT SHALL AUTHORS COPYRIGHT HOLDERS LIABLE CLAIM, DAMAGES LIABILITY, WHETHER ACTION CONTRACT, TORT OTHERWISE, ARISING , CONNECTION SOFTWARE USE DEALINGS SOFTWARE.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/articles/design-principles.html","id":"scope","dir":"Articles","previous_headings":"","what":"Scope","title":"Design Principles for {superspreading}","text":"{superspreading} package aims provide range summary metrics characterise individual-level variation disease transmission impact growth decline epidemic. include calculating probability outbreak becomes epidemic (probability_epidemic()), conversely goes extinct (probability_extinct()), probability outbreak can contained (probability_contain()), proportion cases cluster given size (proportion_cluster_size()), proportion cases cause proportion transmission (proportion_transmission()). aspect package provide probability density functions cumulative distribution functions compute likelihood distribution models estimate heterogeneity individual-level disease transmission available R (.e. base R). present include two models: Poisson-lognormal (dpoislnorm() & ppoislnorm()) Poisson-Weibull (dpoisweibull() & ppoisweibull()) distributions. package implements branching process simulation based bpmodels::chain_sim() enable numerical calculation probability containment within outbreak time outbreak duration threshold. future function removed favour using package implementing branching process models dependency. package mostly focused analytical functions derived branching process models. package provides functions calculate variation individual-level transmission provide functions inference, currently relies {fitdistrplus} fitting models.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/articles/design-principles.html","id":"output","dir":"Articles","previous_headings":"","what":"Output","title":"Design Principles for {superspreading}","text":"Functions name probability_*() return single numeric. Functions name proportion_*() return many rows combinations input values (see expand.grid()). consistency simple well-known data structure makes easy users apply functions different scenarios. distribution functions return vector numerics equal length input vector. behaviour base R distribution functions.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/articles/design-principles.html","id":"design-decisions","dir":"Articles","previous_headings":"","what":"Design decisions","title":"Design Principles for {superspreading}","text":"proportion_*() functions return proportion column(s) containing character strings, formatted percentage sign (%) default. reasoned {superspreading} likely used either stand-alone package, terminus epidemiological analysis pipeline, thus outputs {superspreading} functions passed functions. instances proportions need passed another calculation plotting purposes format_prop argument can switched FALSE numeric column proportions returned. distribution functions vectorised (.e. wrapped Vectorize()). enables used identically base R distribution functions. Native interoperability objects, {epiparameter} package enabled probability_*() proportion_*() via offspring_dist argument. allows user pass single object parameters required {superspreading} function extracted, available within object function returns informative error. offspring_dist argument ... ensure users specify argument full accidentally provide data argument. Internal functions dot (.) prefix, exported functions .","code":""},{"path":"https://epiverse-trace.github.io/superspreading/articles/design-principles.html","id":"dependencies","dir":"Articles","previous_headings":"","what":"Dependencies","title":"Design Principles for {superspreading}","text":"aim restrict number dependencies minimal required set ease maintenance. current hard dependencies : {stats} {checkmate} {stats} distributed R language viewed lightweight dependency, already installed user’s machine R. {checkmate} input checking package widely used across Epiverse-TRACE packages. Suggested dependencies (including package documentation ({knitr}, {rmarkdown}), testing ({spelling} {testthat}), plotting ({ggplot2})) : {epiparameter}, used easily access epidemiological parameters package’s library, {fitdistrplus}, used model fitting methods.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/articles/design-principles.html","id":"contribute","dir":"Articles","previous_headings":"","what":"Contribute","title":"Design Principles for {superspreading}","text":"special requirements contributing {superspreading}, please follow package contributing guide.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/articles/epidemic_risk.html","id":"superspreading-in-decision-making","dir":"Articles","previous_headings":"","what":"Superspreading in decision making","title":"Epidemic Risk","text":"One first tasks outbreak establish whether estimates individual-level transmission variability reported, either outbreak previous outbreak pathogen. Alternatively, outbreak novel pathogen, parameters similar pathogens can searched . accomplished another Epiverse-TRACE R package: {epiparameter}. package contains library epidemiological parameters included offspring distribution parameter estimates uncertainty obtained published literature. aids collation establishes baseline understanding transmission. Similar collation transmission clusters COVID-19. Equipped parameter estimates, metrics provide intuitive understanding transmission patterns can tabulated. example proportion transmission events given cluster size can calculated using {superspreading} function proportion_cluster_size(). calculates proportion new cases originated within transmission event given size. words, proportion transmission events part secondary case clusters (.e. primary case) least, example, five cases. calculation useful inform backwards contact tracing efforts. example look clusters least five, ten twenty-five secondary cases, different numbers initial infections two reproduction numbers see affects cluster sizes. results show level heterogeneity individual-level transmission increases, larger percentage cases come larger cluster sizes, large clusters can produced RR higher even low levels transmission variation. indicates whether preventing gatherings certain size can reduce epidemic preventing potential superspreading events. data settings transmission known, priority can given restricting particular types gatherings effectively bring reproduction number.","code":"# For R = 0.8 proportion_cluster_size( R = 0.8, k = seq(0.1, 1, 0.1), cluster_size = c(5, 10, 25) ) #> R k prop_5 prop_10 prop_25 #> 1 0.8 0.1 66.8% 38.7% 7.36% #> 2 0.8 0.2 48.6% 18% 0.786% #> 3 0.8 0.3 37.7% 9.37% 0.197% #> 4 0.8 0.4 30.3% 5.24% 0.0325% #> 5 0.8 0.5 24.5% 3.07% 0% #> 6 0.8 0.6 21.2% 1.68% 0% #> 7 0.8 0.7 18.2% 1.11% 0% #> 8 0.8 0.8 16% 0.925% 0% #> 9 0.8 0.9 14.5% 0.6% 0% #> 10 0.8 1.0 12.7% 0.445% 0% # For R = 3 proportion_cluster_size( R = 3, k = seq(0.1, 1, 0.1), cluster_size = c(5, 10, 25) ) #> R k prop_5 prop_10 prop_25 #> 1 3 0.1 90.3% 78.4% 50.5% #> 2 3 0.2 84.1% 64.8% 27.1% #> 3 3 0.3 79.5% 55.2% 15.8% #> 4 3 0.4 75.9% 47.6% 9.35% #> 5 3 0.5 73.1% 42.1% 6.09% #> 6 3 0.6 70.5% 36.8% 3.57% #> 7 3 0.7 68.2% 32.7% 2.04% #> 8 3 0.8 66.3% 29.6% 1.63% #> 9 3 0.9 64.7% 26.7% 0.95% #> 10 3 1.0 63.1% 23.9% 0.695%"},{"path":"https://epiverse-trace.github.io/superspreading/articles/epidemic_risk.html","id":"controls-on-transmission","dir":"Articles","previous_headings":"","what":"Controls on transmission","title":"Epidemic Risk","text":"work identifying prevalence overdispersion individual-level transmission, Lloyd-Smith et al. (2005) also showed effect control measures probability containment. defined containment size transmission chain reaching 100 cases. assumed implementation control measures individual population level. {superspreading} provides probability_contain() calculate probability outbreak go extinct reaching threshold size. probability outbreak contained (.e. exceed 100 cases) variety population-level control measures. probability containment calculated using probability_contain(). plot reproduced Lloyd-Smith et al. (2005) figure 3C.","code":"contain_params <- expand.grid( R = 3, k = c(0.1, 0.5, 1, Inf), num_init_infect = 1, control = seq(0, 1, 0.05) ) prob_contain <- apply(contain_params, 1, function(x) { probability_contain( R = x[[\"R\"]], k = x[[\"k\"]], num_init_infect = x[[\"num_init_infect\"]], pop_control = x[[\"control\"]] ) }) contain_params <- cbind(contain_params, prob_contain) # plot probability of epidemic across introductions for multiple k ggplot(data = contain_params) + geom_point( mapping = aes( x = control, y = prob_contain, colour = factor(k) ) ) + scale_y_continuous( name = \"Probability of containment\", limits = c(0, 1) ) + scale_x_continuous(name = \"Control measures (*c*)\", n.breaks = 6) + labs(colour = \"Dispersion (*k*)\") + scale_colour_viridis_d() + theme_bw() + theme( axis.title.x = element_markdown(), legend.title = element_markdown() )"},{"path":[]},{"path":"https://epiverse-trace.github.io/superspreading/articles/estimate_individual_level_transmission.html","id":"transmission-data","dir":"Articles","previous_headings":"","what":"Transmission data","title":"Estimate individual-level transmission","text":"example use transmission chain data Faye et al. (2015) Ebola virus disease outbreak West Africa, period February August 2014. Specifically, data reconstructs pathway Ebola transmission Conakry, Guinea. data used Althaus (2015) show Ebola outbreak Conakry displayed signatures overdispersion (.e. superspreading events), Kucharski et al. (2016) determine effectiveness ring- mass-vaccination campaigns ongoing Ebola outbreaks. best performing model, AIC BIC comparison, negative binomial. AIC BIC model fitting metrics (information criterion) determine model best fits data penalising model complexity prevent overfitting allows comparison models different number parameters. case Poisson Geometric models single parameter, whereas Negative binomial two parameters. parameter negative binomial show overdispersion (size dispersion parameter kk, mu mean, RR) transmission thus EVD transmission chain data shows superspreading events possible realisation EVD transmission dynamics. values match reported Althaus (2015) reproduce figure 1 paper display tail distribution superspreading events can possible. Number secondary cases empirical data (bar plot) density negative binomial maximum likelihood estimates fit empirical data (points line). plot reproduced Althaus (2015) figure 1. Next partitioned data index cases secondary cases following Kucharski et al. (2016). fit negative binomial model index non-index case transmission events.","code":"# total number of cases (i.e. individuals in transmission chain) n <- 152 # number of secondary cases for all cases all_cases_transmission <- c( 1, 2, 2, 5, 14, 1, 4, 4, 1, 3, 3, 8, 2, 1, 1, 4, 9, 9, 1, 1, 17, 2, 1, 1, 1, 4, 3, 3, 4, 2, 5, 1, 2, 2, 1, 9, 1, 3, 1, 2, 1, 1, 2 ) # add zeros for each cases that did not cause a secondary case # (i.e. cases that did not transmit) all_cases <- c( all_cases_transmission, rep(0, n - length(all_cases_transmission)) ) # fit a standard set of offspring distribution models: # - Poisson # - Geometric # - Negative Binomial pois_fit <- fitdist(data = all_cases, distr = \"pois\") geom_fit <- fitdist(data = all_cases, distr = \"geom\") nbinom_fit <- fitdist(data = all_cases, distr = \"nbinom\") model_tbl <- ic_tbl(pois_fit, geom_fit, nbinom_fit) col.names <- gsub( pattern = \"^Delta\", replacement = \"$\\\\\\\\Delta$\", x = colnames(model_tbl) ) col.names <- gsub(pattern = \"^w\", replacement = \"$w$\", x = col.names) knitr::kable(model_tbl, col.names = col.names, row.names = FALSE, digits = 1) nbinom_fit$estimate #> size mu #> 0.1814260 0.9537995 # tally cases tally <- table(all_cases) # pad with zeros when number of cases not in tally num_cases <- rep(0, 21) names(num_cases) <- as.character(seq(0, 20, 1)) num_cases[names(tally)] <- tally # convert cases to proportional of total cases to plot on the same scale as # the density prop_num_cases <- num_cases / sum(num_cases) # create data frame with proportion of cases, density and number of secondary # cases nbinom_data <- data.frame( x = seq(0, 20, 1), prop_num_cases = prop_num_cases, density = dnbinom( x = seq(0, 20, 1), size = nbinom_fit$estimate[[\"size\"]], mu = nbinom_fit$estimate[[\"mu\"]] ) ) # make plot ggplot(data = nbinom_data) + geom_col( mapping = aes(x = x, y = prop_num_cases), fill = \"cyan3\", colour = \"black\" ) + geom_point( mapping = aes(x = x, y = density), colour = \"#f58231\", size = 2 ) + geom_line( mapping = aes(x = x, y = density), colour = \"#f58231\" ) + scale_x_continuous(name = \"Number of secondary cases\") + scale_y_continuous(name = \"Frequency\") + theme_bw() index_case_transmission <- c(2, 17, 5, 1, 8, 2, 14) 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\" ) param_index #> Fitting of the distribution ' nbinom ' by maximum likelihood #> Parameters: #> estimate Std. Error #> size 1.596646 1.025029 #> mu 7.000771 2.320850 param_non_index <- fitdist( data = non_index_cases, distr = \"nbinom\" ) param_non_index #> Fitting of the distribution ' nbinom ' by maximum likelihood #> Parameters: #> estimate Std. Error #> size 0.1937490 0.05005421 #> mu 0.6619608 0.14197451"},{"path":"https://epiverse-trace.github.io/superspreading/articles/estimate_individual_level_transmission.html","id":"superspreading-using-alternative-distributions","dir":"Articles","previous_headings":"","what":"Superspreading using alternative distributions","title":"Estimate individual-level transmission","text":"Advanced options section vignette discusses alternative transmission models quantify overdispersion may considered advanced comparison example. Research subsequent Lloyd-Smith et al. (2005) shown contact data infectious disease outbreaks often shows signatures overdispersion can therefore cause superspreading events. However, overdispersion can modelled distributions negative binomial. Kremer et al. (2021) showed SARS-CoV-2 superspreading may better modelled Poisson mixture distribution (Poisson compound distribution). Four Poisson mixture distribution applied: Poisson-Gamma, Poisson-Lognormal, Poisson-Weibull, Poisson-Generalised-Gamma; finding Poisson-lognormal Poisson-Weibull fit best three data sets. Poisson-Gamma distribution negative binomial distribution. Hereafter refer negative binomial. R density functions cumulative distribution functions poisson (dpois() ppois()), geometric (dgeom() pgeom()) negative binomial (dnbinom() pnbinom()) distributions, supply Poisson compound distributions. {superspreading} R package supply density cumulative distribution functions Poisson-lognormal (dpoislnorm() ppoislnorm()) Poisson-Weibull (dpoisweibull() ppoisweibull()). functions can used {fitdistrplus}, shown distributions . negative binomial still best performing fitting model, even addition Poisson-lognormal Poisson-Weibull models. Although second best model, Poisson-Weibull, performs similarly well negative binomial (Δ\\DeltaAIC < 2 & Δ\\DeltaBIC < 2). plot density distribution given maximum likelihood estimates inspect differences two distributions. Number secondary cases empirical data (bar plot) density negative binomial (orange) poisson-Weibull (pink) maximum likelihood estimates fit empirical data (points line). fit model similar, expected close AIC BIC (models numbers free parameters). Poisson-Weibull compound distribution can adequately capture overdispersion EVD transmission data. noticeable difference models fitting number cases caused single secondary cases. negative binomial matches empirical data, whereas Poisson-Weibull slightly overestimates number. Overall, {superspreading} {fitdistrplus} (another fitting package choice) can used estimate understand individual-level transmission dynamics transmission chain data available.","code":"# fit an expanded set of offspring distribution models: # - Poisson # - Geometric # - Negative Binomial # - Poisson-lognormal compound # - Poisson-Weibull compound pois_fit <- fitdist(data = all_cases, distr = \"pois\") geom_fit <- fitdist(data = all_cases, distr = \"geom\") nbinom_fit <- fitdist(data = all_cases, distr = \"nbinom\") poislnorm_fit <- fitdist( data = all_cases, distr = \"poislnorm\", start = list(meanlog = 1, sdlog = 1) ) poisweibull_fit <- fitdist( data = all_cases, distr = \"poisweibull\", start = list(shape = 1, scale = 1) ) model_tbl <- ic_tbl( pois_fit, geom_fit, nbinom_fit, poislnorm_fit, poisweibull_fit ) col.names <- gsub( pattern = \"^Delta\", replacement = \"$\\\\\\\\Delta$\", x = colnames(model_tbl) ) col.names <- gsub(pattern = \"^w\", replacement = \"$w$\", x = col.names) knitr::kable(model_tbl, col.names = col.names, row.names = FALSE, digits = 1) # create data frame with proportion of cases, density of each distribution dist_compare_data <- data.frame( x = seq(0, 20, 1), prop_num_cases = c(prop_num_cases, rep(0, 21)), dens = c( dnbinom( x = seq(0, 20, 1), size = nbinom_fit$estimate[[\"size\"]], mu = nbinom_fit$estimate[[\"mu\"]] ), poisweibull_density = dpoisweibull( x = seq(0, 20, 1), shape = poisweibull_fit$estimate[[\"shape\"]], scale = poisweibull_fit$estimate[[\"scale\"]] ) ), dist = c(rep(\"Negative Binomial\", 21), rep(\"Poisson-Weibull\", 21)) ) # make plot ggplot(data = dist_compare_data) + geom_col( mapping = aes(x = x, y = prop_num_cases), fill = \"cyan3\", colour = \"black\" ) + geom_point( mapping = aes( x = x, y = dens, colour = dist ), size = 2 ) + geom_line(mapping = aes(x = x, y = dens, colour = dist)) + scale_x_continuous(name = \"Number of secondary cases\") + scale_y_continuous(name = \"Frequency\") + scale_colour_manual( name = \"Distribution\", values = c(\"#f58231\", \"#ffe119\") ) + theme_bw() + theme(legend.position = \"top\")"},{"path":[]},{"path":[]},{"path":"https://epiverse-trace.github.io/superspreading/articles/proportion_transmission.html","id":"definitions","dir":"Articles","previous_headings":"","what":"Definitions","title":"Methods for calculating the proportion of transmission","text":"formula p80p_{80} method stated Endo et al. (2020) : 1−p80=∫0XNB(⌊x⌋;k,(k(R0)+k)dx 1 - p_{80} = \\int^{X}_{0} \\text{NB} ( \\lfloor x \\rfloor; k, \\left( \\frac{k}{(R_0) + k} \\right) dx XX satisfies 1−0.8=1R0∫0X⌊x⌋NB(⌊x⌋;k,kR0+k)dx 1 - 0.8 = \\frac{1}{R_0} \\int^{X}_{0} \\lfloor x \\rfloor \\text{NB} \\left( \\lfloor x \\rfloor; k, \\frac{k}{R_0 + k} \\right) dx Additionally, Endo et al. (2020) showed : 1R0∫0X⌊x⌋NB(⌊x⌋;k,kR0+k)dx=∫0X−1NB(⌊x⌋;k+1,kR0+k) \\frac{1}{R_0} \\int^{X}_{0} \\lfloor x \\rfloor \\text{NB} \\left( \\lfloor x \\rfloor; k, \\frac{k}{R_0 + k} \\right) dx = \\int^{X-1}_{0} \\text{NB} \\left( \\lfloor x \\rfloor; k + 1, \\frac{k}{R_0 + k} \\right) t20t_{20} method calculates, stated Lloyd-Smith et al. (2005): “expected proportion transmission due infectious 20% cases, t20t_{20}”, given t20=1−Ftrans(x20)t_{20} = 1 - F_{trans}(x_{20}), FtransF_{trans} defined : Ftrans(x)=1R0∫0xufv(u)du F_{trans}(x) = \\frac{1}{R_0} \\int^{x}_{0} u f_v (u) du fν(x)f_\\nu(x) probability density function (pdf) gamma distribution individual reproduction number ν\\nu. methods proportion transmission can modified using percent_transmission argument proportion_transmission() fixed 80 20, respectively, p80p_{80} t20t_{20}. two methods calculating p80p_{80} method, analytically given Endo et al. (2020), numerically sampling negative binomial distribution (proportion_transmission(..., simulate = TRUE). purpose vignette compare methods term analytical calculation p80p_{80}, numerical calculation p80simp_{80}^{sim}. Now p80p_{80} t20t_{20} methods defined ’ll explore functionality , characteristics compare , making note unexpected behaviour watch . First load {superspreading}, {ggplot2}, {purrr} {dplyr} R packages.","code":"library(superspreading) library(ggplot2) library(purrr) library(dplyr) #> #> Attaching package: 'dplyr' #> The following objects are masked from 'package:stats': #> #> filter, lag #> The following objects are masked from 'package:base': #> #> intersect, setdiff, setequal, union"},{"path":"https://epiverse-trace.github.io/superspreading/articles/proportion_transmission.html","id":"exploring-each-method","dir":"Articles","previous_headings":"","what":"Exploring each method","title":"Methods for calculating the proportion of transmission","text":"show proportion transmission using methods can load estimates RR kk estimated Lloyd-Smith et al. (2005), stored library epidemiological parameters {epiparameter} R package, interoperability {epiparameter} {superspreading} directly supply parameters offspring distributions ( objects) offspring_dist argument proportion_transmission(). create table estimates mean (RR) dispersion (kk) disease Lloyd-Smith et al. (2005). Using parameter estimates negative binomial offspring distribution disease can append calculated proportion transmission caused infectious 20% cases, using t20t_{20} method, calculated proportion transmission causing 80% onward transmission, using p80p_{80} method. can seen table offspring distribution smaller dispersion (kk) parameter proportion cases produced infectious 20% cases high, proportion cases produce 80% transmission low. estimates SARS demonstrate point. metrics lead conclusion disease transmission dynamics 2003 SARS outbreak Singapore heterogeneous superspreading important aspect outbreak. variability individual-level transmission comes modelling individual reproduction number, ν\\nu gamma distribution, instead assuming individual-level reproduction number equal individuals, result Poisson offspring distribution (see Lloyd-Smith et al. (2005) Supplementary Material information). visualise inherent variability resulting gamma-distributed reproduction number compares assumption homogeneous population can plot expected proportion transmission proportion infectious cases. need write couple custom functions. can now reproduce Figure 1b Lloyd-Smith et al. (2005) using offspring distribution parameters obtained . plot shows variability transmission owing gamma-distributed individual reproduction number (ν\\nu). take slice plot proportion infectious cases equals 0.2 (shown dashed line) can calculate proportion transmission caused infectious 20% cases using proportion_tranmission(..., method = \"t_20\") function. plot replicates Figure 1c Lloyd-Smith et al. (2005). shows different diseases different proportion transmission infectious 20% owing varying degrees overdispersion (kk). plot uses RR 2, however, one characteristic t20t_{20} method different values RR influence proportion transmission, plot look identical value RR. shown equation defining t20t_{20} method integral divided R0R_0 fν(u)f_{\\nu}(u) control proportion transmission. case p80p_{80}, changes RR kk influence proportion transmission. One thing mentioned interpretation p80p_{80} t20t_{20} methods interchangeable, additionally, t80t_{80} p20p_{20} equal. Stated differently, p80p_{80} method calculate proportion transmission cause 20% cases, t20t_{20} method calculate proportion transmission caused infectious 80% equivalent. also case 1−p80≠t201 - p_{80} \\neq t_{20}, thus 1−t20≠p801 - t_{20} \\neq p_{80}. vary RR kk show setting p80p_{80} method percent_transmission = 0.2, t20t_{20} method percent_transmission = 0.8 two interchangeably interpreted outlined box . show 1−p80≠t201 - p_{80} \\neq t_{20} 1−t20≠p801 - t_{20} \\neq p_{80}. t20t_{20} method allows true homogeneity k→∞k \\rightarrow \\infty (t20=20%t_{20} = 20\\%), whereas p80p_{80} method allow true homogeneity (p80≠80%p_{80} \\neq 80\\%).","code":"library(epiparameter) offspring_dists <- epiparameter_db( epi_name = \"offspring distribution\" ) #> Returning 10 results that match the criteria (10 are parameterised). #> Use subset to filter by entry variables or single_epiparameter to return a single entry. #> To retrieve the citation for each use the 'get_citation' function diseases <- vapply(offspring_dists, `[[`, FUN.VALUE = character(1), \"disease\") offspring_dists <- offspring_dists[!duplicated(diseases)] diseases <- diseases[!duplicated(diseases)] offspring_dist_params <- vapply( offspring_dists, get_parameters, FUN.VALUE = numeric(2) ) offspring_dist_params <- data.frame( disease = diseases, t(offspring_dist_params) ) offspring_dist_params #> disease mean dispersion #> 1 SARS 1.63 0.16 #> 2 Smallpox 3.19 0.37 #> 3 Mpox 0.32 0.58 #> 4 Pneumonic Plague 1.32 1.37 #> 5 Hantavirus Pulmonary Syndrome 0.70 1.66 #> 6 Ebola Virus Disease 1.50 5.10 offspring_dist_params$t20 <- do.call( rbind, apply( offspring_dist_params, MARGIN = 1, function(x) { proportion_transmission( R = as.numeric(x[2]), k = as.numeric(x[3]), percent_transmission = 0.2, method = \"t_20\", format_prop = FALSE ) } ) )[, 3] offspring_dist_params$p80 <- do.call( rbind, apply( offspring_dist_params, MARGIN = 1, function(x) { proportion_transmission( R = as.numeric(x[2]), k = as.numeric(x[3]), percent_transmission = 0.8, method = \"p_80\", format_prop = FALSE ) } ) )[, 3] offspring_dist_params #> disease mean dispersion t20 p80 #> 1 SARS 1.63 0.16 0.8825175 0.1300095 #> 2 Smallpox 3.19 0.37 0.7125723 0.2405781 #> 3 Mpox 0.32 0.58 0.6201376 0.1609538 #> 4 Pneumonic Plague 1.32 1.37 0.4737949 0.3392229 #> 5 Hantavirus Pulmonary Syndrome 0.70 1.66 0.4476538 0.3023708 #> 6 Ebola Virus Disease 1.50 5.10 0.3363023 0.4315065 # nolint start for `:::` get_infectious_curve <- function(R, k) { # upper limit of x when y = 0 upper_u <- superspreading:::solve_for_u(prop = 0, R = R, k = k) upper_u <- round(upper_u) u_seq <- superspreading:::lseq(from = 1e-5, to = upper_u, length.out = 500) res <- lapply(u_seq, function(upper) { integrate( function(u) u * superspreading:::fvx(x = u, R, k), lower = 0, upper = upper )$value / R }) expected_v_more_than_x <- 1 - unlist(res) proportion_more_than_x <- 1 - superspreading:::pgammaRk(u_seq, R = R, k = k) data.frame( exp_t = expected_v_more_than_x, prop_i = proportion_more_than_x ) } # nolint end infect_curve <- map(offspring_dist_params %>% group_split(disease), function(x) { get_infectious_curve(R = x$mean, k = x$dispersion) %>% mutate( disease = x$disease, R = x$mean, k = x$dispersion ) }) infect_curve <- do.call(rbind, infect_curve) ggplot( data = infect_curve, aes(x = prop_i, y = exp_t, colour = disease) ) + geom_line() + geom_abline(slope = 1) + geom_vline(xintercept = 0.2, linetype = 2, alpha = 0.2) + scale_x_continuous(breaks = seq(0, 1, by = 0.2)) + theme_classic() + theme( aspect.ratio = 1, legend.position = \"right\" ) + annotate( geom = \"text\", angle = 45, size = 2.5, x = 0.5, y = 0.5, vjust = 1.5, label = \"Homogeneous population\" ) + labs( x = \"Proportion of infectious cases (ranked)\", y = \"Expected proportion of transmission\", colour = \"\" ) + coord_cartesian(expand = FALSE) k_seq <- superspreading:::lseq(from = 0.01, to = 100, length.out = 1000) # nolint y <- map_dbl( k_seq, function(x) { proportion_transmission( R = 2, k = x, percent_transmission = 0.2, method = \"t_20\", format_prop = FALSE )[, 3] } ) prop_t20 <- data.frame(k_seq, y) ggplot() + geom_line(data = prop_t20, mapping = aes(x = k_seq, y = y)) + geom_point( data = offspring_dist_params, mapping = aes( x = dispersion, y = t20, fill = disease ), shape = 21, size = 3 ) + geom_hline(yintercept = c(0.2, 0.8), linetype = 2, alpha = 0.2) + theme_classic() + theme( aspect.ratio = 1 ) + scale_y_continuous( name = paste( \"Proportion of transmission expected from\", \"the most infectious 20% of cases\", sep = \" \\n\" ), limits = c(0, 1), breaks = seq(0, 1, by = 0.2) ) + scale_x_log10(name = \"Dispersion parameter\", expand = c(0, 0)) + labs(fill = \"\") # For k = 0.5 proportion_transmission( R = 0.1, k = 0.5, percent_transmission = 0.8, method = \"t_20\" ) #> R k prop_80 #> 1 0.1 0.5 99.6% proportion_transmission( R = 1, k = 0.5, percent_transmission = 0.8, method = \"t_20\" ) #> R k prop_80 #> 1 1 0.5 99.6% proportion_transmission( R = 5, k = 0.5, percent_transmission = 0.8, method = \"t_20\" ) #> R k prop_80 #> 1 5 0.5 99.6% # For k = 2 proportion_transmission( R = 0.1, k = 2, percent_transmission = 0.8, method = \"t_20\" ) #> R k prop_80 #> 1 0.1 2 94.9% proportion_transmission( R = 1, k = 2, percent_transmission = 0.8, method = \"t_20\" ) #> R k prop_80 #> 1 1 2 94.9% proportion_transmission( R = 5, k = 2, percent_transmission = 0.8, method = \"t_20\" ) #> R k prop_80 #> 1 5 2 94.9% # For k = 0.5 proportion_transmission( R = 0.1, k = 0.5, percent_transmission = 0.8, method = \"p_80\" ) #> R k prop_80 #> 1 0.1 0.5 6.71% proportion_transmission( R = 1, k = 0.5, percent_transmission = 0.8, method = \"p_80\" ) #> R k prop_80 #> 1 1 0.5 22.6% proportion_transmission( R = 5, k = 0.5, percent_transmission = 0.8, method = \"p_80\" ) #> R k prop_80 #> 1 5 0.5 29.3% # For k = 2 proportion_transmission( R = 0.1, k = 2, percent_transmission = 0.8, method = \"p_80\" ) #> R k prop_80 #> 1 0.1 2 7.3% proportion_transmission( R = 1, k = 2, percent_transmission = 0.8, method = \"p_80\" ) #> R k prop_80 #> 1 1 2 35.6% proportion_transmission( R = 5, k = 2, percent_transmission = 0.8, method = \"p_80\" ) #> R k prop_80 #> 1 5 2 48.9% # R = 1, k = 0.5 proportion_transmission( R = 1, k = 0.5, percent_transmission = 0.2, method = \"p_80\" ) #> R k prop_20 #> 1 1 0.5 2.45% proportion_transmission( R = 1, k = 0.5, percent_transmission = 0.8, method = \"t_20\" ) #> R k prop_80 #> 1 1 0.5 99.6% # R = 3, k = 2 proportion_transmission( R = 3, k = 2, percent_transmission = 0.2, method = \"p_80\" ) #> R k prop_20 #> 1 3 2 5.86% proportion_transmission( R = 3, k = 2, percent_transmission = 0.8, method = \"t_20\" ) #> R k prop_80 #> 1 3 2 94.9% 1 - proportion_transmission( R = 1, k = 0.5, percent_transmission = 0.8, method = \"p_80\", format_prop = FALSE )[, 3] #> [1] 0.7735753 proportion_transmission( R = 1, k = 0.5, percent_transmission = 0.2, method = \"t_20\" ) #> R k prop_20 #> 1 1 0.5 65% 1 - proportion_transmission( R = 1, k = 0.5, percent_transmission = 0.2, method = \"t_20\", format_prop = FALSE )[, 3] #> [1] 0.3501798 proportion_transmission( R = 1, k = 0.5, percent_transmission = 0.8, method = \"p_80\" ) #> R k prop_80 #> 1 1 0.5 22.6% proportion_transmission( R = 1, k = Inf, percent_transmission = 0.8, method = \"p_80\" ) #> Infinite values of k are being approximated by 1e5 for calculations. #> R k prop_80 #> 1 1 1e+05 43.2% proportion_transmission( R = 1, k = Inf, percent_transmission = 0.8, method = \"t_20\" ) #> Infinite values of k are being approximated by 1e5 for calculations. #> R k prop_80 #> 1 1 1e+05 80.1%"},{"path":"https://epiverse-trace.github.io/superspreading/articles/superspreading.html","id":"definition","dir":"Articles","previous_headings":"","what":"Definition","title":"Getting started with {superspreading}","text":"Superspreading describes individual heterogeneity disease transmission, individuals transmit many infectees infectors infect zero individuals (Lloyd-Smith et al. 2005).","code":""},{"path":"https://epiverse-trace.github.io/superspreading/articles/superspreading.html","id":"probability-of-epidemic","dir":"Articles","previous_headings":"","what":"Probability of epidemic","title":"Getting started with {superspreading}","text":"probability novel disease cause epidemic (.e. sustained transmission population) determined nature diseases’ transmission heterogeneity. variability may intrinsic property disease, product human behaviour social mixing patterns. given value RR, variability high, probability outbreak cause epidemic lower superspreading events rare. Whereas lower variability probability higher individuals closer mean (RR). use RR represent reproduction number (number secondary cases caused typical case). Depending situation, may equivalent basic reproduction number (R0R_0, representing transmission fully susceptible population) effective reproduction number given point time (RtR_t, representing extent transmission time tt). Either can input functions provided {superspreading} probability_epidemic() function {superspreading} can calculate probability. kk dispersion parameter negative binomial distribution controls variability individual-level transmission. code, kk values one represent low heterogeneity (case k→∞k \\rightarrow \\infty poisson distribution), kk decreases, heterogeneity increases. kk equals 1, distribution geometric. Values kk less one indicate overdispersion disease transmission, signature superspreading. value RR increases, causes probability epidemic increase, kk remains . value RR less equal one zero probability causing sustained epidemic. Finally, probability new infection cause large epidemic influenced number initial infections seeding outbreak. define number initial infections.","code":"probability_epidemic(R = 1.5, k = 1, num_init_infect = 1) #> [1] 0.3333333 probability_epidemic(R = 1.5, k = 0.5, num_init_infect = 1) #> [1] 0.2324081 probability_epidemic(R = 1.5, k = 0.1, num_init_infect = 1) #> [1] 0.06765766 probability_epidemic(R = 0.5, k = 1, num_init_infect = 1) #> [1] 0 probability_epidemic(R = 1.0, k = 1, num_init_infect = 1) #> [1] 0 probability_epidemic(R = 1.5, k = 1, num_init_infect = 1) #> [1] 0.3333333 probability_epidemic(R = 5, k = 1, num_init_infect = 1) #> [1] 0.8 probability_epidemic(R = 1.5, k = 1, num_init_infect = 1) #> [1] 0.3333333 probability_epidemic(R = 1.5, k = 1, num_init_infect = 10) #> [1] 0.9826585 probability_epidemic(R = 1.5, k = 1, num_init_infect = 100) #> [1] 1"},{"path":"https://epiverse-trace.github.io/superspreading/articles/superspreading.html","id":"empirical-superspreading","dir":"Articles","previous_headings":"","what":"Empirical superspreading","title":"Getting started with {superspreading}","text":"Given probability_epidemic() possible determine probability epidemic diseases parameters offspring distribution estimated. offspring distribution simply distribution number secondary infections caused primary infection. distribution RR, mean distribution given RR. can use {epiparameter} load offspring distributions multiple diseases evaluate likely cause epidemics. parameters distribution can extracted: example assume initial pool infectors one (num_init_infect = 1) can easily adjusted case evidence larger initial seeding infections, whether animal--human spillover imported cases outside area interest. can see probability epidemic given estimates Lloyd-Smith et al. (2005) greater Ebola SARS. due offspring distribution Ebola larger dispersion (dispersion kk = 5.1), compared SARS, relatively small dispersion (kk = 0.16).","code":"sars <- epiparameter_db( disease = \"SARS\", epi_name = \"offspring distribution\", single_epiparameter = TRUE ) #> Using Lloyd-Smith J, Schreiber S, Kopp P, Getz W (2005). \"Superspreading and #> the effect of individual variation on disease emergence.\" _Nature_. #> doi:10.1038/nature04153 .. #> To retrieve the citation use the 'get_citation' function evd <- epiparameter_db( disease = \"Ebola Virus Disease\", epi_name = \"offspring distribution\", single_epiparameter = TRUE ) #> Using Lloyd-Smith J, Schreiber S, Kopp P, Getz W (2005). \"Superspreading and #> the effect of individual variation on disease emergence.\" _Nature_. #> doi:10.1038/nature04153 .. #> To retrieve the citation use the 'get_citation' function sars_params <- get_parameters(sars) sars_params #> mean dispersion #> 1.63 0.16 evd_params <- get_parameters(evd) evd_params #> mean dispersion #> 1.5 5.1 family(sars) #> [1] \"nbinom\" probability_epidemic( R = sars_params[[\"mean\"]], k = sars_params[[\"dispersion\"]], num_init_infect = 1 ) #> [1] 0.1198705 family(evd) #> [1] \"nbinom\" probability_epidemic( R = evd_params[[\"mean\"]], k = evd_params[[\"dispersion\"]], num_init_infect = 1 ) #> [1] 0.5092324"},{"path":[]},{"path":"https://epiverse-trace.github.io/superspreading/authors.html","id":null,"dir":"","previous_headings":"","what":"Authors","title":"Authors and Citation","text":"Joshua W. Lambert. Author, maintainer, copyright holder. Adam Kucharski. Author, copyright holder. Dillon C. Adam. Author. Sebastian Funk. Contributor, copyright holder. .chain_sim uses code bpmodels::chain_sim Pratik Gupte. Reviewer. Hugo Gruson. Reviewer. James M. Azam. Reviewer, contributor.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/authors.html","id":"citation","dir":"","previous_headings":"","what":"Citation","title":"Authors and Citation","text":"Lambert J, Kucharski , Adam D (2024). superspreading: Estimate Individual-Level Variation Transmission. R package version 0.2.0.9000, https://epiverse-trace.github.io/superspreading/, https://github.com/epiverse-trace/superspreading.","code":"@Manual{, title = {superspreading: Estimate Individual-Level Variation in Transmission}, author = {Joshua W. Lambert and Adam Kucharski and Dillon C. Adam}, year = {2024}, note = {R package version 0.2.0.9000, https://epiverse-trace.github.io/superspreading/}, url = {https://github.com/epiverse-trace/superspreading}, }"},{"path":"https://epiverse-trace.github.io/superspreading/index.html","id":"superspreading-estimate-individual-level-variation-in-transmission-","dir":"","previous_headings":"","what":"Estimate Individual-Level Variation in Transmission","title":"Estimate Individual-Level Variation in Transmission","text":"superspreading R package provides set functions estimate understand individual-level variation transmission infectious diseases data secondary cases. superspreading implements methods outlined Lloyd-Smith et al. (2005), Adam J. Kucharski et al. (2020), Kremer et al. (2021), well additional functions. superspreading developed Centre Mathematical Modelling Infectious Diseases London School Hygiene Tropical Medicine part Epiverse-TRACE.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/index.html","id":"installation","dir":"","previous_headings":"","what":"Installation","title":"Estimate Individual-Level Variation in Transmission","text":"easiest way install development version superspreading GitHub use pak package:","code":"# check whether {pak} is installed if(!require(\"pak\")) install.packages(\"pak\") pak::pak(\"epiverse-trace/superspreading\")"},{"path":"https://epiverse-trace.github.io/superspreading/index.html","id":"quick-start","dir":"","previous_headings":"","what":"Quick start","title":"Estimate Individual-Level Variation in Transmission","text":"","code":"library(superspreading)"},{"path":"https://epiverse-trace.github.io/superspreading/index.html","id":"calculate-the-heterogeneity-of-transmission","dir":"","previous_headings":"Quick start","what":"Calculate the heterogeneity of transmission","title":"Estimate Individual-Level Variation in Transmission","text":"Case study using data early Ebola outbreak Guinea 2014, stratified index non-index cases, Adam J. Kucharski et al. (2016). Data transmission index secondary cases Ebola 2014. Source: Faye et al. (2015) & Althaus (2015). {fitdistrplus} well-developed stable R package provides variety methods fitting distribution models data (Delignette-Muller Dutang 2015). Therefore, used throughout documentation superspreading recommended package wanting fit distribution models, example supplied superspreading (Poisson-lognormal Poisson-Weibull). recommend reading fitdistrplus documentation (specifically ?fitdist) explore full range functionality. example fit negative binomial distribution estimate reproduction number (RR, mean distribution) dispersion (kk, measure variance distribution). parameters estimated via maximum likelihood (default method fitdist()). reproduction number (RR) higher index cases non-index cases, heterogeneity transmission higher non-index cases (.e. kk lower).","code":"# we use {fitdistrplus} to fit the models library(fitdistrplus) #> Loading required package: MASS #> Loading required package: survival # 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"},{"path":"https://epiverse-trace.github.io/superspreading/index.html","id":"calculate-the-probability-of-a-large-epidemic","dir":"","previous_headings":"Quick start","what":"Calculate the probability of a large epidemic","title":"Estimate Individual-Level Variation in Transmission","text":"Given reproduction number (RR) dispersion (kk), probability infectious disease cause epidemic, words probability go extinct, can calculated using probability_epidemic(). use probability_epidemic() parameters estimated section Ebola, assuming three initial infections seeding potential outbreak. probability causing sustained outbreak high index cases, zero non-index cases (.e. disease transmission inevitably cease assuming transmission dynamics change).","code":"# 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 probability_epidemic( R = param_index$estimate[[\"R\"]], k = param_index$estimate[[\"k\"]], num_init_infect = initial_infections ) #> [1] 0.9995741 # Probability of an epidemic using k estimated from non-index cases probability_epidemic( R = param_non_index$estimate[[\"R\"]], k = param_non_index$estimate[[\"k\"]], num_init_infect = initial_infections ) #> [1] 0"},{"path":"https://epiverse-trace.github.io/superspreading/index.html","id":"package-vignettes","dir":"","previous_headings":"","what":"Package vignettes","title":"Estimate Individual-Level Variation in Transmission","text":"details use superspreading can found online documentation package vignettes, “Articles”.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/index.html","id":"visualisation-and-plotting-functionality","dir":"","previous_headings":"Package vignettes","what":"Visualisation and plotting functionality","title":"Estimate Individual-Level Variation in Transmission","text":"superspreading provide plotting functions, instead provide example code chunks package’s vignettes can used templates upon data visualisations can modified. recommend users copy edit examples purposes. (permitted package’s MIT license). default code chunks plotting folded, order unfold see code simply click code button top left plot.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/index.html","id":"help","dir":"","previous_headings":"","what":"Help","title":"Estimate Individual-Level Variation in Transmission","text":"report bug please open issue","code":""},{"path":"https://epiverse-trace.github.io/superspreading/index.html","id":"contribute","dir":"","previous_headings":"","what":"Contribute","title":"Estimate Individual-Level Variation in Transmission","text":"Contributions superspreading welcomed. Please follow package contributing guide.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/index.html","id":"code-of-conduct","dir":"","previous_headings":"","what":"Code of Conduct","title":"Estimate Individual-Level Variation in Transmission","text":"Please note {superspreading} project released Contributor Code Conduct. contributing project, agree abide terms.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/index.html","id":"citing-this-package","dir":"","previous_headings":"","what":"Citing this package","title":"Estimate Individual-Level Variation in Transmission","text":"","code":"citation(\"superspreading\") #> To cite package 'superspreading' in publications use: #> #> Lambert J, Kucharski A, Adam D (2024). _superspreading: Estimate #> Individual-Level Variation in Transmission_. R package version #> 0.2.0.9000, https://epiverse-trace.github.io/superspreading/, #> . #> #> A BibTeX entry for LaTeX users is #> #> @Manual{, #> title = {superspreading: Estimate Individual-Level Variation in Transmission}, #> author = {Joshua W. Lambert and Adam Kucharski and Dillon C. Adam}, #> year = {2024}, #> note = {R package version 0.2.0.9000, #> https://epiverse-trace.github.io/superspreading/}, #> url = {https://github.com/epiverse-trace/superspreading}, #> }"},{"path":"https://epiverse-trace.github.io/superspreading/index.html","id":"related-projects","dir":"","previous_headings":"","what":"Related projects","title":"Estimate Individual-Level Variation in Transmission","text":"project overlap R packages: {epichains} another Epiverse-TRACE R package analyses transmission chain data infer likelihood either size length outbreak cluster, simulate transmission chains. based , now retired, {bpmodels} package. Two main differences superspreading {epichains} : 1) superspreading functions compute metrics characterise outbreaks superspreading events (e.g. probability_epidemic(), probability_extinct(), proportion_cluster_size() & proportion_transmission()); whereas {epichains} functions calculate likelihood transmission chain size length. 2) {epichains} exports functions simulate single-type branching process (simulate_chains() & simulate_chain_stats()). {modelSSE} similar scope superspreading, contains functions infer offspring distribution parameters. exports several infectious disease outbreak datasets (see data(package = \"modelSSE\")). superspreading {modelSSE} export functions calculate proportion transmission using different methods. also imports {Delaporte} package model offspring distribution Delaporte distribution.","code":""},{"path":[]},{"path":"https://epiverse-trace.github.io/superspreading/reference/calc_network_R.html","id":null,"dir":"Reference","previous_headings":"","what":"Calculate the reproduction number (\\(R\\)) for a (heterogeneous) network — calc_network_R","title":"Calculate the reproduction number (\\(R\\)) for a (heterogeneous) network — calc_network_R","text":"calculation reproduction number adjusting heterogeneity number contacts.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/calc_network_R.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Calculate the reproduction number (\\(R\\)) for a (heterogeneous) network — calc_network_R","text":"","code":"calc_network_R( mean_num_contact, sd_num_contact, infect_duration, prob_transmission, age_range )"},{"path":"https://epiverse-trace.github.io/superspreading/reference/calc_network_R.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Calculate the reproduction number (\\(R\\)) for a (heterogeneous) network — calc_network_R","text":"mean_num_contact numeric, mean (average) number new contacts per unit time. sd_num_contact numeric, standard deviation number new contacts per unit time. infect_duration numeric, duration infectiousness. prob_transmission numeric probability transmission per contact, also known \\(\\beta\\). age_range numeric vector two elements, lower upper age limits individuals network.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/calc_network_R.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Calculate the reproduction number (\\(R\\)) for a (heterogeneous) network — calc_network_R","text":"named numeric vector length 2, unadjusted (R) network adjusted (R_net) estimates \\(R\\).","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/calc_network_R.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Calculate the reproduction number (\\(R\\)) for a (heterogeneous) network — calc_network_R","text":"","code":"# example using NATSAL data calc_network_R( mean_num_contact = 14.1, sd_num_contact = 69.6, infect_duration = 1, prob_transmission = 1, age_range = c(16, 74) ) #> R R_net #> 0.2431034 6.1665077"},{"path":"https://epiverse-trace.github.io/superspreading/reference/dot-chain_sim.html","id":null,"dir":"Reference","previous_headings":"","what":"Simulate transmission chains using a stochastic branching process — .chain_sim","title":"Simulate transmission chains using a stochastic branching process — .chain_sim","text":"Code modified bpmodels::chain_sim() function. function chain_sim() function bpmodels reused permission licensed MIT bpmodels. bpmodels CRAN retired.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dot-chain_sim.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Simulate transmission chains using a stochastic branching process — .chain_sim","text":"","code":".chain_sim( n, offspring, stat = c(\"size\", \"length\"), stat_threshold = Inf, generation_time, tf = Inf, ... )"},{"path":"https://epiverse-trace.github.io/superspreading/reference/dot-chain_sim.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Simulate transmission chains using a stochastic branching process — .chain_sim","text":"n Number simulations run. offspring Offspring distribution: character string corresponding R distribution function (e.g., \"pois\" Poisson, rpois() R function generate Poisson random numbers). stat String; Statistic calculate. Can one : \"size\": total number offspring. \"length\": total number ancestors. stat_threshold size length simulation results set Inf. Defaults Inf, resulting results ever set Inf generation_time generation time generator function; name user-defined named anonymous function one argument n, representing number generation times generate. tf End time (generation_time interval given). ... Parameters offspring distribution required R.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dot-chain_sim.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Simulate transmission chains using a stochastic branching process — .chain_sim","text":" columns n (simulation ID), id (unique ID within simulation individual element chain), ancestor (ID ancestor element), generation. time column also appended generation_time interval supplied serial.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dot-chain_sim.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Simulate transmission chains using a stochastic branching process — .chain_sim","text":"Sebastian Funk, James M. Azam, Joshua W. Lambert","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dot-fit.html","id":null,"dir":"Reference","previous_headings":"","what":"Optimise a function using either numerical optimisation or grid search — .fit","title":"Optimise a function using either numerical optimisation or grid search — .fit","text":"Optimise function using either numerical optimisation grid search","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dot-fit.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Optimise a function using either numerical optimisation or grid search — .fit","text":"","code":".fit(func, fit_method = c(\"optim\", \"grid\"), ...)"},{"path":"https://epiverse-trace.github.io/superspreading/reference/dot-fit.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Optimise a function using either numerical optimisation or grid search — .fit","text":"func function. fit_method character string, either \"optim\" \"grid\". ... Named elements replace default optimisation settings either optim() grid search. See details.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dot-fit.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Optimise a function using either numerical optimisation or grid search — .fit","text":"single numeric.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dot-fit.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Optimise a function using either numerical optimisation or grid search — .fit","text":"Arguments passed dots depend whether fit_method set \"optim\" \"grid\". \"optim\", arguments passed optim(), \"grid\", variable arguments lower, upper (lower upper bounds grid search parameter optimised, defaults lower = 0.001 upper = 0.999), \"res\" (resolution grid, default res = 0.001).","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dpoislnorm.html","id":null,"dir":"Reference","previous_headings":"","what":"Density of the poisson-lognormal compound distribution — dpoislnorm","title":"Density of the poisson-lognormal compound distribution — dpoislnorm","text":"Density poisson-lognormal compound distribution","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dpoislnorm.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Density of the poisson-lognormal compound distribution — dpoislnorm","text":"","code":"dpoislnorm(x, meanlog, sdlog)"},{"path":"https://epiverse-trace.github.io/superspreading/reference/dpoislnorm.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Density of the poisson-lognormal compound distribution — dpoislnorm","text":"x number quantile distribution. meanlog number mean distribution log scale. sdlog number standard deviation distribution log scale.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dpoislnorm.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Density of the poisson-lognormal compound distribution — dpoislnorm","text":"numeric vector density poisson-lognormal distribution.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dpoislnorm.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Density of the poisson-lognormal compound distribution — dpoislnorm","text":"function vectorised vector quantiles can input output equal length.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dpoislnorm.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Density of the poisson-lognormal compound distribution — dpoislnorm","text":"","code":"dpoislnorm(x = 10, meanlog = 1, sdlog = 2) #> [1] 0.01626334 dpoislnorm(x = 1:10, meanlog = 1, sdlog = 2) #> [1] 0.14112152 0.08990619 0.06345106 0.04780697 0.03765325 0.03061694 #> [7] 0.02550065 0.02164138 0.01864488 0.01626334"},{"path":"https://epiverse-trace.github.io/superspreading/reference/dpoisweibull.html","id":null,"dir":"Reference","previous_headings":"","what":"Density of the poisson-Weibull compound distribution — dpoisweibull","title":"Density of the poisson-Weibull compound distribution — dpoisweibull","text":"Density poisson-Weibull compound distribution","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dpoisweibull.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Density of the poisson-Weibull compound distribution — dpoisweibull","text":"","code":"dpoisweibull(x, shape, scale)"},{"path":"https://epiverse-trace.github.io/superspreading/reference/dpoisweibull.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Density of the poisson-Weibull compound distribution — dpoisweibull","text":"x number quantile distribution. shape number shape parameter distribution. scale number scale parameter distribution.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dpoisweibull.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Density of the poisson-Weibull compound distribution — dpoisweibull","text":"numeric vector density poisson-Weibull distribution.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dpoisweibull.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Density of the poisson-Weibull compound distribution — dpoisweibull","text":"function vectorised vector quantiles can input output equal length.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/dpoisweibull.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Density of the poisson-Weibull compound distribution — dpoisweibull","text":"","code":"dpoisweibull(x = 10, shape = 1, scale = 2) #> [1] 0.00578051 dpoisweibull(x = 1:10, shape = 1, scale = 2) #> [1] 0.222222222 0.148148148 0.098765432 0.065843621 0.043895748 0.029263832 #> [7] 0.019509221 0.013006147 0.008670765 0.005780510"},{"path":"https://epiverse-trace.github.io/superspreading/reference/gamma.html","id":null,"dir":"Reference","previous_headings":"","what":"Defines the gamma functions in terms of the mean reproductive number (R) and the dispersion parameter (k) — gamma","title":"Defines the gamma functions in terms of the mean reproductive number (R) and the dispersion parameter (k) — gamma","text":"dgammaRk() gamma density function pgammaRk() gamma distribution function fvx() fore gamma probability density function (pdf) describing individual reproductive number \\(\\nu\\) given R0 k","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/gamma.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Defines the gamma functions in terms of the mean reproductive number (R) and the dispersion parameter (k) — gamma","text":"","code":"dgammaRk(x, R, k) pgammaRk(x, R, k) fvx(x, R, k)"},{"path":"https://epiverse-trace.github.io/superspreading/reference/gamma.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Defines the gamma functions in terms of the mean reproductive number (R) and the dispersion parameter (k) — gamma","text":"R number specifying R parameter (.e. average secondary cases per infectious individual). k number specifying k parameter (.e. overdispersion offspring distribution fitted negative binomial).","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/ic_tbl.html","id":null,"dir":"Reference","previous_headings":"","what":"Helper function to create a model comparison table — ic_tbl","title":"Helper function to create a model comparison table — ic_tbl","text":"helper function creating model comparison primarily use superspreading vignettes. designed specifically handling fitdistrplus::fitdist() output generalised function. See bbmle::ICtab() general use function create information criteria tables.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/ic_tbl.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Helper function to create a model comparison table — ic_tbl","text":"","code":"ic_tbl(..., sort_by = c(\"AIC\", \"BIC\", \"none\"))"},{"path":"https://epiverse-trace.github.io/superspreading/reference/ic_tbl.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Helper function to create a model comparison table — ic_tbl","text":"... dots One model fit results fitdistrplus::fitdist(). sort_by character string specifying information criterion order table , either \"AIC\" (default), \"BIC\", \"none\" (.e. ordering).","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/ic_tbl.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Helper function to create a model comparison table — ic_tbl","text":".","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/ic_tbl.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Helper function to create a model comparison table — ic_tbl","text":"","code":"if (requireNamespace(\"fitdistrplus\", quietly = TRUE)) { cases <- rnbinom(n = 100, mu = 5, size = 0.7) pois_fit <- fitdistrplus::fitdist(data = cases, distr = \"pois\") geom_fit <- fitdistrplus::fitdist(data = cases, distr = \"geom\") nbinom_fit <- fitdistrplus::fitdist(data = cases, distr = \"nbinom\") ic_tbl(pois_fit, geom_fit, nbinom_fit) } #> distribution AIC DeltaAIC wAIC BIC DeltaBIC #> 1 nbinom 538.9290 0.000000 9.415687e-01 544.1393 0.000000 #> 2 geom 544.4884 5.559391 5.843130e-02 547.0936 2.954221 #> 3 pois 937.8823 398.953300 2.199093e-87 940.4875 396.348130 #> wBIC #> 1 8.141357e-01 #> 2 1.858643e-01 #> 3 6.995101e-87"},{"path":"https://epiverse-trace.github.io/superspreading/reference/lseq.html","id":null,"dir":"Reference","previous_headings":"","what":"Generates a log scaled sequence of real numbers — lseq","title":"Generates a log scaled sequence of real numbers — lseq","text":"Generates log scaled sequence real numbers","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/lseq.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Generates a log scaled sequence of real numbers — lseq","text":"","code":"lseq(from, to, length.out)"},{"path":"https://epiverse-trace.github.io/superspreading/reference/lseq.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Generates a log scaled sequence of real numbers — lseq","text":", starting (maximal) end values sequence. length 1 unless just supplied unnamed argument. length.desired length sequence. non-negative number, seq seq.int rounded fractional.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/lseq.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Generates a log scaled sequence of real numbers — lseq","text":"seq.int default method seq numeric arguments return vector type \"integer\" \"double\": programmers rely . seq_along seq_len return integer vector, unless long vector double.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/ppoislnorm.html","id":null,"dir":"Reference","previous_headings":"","what":"Cumulative distribution function of the poisson-lognormal compound distribution — ppoislnorm","title":"Cumulative distribution function of the poisson-lognormal compound distribution — ppoislnorm","text":"Cumulative distribution function poisson-lognormal compound distribution","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/ppoislnorm.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Cumulative distribution function of the poisson-lognormal compound distribution — ppoislnorm","text":"","code":"ppoislnorm(q, meanlog, sdlog)"},{"path":"https://epiverse-trace.github.io/superspreading/reference/ppoislnorm.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Cumulative distribution function of the poisson-lognormal compound distribution — ppoislnorm","text":"q number quantile distribution. meanlog number mean distribution log scale. sdlog number standard deviation distribution log scale.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/ppoislnorm.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Cumulative distribution function of the poisson-lognormal compound distribution — ppoislnorm","text":"numeric vector distribution function.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/ppoislnorm.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Cumulative distribution function of the poisson-lognormal compound distribution — ppoislnorm","text":"function vectorised vector quantiles can input output equal length.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/ppoislnorm.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Cumulative distribution function of the poisson-lognormal compound distribution — ppoislnorm","text":"","code":"ppoislnorm(q = 10, meanlog = 1, sdlog = 2) #> [1] 0.74796 ppoislnorm(q = 1:10, meanlog = 1, sdlog = 2) #> [1] 0.3964753 0.4863815 0.5498326 0.5976395 0.6352928 0.6659097 0.6914104 #> [8] 0.7130517 0.7316966 0.7479600"},{"path":"https://epiverse-trace.github.io/superspreading/reference/ppoisweibull.html","id":null,"dir":"Reference","previous_headings":"","what":"Cumulative distribution function of the poisson-Weibull compound distribution — ppoisweibull","title":"Cumulative distribution function of the poisson-Weibull compound distribution — ppoisweibull","text":"Cumulative distribution function poisson-Weibull compound distribution","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/ppoisweibull.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Cumulative distribution function of the poisson-Weibull compound distribution — ppoisweibull","text":"","code":"ppoisweibull(q, shape, scale)"},{"path":"https://epiverse-trace.github.io/superspreading/reference/ppoisweibull.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Cumulative distribution function of the poisson-Weibull compound distribution — ppoisweibull","text":"q number quantile distribution. shape number shape parameter distribution. scale number scale parameter distribution.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/ppoisweibull.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Cumulative distribution function of the poisson-Weibull compound distribution — ppoisweibull","text":"numeric vector distribution function.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/ppoisweibull.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Cumulative distribution function of the poisson-Weibull compound distribution — ppoisweibull","text":"function vectorised vector quantiles can input output equal length.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/ppoisweibull.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Cumulative distribution function of the poisson-Weibull compound distribution — ppoisweibull","text":"","code":"ppoisweibull(q = 10, shape = 1, scale = 2) #> [1] 0.988439 ppoisweibull(q = 1:10, shape = 1, scale = 2) #> [1] 0.5555556 0.7037037 0.8024691 0.8683128 0.9122085 0.9414723 0.9609816 #> [8] 0.9739877 0.9826585 0.9884390"},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_contain.html","id":null,"dir":"Reference","previous_headings":"","what":"Probability that an outbreak will be contained — probability_contain","title":"Probability that an outbreak will be contained — probability_contain","text":"Outbreak containment defined outbreak extinction simulate = FALSE. simulate = FALSE, probability_contain() equivalent calling probability_extinct(). simulate = TRUE, outbreak containment defined case_threshold (default = 100) outbreak_time arguments. Firstly, case_threshold sets size transmission chain outbreak considered contained. Secondly, outbreak_time sets time duration start outbreak within outbreak contained onwards transmission beyond time. setting outbreak_time, generation_time also required. case_threshold outbreak_time can jointly set. Overall, simulate = TRUE, containment defined size time duration transmission chain reaching case_threshold outbreak_time, respectively.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_contain.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Probability that an outbreak will be contained — probability_contain","text":"","code":"probability_contain( R, k, num_init_infect, ind_control = 0, pop_control = 0, simulate = FALSE, ..., case_threshold = 100, outbreak_time = Inf, generation_time = NULL, offspring_dist )"},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_contain.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Probability that an outbreak will be contained — probability_contain","text":"R number specifying R parameter (.e. average secondary cases per infectious individual). k number specifying k parameter (.e. overdispersion offspring distribution fitted negative binomial). num_init_infect integer (least \"integerish\" stored double) specifying number initial infections. ind_control numeric specifying strength individual-level control measures. 0 (default) 1 (maximum). pop_control numeric specifying strength population-level control measures. 0 (default) 1 (maximum). simulate logical boolean determining whether probability containment calculated analytically numerically using stochastic branching process model. Default FALSE calls probability_extinct(), setting TRUE uses branching process enables setting case_threshold, outbreak_time generation_time arguments. ... Named elements replace default arguments .chain_sim(). See details. case_threshold number threshold number cases epidemic considered contained. case_threshold used simulate = TRUE. outbreak_time number time since start outbreak determine outbreaks contained within given period time. outbreak_time used simulate = TRUE. generation_time function generate generation times. function must single argument return numeric vector generation times. See details example. function can defined anonymous. generation_time used simulate = TRUE. offspring_dist object. S3 class working epidemiological parameters/distributions, see epiparameter::epiparameter().","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_contain.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Probability that an outbreak will be contained — probability_contain","text":"number probability containment.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_contain.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Probability that an outbreak will be contained — probability_contain","text":"using simulate = TRUE, default arguments simulate transmission chains .chain_sim() 1e5 replicates, negative binomial (nbinom) offspring distribution, parameterised R (pop_control > 0) k. setting outbreak_time argument, generation_time argument also required. generation_time argument requires random number generator function. example, assume generation time lognormally distributed meanlog = 1 sdlog = 1.5, can define function pass generation_time :","code":"function(x) rlnorm(x, meanlog = 1, sdlog = 1.5)"},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_contain.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Probability that an outbreak will be contained — probability_contain","text":"Lloyd-Smith, J. O., Schreiber, S. J., Kopp, P. E., & Getz, W. M. (2005) Superspreading effect individual variation disease emergence. Nature, 438(7066), 355-359. doi:10.1038/nature04153","code":""},{"path":[]},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_contain.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Probability that an outbreak will be contained — probability_contain","text":"","code":"# population-level control measures probability_contain(R = 1.5, k = 0.5, num_init_infect = 1, pop_control = 0.1) #> [1] 0.8213172 # individual-level control measures probability_contain(R = 1.5, k = 0.5, num_init_infect = 1, ind_control = 0.1) #> [1] 0.8391855 # both levels of control measures probability_contain( R = 1.5, k = 0.5, num_init_infect = 1, ind_control = 0.1, pop_control = 0.1 ) #> [1] 0.8915076 # multi initial infections with population-level control measures probability_contain(R = 1.5, k = 0.5, num_init_infect = 5, pop_control = 0.1) #> [1] 0.3737271 # probability of containment within a certain amount of time # this requires parameterising a generation time gt <- function(n) { rlnorm(n, meanlog = 1, sdlog = 1.5) } probability_contain( R = 1.5, k = 0.5, num_init_infect = 1, simulate = TRUE, case_threshold = 100, outbreak_time = 20, generation_time = gt ) #> [1] 0.67173"},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_epidemic.html","id":null,"dir":"Reference","previous_headings":"","what":"Calculate the probability a disease will cause an outbreak based on R, k and initial cases — probability_epidemic","title":"Calculate the probability a disease will cause an outbreak based on R, k and initial cases — probability_epidemic","text":"Calculates probability branching process cause epidemic (.e. probability fail go extinct) based R, k initial cases.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_epidemic.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Calculate the probability a disease will cause an outbreak based on R, k and initial cases — probability_epidemic","text":"","code":"probability_epidemic( R, k, num_init_infect, ind_control = 0, pop_control = 0, ..., offspring_dist )"},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_epidemic.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Calculate the probability a disease will cause an outbreak based on R, k and initial cases — probability_epidemic","text":"R number specifying R parameter (.e. average secondary cases per infectious individual). k number specifying k parameter (.e. overdispersion offspring distribution fitted negative binomial). num_init_infect integer (least \"integerish\" stored double) specifying number initial infections. ind_control numeric specifying strength individual-level control measures. 0 (default) 1 (maximum). pop_control numeric specifying strength population-level control measures. 0 (default) 1 (maximum). ... Named elements replace default optimisation settings. Currently \"fit_method\" accepted can either \"optim\" (default) \"grid\" numerical optimisation routine grid search, respectively. offspring_dist object. S3 class working epidemiological parameters/distributions, see epiparameter::epiparameter().","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_epidemic.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Calculate the probability a disease will cause an outbreak based on R, k and initial cases — probability_epidemic","text":"value probability large epidemic.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_epidemic.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Calculate the probability a disease will cause an outbreak based on R, k and initial cases — probability_epidemic","text":"Lloyd-Smith, J. O., Schreiber, S. J., Kopp, P. E., & Getz, W. M. (2005) Superspreading effect individual variation disease emergence. Nature, 438(7066), 355-359. doi:10.1038/nature04153 Kucharski, . J., Russell, T. W., Diamond, C., Liu, Y., Edmunds, J., Funk, S. & Eggo, R. M. (2020). Early dynamics transmission control COVID-19: mathematical modelling study. Lancet Infectious Diseases, 20(5), 553-558. doi:10.1016/S1473-3099(20)30144-4","code":""},{"path":[]},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_epidemic.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Calculate the probability a disease will cause an outbreak based on R, k and initial cases — probability_epidemic","text":"","code":"probability_epidemic(R = 1.5, k = 0.1, num_init_infect = 10) #> [1] 0.5036888"},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_extinct.html","id":null,"dir":"Reference","previous_headings":"","what":"Calculate the probability a branching process will go extinct based on R, k and initial cases — probability_extinct","title":"Calculate the probability a branching process will go extinct based on R, k and initial cases — probability_extinct","text":"Calculates probability branching process causes epidemic go extinct. complement probability disease causing epidemic (probability_epidemic()).","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_extinct.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Calculate the probability a branching process will go extinct based on R, k and initial cases — probability_extinct","text":"","code":"probability_extinct( R, k, num_init_infect, ind_control = 0, pop_control = 0, ..., offspring_dist )"},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_extinct.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Calculate the probability a branching process will go extinct based on R, k and initial cases — probability_extinct","text":"R number specifying R parameter (.e. average secondary cases per infectious individual). k number specifying k parameter (.e. overdispersion offspring distribution fitted negative binomial). num_init_infect integer (least \"integerish\" stored double) specifying number initial infections. ind_control numeric specifying strength individual-level control measures. 0 (default) 1 (maximum). pop_control numeric specifying strength population-level control measures. 0 (default) 1 (maximum). ... Named elements replace default optimisation settings. Currently \"fit_method\" accepted can either \"optim\" (default) \"grid\" numerical optimisation routine grid search, respectively. offspring_dist object. S3 class working epidemiological parameters/distributions, see epiparameter::epiparameter().","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_extinct.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Calculate the probability a branching process will go extinct based on R, k and initial cases — probability_extinct","text":"value probability going extinct.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_extinct.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Calculate the probability a branching process will go extinct based on R, k and initial cases — probability_extinct","text":"Lloyd-Smith, J. O., Schreiber, S. J., Kopp, P. E., & Getz, W. M. (2005). Superspreading effect individual variation disease emergence. Nature, 438(7066), 355-359. doi:10.1038/nature04153","code":""},{"path":[]},{"path":"https://epiverse-trace.github.io/superspreading/reference/probability_extinct.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Calculate the probability a branching process will go extinct based on R, k and initial cases — probability_extinct","text":"","code":"probability_extinct(R = 1.5, k = 0.1, num_init_infect = 10) #> [1] 0.4963112"},{"path":"https://epiverse-trace.github.io/superspreading/reference/proportion_cluster_size.html","id":null,"dir":"Reference","previous_headings":"","what":"Estimate what proportion of new cases originated within a transmission event of a given size — proportion_cluster_size","title":"Estimate what proportion of new cases originated within a transmission event of a given size — proportion_cluster_size","text":"Calculates proportion new cases originated transmission event given size. can useful inform backwards contact tracing efforts, .e. many cases associated large clusters. define cluster transmission primary case least one secondary case.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/proportion_cluster_size.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Estimate what proportion of new cases originated within a transmission event of a given size — proportion_cluster_size","text":"","code":"proportion_cluster_size( R, k, cluster_size, ..., offspring_dist, format_prop = TRUE )"},{"path":"https://epiverse-trace.github.io/superspreading/reference/proportion_cluster_size.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Estimate what proportion of new cases originated within a transmission event of a given size — proportion_cluster_size","text":"R number specifying R parameter (.e. average secondary cases per infectious individual). k number specifying k parameter (.e. overdispersion offspring distribution fitted negative binomial). cluster_size number cluster size threshold. ... dots used, extra arguments supplied cause warning. offspring_dist object. S3 class working epidemiological parameters/distributions, see epiparameter::epiparameter(). format_prop logical determining whether proportion column returned function formatted string percentage sign (%), (TRUE, default), numeric (FALSE).","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/proportion_cluster_size.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Estimate what proportion of new cases originated within a transmission event of a given size — proportion_cluster_size","text":" value proportion new cases part transmission event threshold given value R k.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/proportion_cluster_size.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Estimate what proportion of new cases originated within a transmission event of a given size — proportion_cluster_size","text":"function calculates proportion secondary cases caused transmission events certain size. calculate proportion transmission events cause cluster secondary cases certain size. words number cases threshold divided total number cases, number transmission events certain threshold divided number transmission events.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/proportion_cluster_size.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Estimate what proportion of new cases originated within a transmission event of a given size — proportion_cluster_size","text":"","code":"R <- 2 k <- 0.1 cluster_size <- 10 proportion_cluster_size(R = R, k = k, cluster_size = cluster_size) #> R k prop_10 #> 1 2 0.1 68.8% # example with a vector of k k <- c(0.1, 0.2, 0.3, 0.4, 0.5) proportion_cluster_size(R = R, k = k, cluster_size = cluster_size) #> R k prop_10 #> 1 2 0.1 69.1% #> 2 2 0.2 51% #> 3 2 0.3 38.1% #> 4 2 0.4 31.3% #> 5 2 0.5 25.4% # example with a vector of cluster sizes cluster_size <- c(5, 10, 25) proportion_cluster_size(R = R, k = k, cluster_size = cluster_size) #> R k prop_5 prop_10 prop_25 #> 1 2 0.1 85.7% 68.8% 34.1% #> 2 2 0.2 76.4% 51% 13.9% #> 3 2 0.3 69.4% 39.2% 5.83% #> 4 2 0.4 63.8% 30.4% 2.92% #> 5 2 0.5 59.7% 24.9% 1.39%"},{"path":"https://epiverse-trace.github.io/superspreading/reference/proportion_transmission.html","id":null,"dir":"Reference","previous_headings":"","what":"Estimate what proportion of cases cause a certain proportion of transmission — proportion_transmission","title":"Estimate what proportion of cases cause a certain proportion of transmission — proportion_transmission","text":"Calculates proportion cases cause certain percentage transmission. commonly estimated proportion cases cause 80% transmission (.e. secondary cases). can calculated using proportion_transmission() varying values \\(R\\) different values percentage transmission. two methods calculating proportion transmission, \\(p_{80}\\) (default) \\(t_{20}\\), see method argument details information.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/proportion_transmission.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Estimate what proportion of cases cause a certain proportion of transmission — proportion_transmission","text":"","code":"proportion_transmission( R, k, percent_transmission, method = c(\"p_80\", \"t_20\"), simulate = FALSE, ..., offspring_dist, format_prop = TRUE )"},{"path":"https://epiverse-trace.github.io/superspreading/reference/proportion_transmission.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Estimate what proportion of cases cause a certain proportion of transmission — proportion_transmission","text":"R number specifying R parameter (.e. average secondary cases per infectious individual). k number specifying k parameter (.e. overdispersion offspring distribution fitted negative binomial). percent_transmission number percentage transmission proportion cases produced. method character string defining method used calculate proportion transmission. Options \"p_80\" (default) \"t_20\". See details information methods. simulate logical whether calculation done numerically (.e. simulate secondary contacts) analytically. Default FALSE uses analytical calculation. ... dots used, extra arguments supplied cause warning. offspring_dist object. S3 class working epidemiological parameters/distributions, see epiparameter::epiparameter(). format_prop logical determining whether proportion column returned function formatted string percentage sign (%), (TRUE, default), numeric (FALSE).","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/proportion_transmission.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Estimate what proportion of cases cause a certain proportion of transmission — proportion_transmission","text":" value proportion cases given value R k.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/proportion_transmission.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Estimate what proportion of cases cause a certain proportion of transmission — proportion_transmission","text":"Calculates expected proportion transmission given proportion infectious cases. two methods calculate distinct formulations, \\(p_{80}\\) \\(t_{20}\\) can specified method argument. method = p_80 calculates relative transmission heterogeneity offspring distribution secondary cases, \\(Z\\), upper proportion distribution comprise \\(x\\%\\) total number cases given R0 k, \\(x\\) typically defined 0.8 80%. e.g. 80% transmissions generated upper 20% cases, p_80 = 0.2, per 80/20 rule. formulation, changes R can significant effect estimate \\(p_80\\) even k constant. Importantly, formulation allow true homogeneity k = Inf .e. \\(p_{80} = 0.8\\). method = t_20 calculates similar ratio, instead terms theoretical individual reproductive number infectiousness given R0 k. individual reproductive number, 'v', described Lloyd-Smith JO et al. (2005), \"random variable representing expected number secondary cases caused particular infected individual. Values v drawn continuous gamma probability distribution population mean R0 dispersion parameter k, encodes variation infectious histories individuals, including properties host pathogen environmental circumstances.\" value k corresponds shape parameters gamma distribution encodes variation gamma-poisson mixture aka negative binomial method = t_20, define upper proportion infectiousness, typically 0.2 .e. upper 20% infectious cases, per 80/20 rule. e.g. infectious 20% cases, expected produce 80% infections, t_20 = 0.8. Unlike method = p_80, changes R effect estimate t_80 k constant, R still required underlying calculation. formulation allow true homogeneity k = Inf .e. t_20 = 0.2, t_80 = 0.8. Multiple values R k can supplied every combination returned. numerical calculation method = p_80 uses random number generation simulate secondary contacts answers may minimally vary calls. number simulation replicates fixed 1e5.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/proportion_transmission.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Estimate what proportion of cases cause a certain proportion of transmission — proportion_transmission","text":"analytical calculation : Endo, ., Abbott, S., Kucharski, . J., & Funk, S. (2020) Estimating overdispersion COVID-19 transmission using outbreak sizes outside China. Wellcome Open Research, 5. doi:10.12688/wellcomeopenres.15842.3 \\(t_{20}\\) method follows formula defined section 2.2.5 supplementary material : Lloyd-Smith JO, Schreiber SJ, Kopp PE, Getz WM. Superspreading effect individual variation disease emergence. Nature. 2005 Nov;438(7066):355–9. doi:10.1038/nature04153 original code \\(t_{20}\\) method ongoing work originating https://github.com/dcadam/kt : Adam D, Gostic K, Tsang T, Wu P, Lim WW, Yeung , et al. Time-varying transmission heterogeneity SARS COVID-19 Hong Kong. 2022. doi:10.21203/rs.3.rs-1407962/v1","code":""},{"path":"https://epiverse-trace.github.io/superspreading/reference/proportion_transmission.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Estimate what proportion of cases cause a certain proportion of transmission — proportion_transmission","text":"","code":"# example of single values of R and k percent_transmission <- 0.8 # 80% of transmission R <- 2 k <- 0.5 proportion_transmission( R = R, k = k, percent_transmission = percent_transmission ) #> R k prop_80 #> 1 2 0.5 26.4% # example with multiple values of k k <- c(0.1, 0.2, 0.3, 0.4, 0.5, 1) proportion_transmission( R = R, k = k, percent_transmission = percent_transmission ) #> R k prop_80 #> 1 2 0.1 9.21% #> 2 2 0.2 15.6% #> 3 2 0.3 20.3% #> 4 2 0.4 23.8% #> 5 2 0.5 26.4% #> 6 2 1.0 35.6% # example with vectors of R and k R <- c(1, 2, 3) proportion_transmission( R = R, k = k, percent_transmission = percent_transmission ) #> R k prop_80 #> 1 1 0.1 8.69% #> 2 2 0.1 9.21% #> 3 3 0.1 9.39% #> 4 1 0.2 14.3% #> 5 2 0.2 15.6% #> 6 3 0.2 16% #> 7 1 0.3 18.2% #> 8 2 0.3 20.3% #> 9 3 0.3 21% #> 10 1 0.4 20.8% #> 11 2 0.4 23.8% #> 12 3 0.4 25% #> 13 1 0.5 22.6% #> 14 2 0.5 26.4% #> 15 3 0.5 28% #> 16 1 1.0 30% #> 17 2 1.0 35.6% #> 18 3 1.0 37.8%"},{"path":"https://epiverse-trace.github.io/superspreading/reference/superspreading-package.html","id":null,"dir":"Reference","previous_headings":"","what":"superspreading: Estimate Individual-Level Variation in Transmission — superspreading-package","title":"superspreading: Estimate Individual-Level Variation in Transmission — superspreading-package","text":"Implements functions estimate individual-level variation transmission.","code":""},{"path":[]},{"path":"https://epiverse-trace.github.io/superspreading/reference/superspreading-package.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"superspreading: Estimate Individual-Level Variation in Transmission — superspreading-package","text":"Maintainer: Joshua W. Lambert joshua.lambert@lshtm.ac.uk (ORCID) [copyright holder] Authors: Adam Kucharski adam.kucharski@lshtm.ac.uk (ORCID) [copyright holder] Dillon C. Adam dcadam@hku.hk (ORCID) contributors: Sebastian Funk sebastian.funk@lshtm.ac.uk (ORCID) (.chain_sim uses code bpmodels::chain_sim) [contributor, copyright holder] Pratik Gupte pratik.gupte@lshtm.ac.uk (ORCID) [reviewer] Hugo Gruson hugo@data.org (ORCID) [reviewer] James M. Azam james.azam@lshtm.ac.uk (ORCID) [reviewer, contributor]","code":""},{"path":[]},{"path":"https://epiverse-trace.github.io/superspreading/news/index.html","id":"superspreading-020","dir":"Changelog","previous_headings":"","what":"superspreading 0.2.0","title":"superspreading 0.2.0","text":"Second minor release superspreading. release enhances functions added v0.1.0 adds two new exported functions, two new vignettes.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/news/index.html","id":"new-features-0-2-0","dir":"Changelog","previous_headings":"","what":"New features","title":"superspreading 0.2.0","text":"new function (calc_network_R()) estimate reproduction number heterogeneous networks vignette outlining use cases function existing epidemiological literature added (#71). probability_epidemic() probability_extinct() now individual-level population-level control joint framework (#70). proportion_*() functions can now return proportion columns output numeric new argument format_prop set FALSE (#72). new design principles vignette document package development added (#68). Added helper function (ic_tbl()) improve model comparison tables (#65). probability_*() functions now accept dynamic dots ({rlang} added dependency) (#82).","code":""},{"path":"https://epiverse-trace.github.io/superspreading/news/index.html","id":"breaking-changes-0-2-0","dir":"Changelog","previous_headings":"","what":"Breaking changes","title":"superspreading 0.2.0","text":"ind_control pop_control arguments replace control control_type arguments probability_contain(); argument default num_init_infect removed (#70). Changed epidist argument offspring_dist follow Epiverse style (affects several functions) (#64). Argument proportion_transmission() renamed sim simulate (#81).","code":""},{"path":"https://epiverse-trace.github.io/superspreading/news/index.html","id":"minor-changes-0-2-0","dir":"Changelog","previous_headings":"","what":"Minor changes","title":"superspreading 0.2.0","text":"New package hex logo (#73). Updated continuous integration package infrastructure (#67). Improved function documentation (#63). Optimisation now uses optim() default (#82). Testing suite now uses snapshot testing regression tests (#84).","code":""},{"path":"https://epiverse-trace.github.io/superspreading/news/index.html","id":"bug-fixes-0-2-0","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"superspreading 0.2.0","text":"None {superspreading} functions. Update {epiparameter} use vignette tests (#62).","code":""},{"path":"https://epiverse-trace.github.io/superspreading/news/index.html","id":"deprecated-and-defunct-0-2-0","dir":"Changelog","previous_headings":"","what":"Deprecated and defunct","title":"superspreading 0.2.0","text":"None","code":""},{"path":"https://epiverse-trace.github.io/superspreading/news/index.html","id":"superspreading-010","dir":"Changelog","previous_headings":"","what":"superspreading 0.1.0","title":"superspreading 0.1.0","text":"Initial release superspreading, R package estimate individual-level variation disease transmission provide summary metrics superspreading events.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/news/index.html","id":"new-features-0-1-0","dir":"Changelog","previous_headings":"","what":"New features","title":"superspreading 0.1.0","text":"Offspring distributions, available base R, fit transmission data. Functions calculate probability infectious disease cause epidemic, go extinct contained. Summary metric functions calculate proportion cases cause certain proportion secondary transmission, well proportion cases within clusters certain size. Three vignettes, including: introduction package, estimating individual-level transmission data, effect superspreading epidemic risk. Unit tests documentation files. Continuous integration workflows R package checks, rendering README.md, calculating test coverage, deploying pkgdown website.","code":""},{"path":"https://epiverse-trace.github.io/superspreading/news/index.html","id":"breaking-changes-0-1-0","dir":"Changelog","previous_headings":"","what":"Breaking changes","title":"superspreading 0.1.0","text":"None","code":""},{"path":"https://epiverse-trace.github.io/superspreading/news/index.html","id":"bug-fixes-0-1-0","dir":"Changelog","previous_headings":"","what":"Bug fixes","title":"superspreading 0.1.0","text":"None","code":""},{"path":"https://epiverse-trace.github.io/superspreading/news/index.html","id":"deprecated-and-defunct-0-1-0","dir":"Changelog","previous_headings":"","what":"Deprecated and defunct","title":"superspreading 0.1.0","text":"None","code":""}]