Create an <epidist> object — epidist • epiparameter

The <epidist> 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 <epidist> object is the functional unit provided by {epiparameter} to plug into epidemiological pipelines. Obtaining an <epidist> object can be achieved in two main ways:

The epidemiological distribution is stored in the {epiparameter} library and can be accessed by epidist_db().
The alternative method is when you have information (e.g. disease and distribution parameter estimates) and would like to input this into an <epidist> object in order to work in existing analysis pipelines. This is where the epidist() function can be used to fill out each field for which information is known.

Usage

epidist(
  disease,
  pathogen = NA_character_,
  epi_dist,
  prob_distribution = NA_character_,
  prob_distribution_params = NA_real_,
  uncertainty = create_epidist_uncertainty(),
  summary_stats = create_epidist_summary_stats(),
  auto_calc_params = TRUE,
  citation = create_epidist_citation(),
  metadata = create_epidist_metadata(),
  method_assess = create_epidist_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, or NA 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 is lnorm, negative binomial is nbinom, and geometric is geom).
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_epidist_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_epidist_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 is TRUE. 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 the epidist object created.
citation: A character string with the citation of the source of the data or the paper that inferred the distribution parameters, use create_epidist_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. Use create_epidist_metadata() to create metadata.
method_assess: A list of methodological aspects used when fitting the distribution, use create_epidist_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.

Value

An <epidist> object.

Details

Accepted <epidist> 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 `epidist`
ebola_incubation <- epidist(
  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 `epidist`
ebola_incubation <- epidist(
  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 <- epidist(
  disease = "ebola",
  pathogen = "ebola_virus",
  epi_dist = "incubation",
  prob_distribution = "gamma",
  prob_distribution_params = c(shape = 1, scale = 1),
  uncertainty = create_epidist_uncertainty(),
  summary_stats = create_epidist_summary_stats(
    mean = 2,
    sd = 1
  ),
  citation = create_epidist_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_epidist_metadata(
    sample_size = 10,
    region = "UK",
    transmission_mode = "natural_human_to_human",
    inference_method = "MLE"
  ),
  method_assess = create_epidist_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