# Estimate epidemiological delay distributions with `brms` [![Universe](https://epinowcast.r-universe.dev/badges/epidist)](https://epinowcast.r-universe.dev/epidist) [![MIT license](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/epinowcast/epidist/blob/master/LICENSE.md/) [![GitHub contributors](https://img.shields.io/github/contributors/epinowcast/epidist)](https://github.com/epinowcast/epidist/graphs/contributors) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.14213017.svg)](https://doi.org/10.5281/zenodo.14213017) ## Summary Understanding and accurately estimating epidemiological delay distributions is important for public health policy. These estimates influence epidemic situational awareness, control strategies, and resource allocation. This package provides methods to address the key challenges in estimating these distributions, including truncation, interval censoring, and dynamical biases. These issues are frequently overlooked, resulting in biased conclusions. Built on top of ‘brms’, it allows for flexible modelling including time-varying spatial components and partially pooled estimates of demographic characteristics. ## Quickstart To learn more about `epidist` we recommend reading the vignettes in this order: - [Getting started with `epidist`](https://epidist.epinowcast.org/articles/epidist.html) - [Using `epidist` to estimate delay between symptom onset and positive test for an Ebola outbreak in Sierra Leone](https://epidist.epinowcast.org/articles/ebola.html) - [Approximate Bayesian inference in `epidist`](https://epidist.epinowcast.org/articles/approx-inference.html) ## Installation Installing the package You can install the latest released version using the normal `R` function, though you need to point to `r-universe` instead of CRAN: ``` r install.packages( "epidist", repos = "https://epinowcast.r-universe.dev" ) ``` Alternatively, you can use the [`remotes` package](https://remotes.r-lib.org/) to install the development version from Github (warning! this version may contain breaking changes and/or bugs): ``` r remotes::install_github( file.path("epinowcast", "epidist"), dependencies = TRUE ) ``` Similarly, you can install historical versions by specifying the release tag (e.g. this installs [`0.1.0`](https://github.com/epinowcast/epidist/releases/tag/v0.1.0)): ``` r remotes::install_github( file.path("epinowcast", "epidist"), dependencies = TRUE, ref = "v0.1.0" ) ``` *Note: You can also use that last approach to install a specific commit if needed, e.g. if you want to try out a specific unreleased feature, but not the absolute latest developmental version.* Installing CmdStan (optional) By default `epidist` uses the `rstan` package for fitting models. If you wish to use the `cmdstanr` package instead, you will need to install [CmdStan](https://mc-stan.org/users/interfaces/cmdstan), which also entails having a suitable C++ toolchain setup. We recommend using the [`cmdstanr` package](https://mc-stan.org/cmdstanr/) to manage CmdStan. The Stan team provides instructions in the [*Getting started with `cmdstanr`*](https://mc-stan.org/cmdstanr/articles/cmdstanr.html) vignette, with other details and support at the [package site](https://mc-stan.org/cmdstanr/), but the brief version is: ``` r # if you have not yet installed `epidist`, or you installed it without # `Suggests` dependencies install.packages( "cmdstanr", repos = c("https://stan-dev.r-universe.dev", getOption("repos")) ) # once `cmdstanr` is installed cmdstanr::install_cmdstan() ``` *Note: You can speed up CmdStan installation using the `cores` argument. If you are installing a particular version of `epidist`, you may also need to install a past version of CmdStan, which you can do with the `version` argument.* ## Resources Organisation Website Our [organisation website](https://www.epinowcast.org/) includes links to other resources, [guest posts](https://www.epinowcast.org/blog.html), and [seminar schedule](https://www.epinowcast.org/seminars.html) for both upcoming and past recordings. Community Forum Our [community forum](https://community.epinowcast.org/) has areas for [question and answer](https://community.epinowcast.org/c/interface/15) and [considering new methods and tools](https://community.epinowcast.org/c/projects/11), among others. If you are generally interested in real-time analysis of infectious disease, you may find this useful even if do not use `epidist`. ## Contributing We welcome contributions and new contributors! We particularly appreciate help on [identifying and identified issues](https://github.com/epinowcast/epidist/issues). Please check and add to the issues, and/or add a [pull request](https://github.com/epinowcast/epidist/pulls) and see our [contributing guide](https://github.com/epinowcast/.github/blob/main/CONTRIBUTING.md) for more information. ### How to make a bug report or feature request Please briefly describe your problem and what output you expect in an [issue](https://github.com/epinowcast/epidist/issues). If you have a question, please don’t open an issue. Instead, ask on our [forum](https://community.epinowcast.org/). See our [contributing guide](https://github.com/epinowcast/.github/blob/main/CONTRIBUTING.md) for more information. ### Code of Conduct Please note that the `epidist` project is released with a [Contributor Code of Conduct](https://github.com/epinowcast/.github/blob/main/CODE_OF_CONDUCT.md). By contributing to this project, you agree to abide by its terms. ## Citation If you use `epidist` in your work, please consider citing it using `citation("epidist")`. Package citation information ``` r citation("epidist") To cite package 'epidist' in publications use: Adam Howes, Park S, Sam Abbott (NULL). _epidist: Estimate Epidemiological Delay Distributions With brms_. doi:10.5281/zenodo.14213017 . A BibTeX entry for LaTeX users is @Manual{, title = {epidist: Estimate Epidemiological Delay Distributions With brms}, author = {{Adam Howes} and Sang Woo Park and {Sam Abbott}}, year = {NULL}, doi = {10.5281/zenodo.14213017}, } ``` If using our methodology, or the methodology on which ours is based, please cite the relevant papers. This may include: - [Estimating epidemiological delay distributions for infectious diseases](https://www.medrxiv.org/content/10.1101/2024.01.12.24301247v1) by Park *et al.* (2024) - [Best practices for estimating and reporting epidemiological delay distributions of infectious diseases using public health surveillance and healthcare data](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1012520) by Charniga *et al.* (2024) ## Contributors All contributions to this project are gratefully acknowledged using the [`allcontributors` package](https://github.com/ropensci/allcontributors) following the [all-contributors](https://allcontributors.org) specification. Contributions of any kind are welcome! ### Code [seabbs](https://github.com/epinowcast/epidist/commits?author=seabbs), [athowes](https://github.com/epinowcast/epidist/commits?author=athowes), [parksw3](https://github.com/epinowcast/epidist/commits?author=parksw3), [sbfnk](https://github.com/epinowcast/epidist/commits?author=sbfnk), [cherz4](https://github.com/epinowcast/epidist/commits?author=cherz4), [damonbayer](https://github.com/epinowcast/epidist/commits?author=damonbayer), [medewitt](https://github.com/epinowcast/epidist/commits?author=medewitt), [kcharniga](https://github.com/epinowcast/epidist/commits?author=kcharniga) ### Issue Authors [kgostic](https://github.com/epinowcast/epidist/issues?q=is%3Aissue+author%3Akgostic), [TimTaylor](https://github.com/epinowcast/epidist/issues?q=is%3Aissue+author%3ATimTaylor), [jamesmbaazam](https://github.com/epinowcast/epidist/issues?q=is%3Aissue+author%3Ajamesmbaazam), [jonathonmellor](https://github.com/epinowcast/epidist/issues?q=is%3Aissue+author%3Ajonathonmellor) ### Issue Contributors [pearsonca](https://github.com/epinowcast/epidist/issues?q=is%3Aissue+commenter%3Apearsonca), [SamuelBrand1](https://github.com/epinowcast/epidist/issues?q=is%3Aissue+commenter%3ASamuelBrand1), [zsusswein](https://github.com/epinowcast/epidist/issues?q=is%3Aissue+commenter%3Azsusswein), [oswaldogressani](https://github.com/epinowcast/epidist/issues?q=is%3Aissue+commenter%3Aoswaldogressani) # Package index ## Data preparation ### Linelist data Functions for preparing linelist data - [`as_epidist_linelist_data()`](https://epidist.epinowcast.org/reference/as_epidist_linelist_data.md) : Create an epidist_linelist_data object - [`as_epidist_linelist_data(`*``*`)`](https://epidist.epinowcast.org/reference/as_epidist_linelist_data.data.frame.md) : Create an epidist_linelist_data object from a data frame with event dates - [`as_epidist_linelist_data(`*``*`)`](https://epidist.epinowcast.org/reference/as_epidist_linelist_data.default.md) : Create an epidist_linelist_data object from vectors of event times - [`as_epidist_linelist_data(`*``*`)`](https://epidist.epinowcast.org/reference/as_epidist_linelist_data.epidist_aggregate_data.md) : Convert aggregate data to linelist format - [`assert_epidist(`*``*`)`](https://epidist.epinowcast.org/reference/assert_epidist.epidist_linelist_data.md) : Assert validity of `epidist_linelist_data` objects - [`is_epidist_linelist_data()`](https://epidist.epinowcast.org/reference/is_epidist_linelist_data.md) : Check if data has the `epidist_linelist_data` class - [`new_epidist_linelist_data()`](https://epidist.epinowcast.org/reference/new_epidist_linelist_data.md) : Class constructor for `epidist_linelist_data` objects ### Aggregate data Functions for preparing aggregate data - [`as_epidist_aggregate_data()`](https://epidist.epinowcast.org/reference/as_epidist_aggregate_data.md) : Create an epidist_aggregate_data object - [`as_epidist_aggregate_data(`*``*`)`](https://epidist.epinowcast.org/reference/as_epidist_aggregate_data.data.frame.md) : Create an epidist_aggregate_data object from a data.frame - [`as_epidist_aggregate_data(`*``*`)`](https://epidist.epinowcast.org/reference/as_epidist_aggregate_data.default.md) : Create an epidist_aggregate_data object from vectors of event times - [`as_epidist_aggregate_data(`*``*`)`](https://epidist.epinowcast.org/reference/as_epidist_aggregate_data.epidist_linelist_data.md) : Convert linelist data to aggregate format - [`assert_epidist(`*``*`)`](https://epidist.epinowcast.org/reference/assert_epidist.epidist_aggregate_data.md) : Assert validity of `epidist_aggregate_data` objects - [`is_epidist_aggregate_data()`](https://epidist.epinowcast.org/reference/is_epidist_aggregate_data.md) : Check if data has the `epidist_aggregate_data` class - [`new_epidist_aggregate_data()`](https://epidist.epinowcast.org/reference/new_epidist_aggregate_data.md) : Class constructor for `epidist_aggregate_data` objects ## Models ### Naive model Specific methods for the naive model - [`as_epidist_naive_model()`](https://epidist.epinowcast.org/reference/as_epidist_naive_model.md) : Convert an object to an `epidist_naive_model` object - [`as_epidist_naive_model(`*``*`)`](https://epidist.epinowcast.org/reference/as_epidist_naive_model.epidist_aggregate_data.md) : The naive model method for `epidist_aggregate_data` objects - [`as_epidist_naive_model(`*``*`)`](https://epidist.epinowcast.org/reference/as_epidist_naive_model.epidist_linelist_data.md) : The naive model method for `epidist_linelist_data` objects - [`epidist_formula_model(`*``*`)`](https://epidist.epinowcast.org/reference/epidist_formula_model.epidist_naive_model.md) : Define the model-specific component of an `epidist` custom formula for the naive model - [`epidist_transform_data_model(`*``*`)`](https://epidist.epinowcast.org/reference/epidist_transform_data_model.epidist_naive_model.md) : Transform data for the naive model - [`is_epidist_naive_model()`](https://epidist.epinowcast.org/reference/is_epidist_naive_model.md) : Check if data has the `epidist_naive_model` class - [`new_epidist_naive_model()`](https://epidist.epinowcast.org/reference/new_epidist_naive_model.md) : Class constructor for `epidist_naive_model` objects ### Latent model Specific methods for the latent model - [`as_epidist_latent_model()`](https://epidist.epinowcast.org/reference/as_epidist_latent_model.md) : Convert an object to an `epidist_latent_model` object - [`as_epidist_latent_model(`*``*`)`](https://epidist.epinowcast.org/reference/as_epidist_latent_model.epidist_aggregate_data.md) : The latent model method for `epidist_aggregate_data` objects - [`as_epidist_latent_model(`*``*`)`](https://epidist.epinowcast.org/reference/as_epidist_latent_model.epidist_linelist_data.md) : The latent model method for `epidist_linelist_data` objects - [`epidist_family_model(`*``*`)`](https://epidist.epinowcast.org/reference/epidist_family_model.epidist_latent_model.md) : Create the model-specific component of an `epidist` custom family - [`epidist_formula_model(`*``*`)`](https://epidist.epinowcast.org/reference/epidist_formula_model.epidist_latent_model.md) : Define the model-specific component of an `epidist` custom formula for the latent model - [`epidist_model_prior(`*``*`)`](https://epidist.epinowcast.org/reference/epidist_model_prior.epidist_latent_model.md) : Model specific prior distributions for latent models - [`is_epidist_latent_model()`](https://epidist.epinowcast.org/reference/is_epidist_latent_model.md) : Check if data has the `epidist_latent_model` class - [`new_epidist_latent_model()`](https://epidist.epinowcast.org/reference/new_epidist_latent_model.md) : Class constructor for `epidist_latent_model` objects ### Marginal model Specific methods for the marginal model - [`as_epidist_marginal_model()`](https://epidist.epinowcast.org/reference/as_epidist_marginal_model.md) : Convert an object to an `epidist_marginal_model` object - [`as_epidist_marginal_model(`*``*`)`](https://epidist.epinowcast.org/reference/as_epidist_marginal_model.epidist_aggregate_data.md) : The marginal model method for `epidist_aggregate_data` objects - [`as_epidist_marginal_model(`*``*`)`](https://epidist.epinowcast.org/reference/as_epidist_marginal_model.epidist_linelist_data.md) : The marginal model method for `epidist_linelist_data` objects - [`epidist_family_model(`*``*`)`](https://epidist.epinowcast.org/reference/epidist_family_model.epidist_marginal_model.md) : Create the model-specific component of an `epidist` custom family - [`epidist_formula_model(`*``*`)`](https://epidist.epinowcast.org/reference/epidist_formula_model.epidist_marginal_model.md) : Define the model-specific component of an `epidist` custom formula for the marginal model - [`epidist_transform_data_model(`*``*`)`](https://epidist.epinowcast.org/reference/epidist_transform_data_model.epidist_marginal_model.md) : Transform data for the marginal model - [`is_epidist_marginal_model()`](https://epidist.epinowcast.org/reference/is_epidist_marginal_model.md) : Check if data has the `epidist_marginal_model` class - [`new_epidist_marginal_model()`](https://epidist.epinowcast.org/reference/new_epidist_marginal_model.md) : Class constructor for `epidist_marginal_model` objects ## Model fitting ### Model fitting Functions for fitting delay distribution models using `brms` - [`epidist()`](https://epidist.epinowcast.org/reference/epidist.md) : Fit epidemiological delay distributions using a `brms` interface ### Postprocess Functions for postprocessing model output - [`add_mean_sd()`](https://epidist.epinowcast.org/reference/add_mean_sd.md) : Add natural scale mean and standard deviation parameters - [`add_mean_sd(`*``*`)`](https://epidist.epinowcast.org/reference/add_mean_sd.default.md) : Default method for add natural scale parameters - [`add_mean_sd(`*``*`)`](https://epidist.epinowcast.org/reference/add_mean_sd.gamma_samples.md) : Add natural scale mean and standard deviation parameters for a Gamma model - [`add_mean_sd(`*``*`)`](https://epidist.epinowcast.org/reference/add_mean_sd.lognormal_samples.md) : Add natural scale mean and standard deviation parameters for a lognormal model - [`add_mean_sd(`*``*`)`](https://epidist.epinowcast.org/reference/add_mean_sd.weibull_samples.md) : Add natural scale mean and standard deviation parameters for a Weibull model - [`predict_delay_parameters()`](https://epidist.epinowcast.org/reference/predict_delay_parameters.md) [`predict_dpar()`](https://epidist.epinowcast.org/reference/predict_delay_parameters.md) : Extract samples of the delay distribution parameters ### Diagnostic functions - [`epidist_diagnostics()`](https://epidist.epinowcast.org/reference/epidist_diagnostics.md) : Diagnostics for `epidist_fit` models ## Model specification ### Family Functions related to specifying custom `brms` families - [`epidist_family()`](https://epidist.epinowcast.org/reference/epidist_family.md) : Define `epidist` family - [`epidist_family_model()`](https://epidist.epinowcast.org/reference/epidist_family_model.md) [`epidist_formula_model()`](https://epidist.epinowcast.org/reference/epidist_family_model.md) : The model-specific parts of an [`epidist_family()`](https://epidist.epinowcast.org/reference/epidist_family.md) call - [`epidist_family_model(`*``*`)`](https://epidist.epinowcast.org/reference/epidist_family_model.default.md) : Default method for defining a model specific family - [`epidist_family_param()`](https://epidist.epinowcast.org/reference/epidist_family_param.md) : Reparameterise an `epidist` family to align `brms` and Stan - [`epidist_family_param(`*``*`)`](https://epidist.epinowcast.org/reference/epidist_family_param.default.md) : Default method for families which do not require a reparameterisation ### Formula Functions related to specifying custom `brms` formula - [`epidist_family_model()`](https://epidist.epinowcast.org/reference/epidist_family_model.md) [`epidist_formula_model()`](https://epidist.epinowcast.org/reference/epidist_family_model.md) : The model-specific parts of an [`epidist_family()`](https://epidist.epinowcast.org/reference/epidist_family.md) call - [`epidist_formula()`](https://epidist.epinowcast.org/reference/epidist_formula.md) : Define a model specific formula - [`epidist_formula_model(`*``*`)`](https://epidist.epinowcast.org/reference/epidist_formula_model.default.md) : Default method for defining a model specific formula ### Prior distributions Functions for specifying prior distributions - [`epidist_family_prior()`](https://epidist.epinowcast.org/reference/epidist_family_prior.md) : Family specific prior distributions - [`epidist_family_prior(`*``*`)`](https://epidist.epinowcast.org/reference/epidist_family_prior.default.md) : Default family specific prior distributions - [`epidist_family_prior(`*``*`)`](https://epidist.epinowcast.org/reference/epidist_family_prior.lognormal.md) : Family specific prior distributions for the lognormal family - [`epidist_model_prior()`](https://epidist.epinowcast.org/reference/epidist_model_prior.md) : Model specific prior distributions - [`epidist_model_prior(`*``*`)`](https://epidist.epinowcast.org/reference/epidist_model_prior.default.md) : Default model specific prior distributions - [`epidist_prior()`](https://epidist.epinowcast.org/reference/epidist_prior.md) : Define custom prior distributions for epidist models ### Stan code Functions for specifying custom Stan code to put into `brms` - [`epidist_stancode()`](https://epidist.epinowcast.org/reference/epidist_stancode.md) : Define model specific Stan code - [`epidist_stancode(`*``*`)`](https://epidist.epinowcast.org/reference/epidist_stancode.default.md) : Default method for defining model specific Stan code ## Package internals ### Transform data Transform data using the formula and family information - [`epidist_transform_data()`](https://epidist.epinowcast.org/reference/epidist_transform_data.md) : Transform data for an epidist model - [`epidist_transform_data_model()`](https://epidist.epinowcast.org/reference/epidist_transform_data_model.md) : The model-specific parts of an [`epidist_transform_data()`](https://epidist.epinowcast.org/reference/epidist_transform_data.md) call - [`epidist_transform_data_model(`*``*`)`](https://epidist.epinowcast.org/reference/epidist_transform_data_model.default.md) : Default method for transforming data for a model ### Generator model functions Generator functions for creating family specific model utilities. - [`epidist_gen_log_lik()`](https://epidist.epinowcast.org/reference/epidist_gen_log_lik.md) : Create a function to calculate the marginalised log likelihood for double censored and truncated delay distributions - [`epidist_gen_posterior_epred()`](https://epidist.epinowcast.org/reference/epidist_gen_posterior_epred.md) : Create a function to draw from the expected value of the posterior predictive distribution for a model - [`epidist_gen_posterior_predict()`](https://epidist.epinowcast.org/reference/epidist_gen_posterior_predict.md) : Create a function to draw from the posterior predictive distribution for a double censored and truncated delay distribution ### Assert validity of objects Functions used to assert the validity of package objects - [`assert_epidist()`](https://epidist.epinowcast.org/reference/assert_epidist.md) : Validation for epidist objects ## Simulation and Data ### Simulation Tools for simulating datasets - [`simulate_exponential_cases()`](https://epidist.epinowcast.org/reference/simulate_exponential_cases.md) : Simulate exponential cases - [`simulate_gillespie()`](https://epidist.epinowcast.org/reference/simulate_gillespie.md) : Simulate cases from a stochastic SIR model - [`simulate_secondary()`](https://epidist.epinowcast.org/reference/simulate_secondary.md) : Simulate secondary events based on a delay distribution - [`simulate_uniform_cases()`](https://epidist.epinowcast.org/reference/simulate_uniform_cases.md) : Simulate cases from a uniform distribution ### Data Data included with the package - [`sierra_leone_ebola_data`](https://epidist.epinowcast.org/reference/sierra_leone_ebola_data.md) : Ebola linelist data from Fang et al. (2016) ## Reexported functions - [`reexports`](https://epidist.epinowcast.org/reference/reexports.md) [`lognormal`](https://epidist.epinowcast.org/reference/reexports.md) [`weibull`](https://epidist.epinowcast.org/reference/reexports.md) [`Gamma`](https://epidist.epinowcast.org/reference/reexports.md) [`bf`](https://epidist.epinowcast.org/reference/reexports.md) : Objects exported from other packages # Articles ### All vignettes - [Approximate Bayesian inference in epidist](https://epidist.epinowcast.org/articles/approx-inference.md): “A demonstration of how to fit models in epidist using approximate Bayesian inference methods such as the Laplace approximation, ADVI, and Pathfinder.” - [Using epidist to estimate delay between symptom onset and positive test for an Ebola outbreak in Sierra Leone](https://epidist.epinowcast.org/articles/ebola.md): A more detailed guide to using the epidist R package - [Getting started with epidist](https://epidist.epinowcast.org/articles/epidist.md): A quick start guide to using the epidist R package - [Frequently asked questions and tips](https://epidist.epinowcast.org/articles/faq.md): - [Guide to the statistical models implemented in epidist](https://epidist.epinowcast.org/articles/model.md):