The <epiparameter>
class is used to store epidemiological
parameters for a single disease. These epidemiological parameters cover a
variety of aspects including delay distributions (e.g. incubation periods
and serial intervals, among others) and offspring distributions.
The <epiparameter>
object is the functional unit provided by
{epiparameter}
to plug into epidemiological pipelines. Obtaining an
<epiparameter>
object can be achieved in two main ways:
The epidemiological distribution is stored in the
{epiparameter}
library and can be accessed byepiparameter_db()
.The alternative method is when you have information (e.g. disease and distribution parameter estimates) and would like to input this into an
<epiparameter>
object in order to work in existing analysis pipelines. This is where theepiparameter()
function can be used to fill out each field for which information is known.
Usage
epiparameter(
disease,
pathogen = NA_character_,
epi_dist,
prob_distribution = NA_character_,
prob_distribution_params = NA_real_,
uncertainty = create_uncertainty(),
summary_stats = create_summary_stats(),
auto_calc_params = TRUE,
citation = create_citation(),
metadata = create_metadata(),
method_assess = create_method_assess(),
discretise = FALSE,
truncation = NA_real_,
notes = NULL,
...
)
Arguments
- disease
A
character
string with name of the infectious disease.- pathogen
A
character
string with the name of the causative agent of disease, orNA
if not known.- epi_dist
A
character
string with the name of the epidemiological distribution type.- prob_distribution
A
character
string specifying the probability distribution. This should match the R naming convention of probability distributions (e.g. lognormal islnorm
, negative binomial isnbinom
, and geometric isgeom
).- prob_distribution_params
A named vector of probability distribution parameters.
- uncertainty
A list of named vectors with the uncertainty around the probability distribution parameters. If uncertainty around the parameter estimates is unknown use
create_uncertainty()
(which is the argument default) to create a list with the correct names with missing values.- summary_stats
A list of summary statistics, use
create_summary_stats()
to create list. This list can include summary statistics about the inferred distribution such as it's mean and standard deviation, quantiles of the distribution, or information about the data used to fit the distribution such as lower and upper range. The summary statistics can also include uncertainty around metrics such as confidence interval around mean and standard deviation.- auto_calc_params
A boolean
logical
determining whether to try and calculate the probability distribution parameters from summary statistics if distribution parameters are not provided. Default isTRUE
. In the case when sufficient summary statistics are provided and the parameter(s) of the distribution are not, the.calc_dist_params()
function is called to calculate the parameters and add them to theepiparameter
object created.- citation
A
<bibentry>
with the citation of the source of the data or the paper that inferred the distribution parameters, usecreate_citation()
to create citation.- metadata
A list of metadata, this can include: sample size, the transmission mode of the disease (e.g. is it vector-borne or directly transmitted), etc. It is assumed that the disease is not vector-borne and that the distribution is intrinsic (e.g. not an extrinsic delay distribution such as extrinsic incubation period) unless
transmission_mode = "vector_borne"
is contained in the metadata. Usecreate_metadata()
to create metadata.- method_assess
A list of methodological aspects used when fitting the distribution, use
create_method_assess()
to create method assessment.- discretise
A boolean
logical
whether the distribution is discretised. Default is FALSE which assumes a continuous probability distribution- truncation
A
numeric
specifying the truncation point if the inferred distribution was truncated,NA
if not or unknown.- notes
A
character
string with any additional information about the data, inference method or disease.- ...
dots Extra arguments to be passed to internal functions.
This is most commonly used to pass arguments to
distcrete::distcrete()
that construct the discretised distribution S3 object. To see which arguments can be adjusted for discretised distributions seedistcrete::distcrete()
.
Details
Accepted <epiparameter>
distribution parameterisations are:
Gamma must be either 'shape' and 'scale' or 'shape' and 'rate'
Weibull must be 'shape' and 'scale'
Lognormal must be 'meanlog' and 'sdlog' or 'mu' and 'sigma'
Negative Binomial must be either 'mean' and 'dispersion' or 'n' and 'p'
Geometric must be either 'mean' or 'prob'
Poisson must be 'mean'
Examples
# minimal input required for `epiparameter`
ebola_incubation <- epiparameter(
disease = "ebola",
epi_dist = "incubation_period",
prob_distribution = "gamma",
prob_distribution_params = c(shape = 1, scale = 1)
)
#> Citation cannot be created as author, year, journal or title is missing
# minimal input required for discrete `epiparameter`
ebola_incubation <- epiparameter(
disease = "ebola",
epi_dist = "incubation_period",
prob_distribution = "gamma",
prob_distribution_params = c(shape = 1, scale = 1),
discretise = TRUE
)
#> Citation cannot be created as author, year, journal or title is missing
# example with more fields filled in
ebola_incubation <- epiparameter(
disease = "ebola",
pathogen = "ebola_virus",
epi_dist = "incubation",
prob_distribution = "gamma",
prob_distribution_params = c(shape = 1, scale = 1),
uncertainty = create_uncertainty(),
summary_stats = create_summary_stats(mean = 2, sd = 1),
citation = create_citation(
author = person(given = "John", family = "Smith"),
year = 2002,
title = "COVID-19 incubation period",
journal = "Epi Journal",
doi = "10.19832/j.1366-9516.2012.09147.x"
),
metadata = create_metadata(
sample_size = 10,
region = "UK",
transmission_mode = "natural_human_to_human",
inference_method = "MLE"
),
method_assess = create_method_assess(
censored = TRUE
),
discretise = FALSE,
truncation = NA,
notes = "No notes"
)
#> Using Smith J (2002). “COVID-19 incubation period.” _Epi Journal_.
#> doi:10.19832/j.1366-9516.2012.09147.x
#> <https://doi.org/10.19832/j.1366-9516.2012.09147.x>.
#> To retrieve the citation use the 'get_citation' function