From 7be89e5c21a9480f4933a38049d7901d4bf525eb Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Fri, 24 Nov 2023 16:05:54 +0000 Subject: [PATCH] Automatic readme update --- README.md | 447 ++++++++++++++++-------------------------------------- 1 file changed, 133 insertions(+), 314 deletions(-) diff --git a/README.md b/README.md index 8c6ccd09d..c229a7404 100644 --- a/README.md +++ b/README.md @@ -17,8 +17,10 @@ contributors](https://img.shields.io/github/contributors/epiforecasts/EpiNow2)]( commits](https://img.shields.io/github/commits-since/epiforecasts/EpiNow2/v1.4.0.svg?color=orange)](https://GitHub.com/epiforecasts/EpiNow2/commit/main/) [![DOI](https://zenodo.org/badge/272995211.svg)](https://zenodo.org/badge/latestdoi/272995211) -This package estimates the time-varying reproduction number, growth -rate, and doubling time using a range of open-source tools ([Abbott et +## Summary + +EpiNow2 estimates the time-varying reproduction number, growth rate, and +doubling time using a range of open-source tools ([Abbott et al.](https://doi.org/10.12688/wellcomeopenres.16006.1)), and current best practices ([Gostic et al.](https://doi.org/10.1371/journal.pcbi.1008409)). It aims to help @@ -26,8 +28,17 @@ users avoid some of the limitations of naive implementations in a framework that is informed by community feedback and is actively supported. -It estimates the time-varying reproduction number on cases by date of -infection (using a similar approach to that implemented in +Forecasting is also supported for the time-varying reproduction number, +infections, and reported cases using the same generative process +approach as used for estimation. + +
+ +More details + + +EpiNow2 estimates the time-varying reproduction number on cases by date +of infection (using a similar approach to that implemented in [`{EpiEstim}`](https://github.com/mrc-ide/EpiEstim)). Imputed infections are then mapped to observed data (for example cases by date of report) via a series of uncertain delay distributions (in the examples in the @@ -39,9 +50,38 @@ estimates, helping to mitigate spurious findings. This is handled internally. The time-varying reproduction estimates and the uncertain generation time also give time-varying estimates of the rate of growth. -The default model uses a non-stationary Gaussian process to estimate the -time-varying reproduction number and then infer infections. Other -options include: +
+
+ +Models provided + + +`{EpiNow2}` is designed to be used via a single function call to two +functions: + +- [`epinow()`](https://epiforecasts.io/EpiNow2/reference/epinow.html): + Estimate Rt and cases by date of infection and forecast these + infections into the future. + +- [`regional_epinow()`](https://epiforecasts.io/EpiNow2/reference/regional_epinow.html): + Efficiently run `epinow()` across multiple regions in an efficient + manner. + +These two functions call +[`estimate_infections()`](https://epiforecasts.io/EpiNow2/reference/estimate_infections.html), +which works to reconstruct cases by date of infection from reported +cases. + +[`estimate_infections()`](https://epiforecasts.io/EpiNow2/reference/estimate_infections.html) +can be used on its own to infer the underlying infection case curve from +reported cases and estimate Rt. Estimating the underlying infection case +curve via back-calculation (and then calculating Rt) is substantially +less computationally demanding than generating using default settings +but may result in less reliable estimates of Rt. + +The default model in `estimate_infections()` uses a non-stationary +Gaussian process to estimate the time-varying reproduction number and +then infer infections. Other options include: - A stationary Gaussian process (faster to estimate but currently gives reduced performance for real time estimates). @@ -64,20 +104,23 @@ The documentation for provides examples of the implementation of the different options available. -Forecasting is also supported for the time-varying reproduction number, -infections and reported cases using the same generative process approach -as used for estimation. +### Other functions -A simple example of using the package to estimate a national Rt for -Covid-19 can be found -[here](https://gist.github.com/seabbs/163d0f195892cde685c70473e1f5e867). +- [`estimate_secondary()`](https://epiforecasts.io/EpiNow2/reference/estimate_secondary.html): + Estimate the relationship between primary and secondary observations, + for example, deaths (secondary) based on hospital admissions + (primary), or bed occupancy (secondary) based on hospital admissions + (primary). + +- [`estimate_truncation()`](https://epiforecasts.io/EpiNow2/reference/estimate_truncation.html): + Estimate a truncation distribution from multiple snapshots of the same + data source over time. For more flexibility, check out the + [`{epinowcast}`](https://package.epinowcast.org/) package. + +For more details on using each function see the [function +documentation](https://epiforecasts.io/EpiNow2/reference/index.html). -`EpiNow2` also supports adjustment for truncated data via -`estimate_truncation()` (though users may be interested in more -flexibility and if so should check out the -[`epinowcast`](https://package.epinowcast.org/) package), and for -estimating dependent observations (i.e deaths based on hospital -admissions) using `estimate_secondary()`. +
## Installation @@ -124,296 +167,70 @@ simple deployment/development a prebuilt docker image is also available (see documentation [here](https://github.com/epiforecasts/EpiNow2/wiki/Docker)). -## Quick start - -`{EpiNow2}` is designed to be used with a single function call or to be -used in an ad-hoc fashion via individual function calls. The core -functions of `{EpiNow2}` are the two single-call functions -[`epinow()`](https://epiforecasts.io/EpiNow2/reference/epinow.html), -[`regional_epinow()`](https://epiforecasts.io/EpiNow2/reference/regional_epinow.html), -plus functions -[`estimate_infections()`](https://epiforecasts.io/EpiNow2/reference/estimate_infections.html), -[`estimate_secondary()`](https://epiforecasts.io/EpiNow2/reference/estimate_secondary.html) -and -[`estimate_truncation()`](https://epiforecasts.io/EpiNow2/reference/estimate_truncation.html). -In the following section we give an overview of the simple use case for -`epinow` and `regional_epinow`. -[`estimate_infections()`](https://epiforecasts.io/EpiNow2/reference/estimate_infections.html) -can be used on its own to infer the underlying infection case curve from -reported cases and estimate Rt. Estimating the underlying infection case -curve via back-calculation (and then calculating Rt) is substantially -less computationally demanding than generating using default settings -but may result in less reliable estimates of Rt. For more details on -using each function see the [function -documentation](https://epiforecasts.io/EpiNow2/reference/index.html). - -The first step to using the package is to load it as follows. - -``` r -library(EpiNow2) -``` - -### Reporting delays, incubation period and generation time - -Distributions can either be fitted using package functionality or -determined elsewhere and then defined with uncertainty for use in -`{EpiNow2}`. When data is supplied a subsampled bootstrapped lognormal -will be fit (to account for uncertainty in the observed data without -being biased by changes in incidence). An arbitrary number of delay -distributions are supported with the most common use case likely to be a -incubation period followed by a reporting delay. - -For example if data on the delay between onset and infection was -available we could fit a distribution to it with appropriate uncertainty -as follows (note this is a synthetic example), - -``` r -reporting_delay <- estimate_delay( - rlnorm(1000, log(2), 1), - max_value = 14, bootstraps = 1 -) -``` - -If data was not available we could instead make an informed estimate of -the likely delay. We choose a lognormal distribution with mean 2, -standard deviation 1 (both with some uncertainty) and a maximum of 10. -*This is just an example and unlikely to apply in any particular use -case*. - -``` r -reporting_delay <- dist_spec( - mean = convert_to_logmean(2, 1), - mean_sd = 0.1, - sd = convert_to_logsd(2, 1), - sd_sd = 0.1, - max = 10, - dist = "lognormal" -) -#> Warning: The meaning of the 'max' argument has changed compared to previous versions. It now indicates the maximum of a distribution rather than the length of the probability mass function (including 0) that it represented previously. To replicate previous behaviour reduce max by 1. -#> This warning is displayed once every 8 hours. -reporting_delay -#> -#> Uncertain lognormal distribution with (untruncated) logmean 0.58 (SD 0.1) and logSD 0.47 (SD 0.1) -``` - -We use example literature estimates for the incubation period and -generation time of Covid-19 (see -[here](https://github.com/epiforecasts/EpiNow2/tree/main/data-raw) for -the code that generates these estimates). *These distributions are -unlikely to be applicable for your use case. We strongly recommend -investigating what might be the best distributions to use in any given -use case.* - -``` r -example_generation_time -#> -#> Uncertain gamma distribution with (untruncated) mean 3.6 (SD 0.71) and SD 3.1 (SD 0.77) -example_incubation_period -#> -#> Uncertain lognormal distribution with (untruncated) logmean 1.6 (SD 0.064) and logSD 0.42 (SD 0.069) -``` - -### [epinow()](https://epiforecasts.io/EpiNow2/reference/epinow.html) +## Resources + +
+ +Getting Started + + +The [Getting Started +vignette](https://epiforecasts.io/EpiNow2/dev/EpiNow2.html) is your +quickest entry point to the package. It provides a quick run through of +the two main functions in the package and how to set up them up. It also +discusses how to summarise and visualise the results after running the +models. + +
+
+ +Package website + + +The [package website](https://epiforecasts.io/EpiNow2/dev/index.html) +provides various resources for learning about the package, including the +function reference, details about each model (model definition), +workflows for each model (usage), and case studies or literature of +applications of the package. + +
+
+ +End-to-end workflows + + +The [workflow +vignette](https://epiforecasts.io/EpiNow2/dev/articles/estimate_infections_workflow.html) +provides guidance on the end-to-end process of estimating reproduction +numbers and performing short-term forecasts for a disease spreading in a +given setting. + +
+
+ +Model definitions + + +On the website, we provide the mathematical definition of each model. +For example, the model definition vignette for `estimate_infections()` +can be found +[here](https://epiforecasts.io/EpiNow2/dev/articles/estimate_infections.html). + +
+
+ +Example implementations + -This function represents the core functionality of the package and -includes results reporting, plotting and optional saving. It requires a -data frame of cases by date of report and the distributions defined -above. - -Load example case data from `{EpiNow2}`. - -``` r -reported_cases <- example_confirmed[1:60] -head(reported_cases) -#> date confirm -#> 1: 2020-02-22 14 -#> 2: 2020-02-23 62 -#> 3: 2020-02-24 53 -#> 4: 2020-02-25 97 -#> 5: 2020-02-26 93 -#> 6: 2020-02-27 78 -``` - -Estimate cases by date of infection, the time-varying reproduction -number, the rate of growth and forecast these estimates into the future -by 7 days. Summarise the posterior and return a summary table and plots -for reporting purposes. If a `target_folder` is supplied results can be -internally saved (with the option to also turn off explicit returning of -results). Here we use the default model parameterisation that -prioritises real-time performance over run-time or other considerations. -For other formulations see the documentation for -`estimate_infections()`. - -``` r -estimates <- epinow( - reported_cases = reported_cases, - generation_time = generation_time_opts(example_generation_time), - delays = delay_opts(example_incubation_period + reporting_delay), - rt = rt_opts(prior = list(mean = 2, sd = 0.2)), - stan = stan_opts(cores = 4, control = list(adapt_delta = 0.99)), - verbose = interactive() -) -names(estimates) -#> [1] "estimates" "estimated_reported_cases" -#> [3] "summary" "plots" -#> [5] "timing" -``` - -Both summary measures and posterior samples are returned for all -parameters in an easily explored format which can be accessed using -`summary`. The default is to return a summary table of estimates for key -parameters at the latest date partially supported by data. - -``` r -knitr::kable(summary(estimates)) -``` - -| measure | estimate | -|:--------------------------------------|:----------------------| -| New confirmed cases by infection date | 2243 (1144 – 4190) | -| Expected change in daily cases | Likely decreasing | -| Effective reproduction no. | 0.88 (0.6 – 1.2) | -| Rate of growth | -0.028 (-0.1 – 0.035) | -| Doubling/halving time (days) | -25 (20 – -6.9) | - -Summarised parameter estimates can also easily be returned, either -filtered for a single parameter or for all parameters. - -``` r -head(summary(estimates, type = "parameters", params = "R")) -#> date variable strat type median mean sd lower_90 -#> 1: 2020-02-22 R estimate 2.227000 2.234991 0.14475898 2.012280 -#> 2: 2020-02-23 R estimate 2.194586 2.199036 0.11981031 2.012784 -#> 3: 2020-02-24 R estimate 2.158077 2.160968 0.09983093 2.002390 -#> 4: 2020-02-25 R estimate 2.120294 2.120978 0.08450716 1.986945 -#> 5: 2020-02-26 R estimate 2.080098 2.079349 0.07331063 1.962580 -#> 6: 2020-02-27 R estimate 2.036740 2.036424 0.06555145 1.928347 -#> lower_50 lower_20 upper_20 upper_50 upper_90 -#> 1: 2.132905 2.188984 2.268706 2.332697 2.484471 -#> 2: 2.113308 2.162047 2.228660 2.280186 2.402885 -#> 3: 2.091295 2.132324 2.184877 2.228413 2.327439 -#> 4: 2.063099 2.098374 2.140263 2.176206 2.266145 -#> 5: 2.028392 2.060083 2.097677 2.124936 2.203185 -#> 6: 1.992552 2.020233 2.053117 2.077413 2.146660 -``` - -Reported cases are returned in a separate data frame in order to -streamline the reporting of forecasts and for model evaluation. - -``` r -head(summary(estimates, output = "estimated_reported_cases")) -#> date type median mean sd lower_90 lower_50 lower_20 -#> 1: 2020-02-22 gp_rt 66 67.7370 17.87953 42.00 55.00 62 -#> 2: 2020-02-23 gp_rt 76 77.7610 20.41899 47.00 63.00 71 -#> 3: 2020-02-24 gp_rt 77 77.6055 20.03036 47.00 64.00 72 -#> 4: 2020-02-25 gp_rt 74 75.5260 19.66621 47.00 61.00 70 -#> 5: 2020-02-26 gp_rt 78 79.4530 20.99436 48.95 64.00 73 -#> 6: 2020-02-27 gp_rt 111 113.4765 28.82705 71.95 93.75 103 -#> upper_20 upper_50 upper_90 -#> 1: 70.0 79 102.00 -#> 2: 81.0 91 112.00 -#> 3: 82.0 90 113.00 -#> 4: 79.0 87 110.00 -#> 5: 83.0 93 117.00 -#> 6: 117.4 131 164.05 -``` - -A range of plots are returned (with the single summary plot shown -below). These plots can also be generated using the following `plot` -method. - -``` r -plot(estimates) -``` - -![](man/figures/unnamed-chunk-15-1.png) - -### [regional_epinow()](https://epiforecasts.io/EpiNow2/reference/regional_epinow.html) - -The `regional_epinow()` function runs the `epinow()` function across -multiple regions in an efficient manner. - -Define cases in multiple regions delineated by the region variable. - -``` r -reported_cases <- data.table::rbindlist(list( - data.table::copy(reported_cases)[, region := "testland"], - reported_cases[, region := "realland"] -)) -head(reported_cases) -#> date confirm region -#> 1: 2020-02-22 14 testland -#> 2: 2020-02-23 62 testland -#> 3: 2020-02-24 53 testland -#> 4: 2020-02-25 97 testland -#> 5: 2020-02-26 93 testland -#> 6: 2020-02-27 78 testland -``` - -Calling `regional_epinow()` runs the `epinow()` on each region in turn -(or in parallel depending on the settings used). Here we switch to using -a weekly random walk rather than the full Gaussian process model giving -us piecewise constant estimates by week. - -``` r -estimates <- regional_epinow( - reported_cases = reported_cases, - generation_time = generation_time_opts(example_generation_time), - delays = delay_opts(example_incubation_period + reporting_delay), - rt = rt_opts(prior = list(mean = 2, sd = 0.2), rw = 7), - gp = NULL, - stan = stan_opts(cores = 4, warmup = 250, samples = 1000) -) -#> INFO [2023-10-26 15:41:15] Producing following optional outputs: regions, summary, samples, plots, latest -#> INFO [2023-10-26 15:41:15] Reporting estimates using data up to: 2020-04-21 -#> INFO [2023-10-26 15:41:15] No target directory specified so returning output -#> INFO [2023-10-26 15:41:15] Producing estimates for: testland, realland -#> INFO [2023-10-26 15:41:15] Regions excluded: none -#> INFO [2023-10-26 15:42:07] Completed estimates for: testland -#> INFO [2023-10-26 15:42:55] Completed estimates for: realland -#> INFO [2023-10-26 15:42:55] Completed regional estimates -#> INFO [2023-10-26 15:42:55] Regions with estimates: 2 -#> INFO [2023-10-26 15:42:55] Regions with runtime errors: 0 -#> INFO [2023-10-26 15:42:55] Producing summary -#> INFO [2023-10-26 15:42:55] No summary directory specified so returning summary output -#> INFO [2023-10-26 15:42:55] No target directory specified so returning timings -``` - -Results from each region are stored in a `regional` list with across -region summary measures and plots stored in a `summary` list. All -results can be set to be internally saved by setting the `target_folder` -and `summary_dir` arguments. Each region can be estimated in parallel -using the `{future}` package (when in most scenarios `cores` should be -set to 1). For routine use each MCMC chain can also be run in parallel -(with `future` = TRUE) with a time out (`max_execution_time`) allowing -for partial results to be returned if a subset of chains is running -longer than expected. See the documentation for the `{future}` package -for details on nested futures. - -Summary measures that are returned include a table formatted for -reporting (along with raw results for further processing). Futures -updated will extend the S3 methods used above to smooth access to this -output. - -``` r -knitr::kable(estimates$summary$summarised_results$table) -``` - -| Region | New confirmed cases by infection date | Expected change in daily cases | Effective reproduction no. | Rate of growth | Doubling/halving time (days) | -|:---------|:--------------------------------------|:-------------------------------|:---------------------------|:------------------------|:-----------------------------| -| realland | 2141 (1156 – 3975) | Likely decreasing | 0.86 (0.63 – 1.1) | -0.031 (-0.092 – 0.029) | -22 (24 – -7.5) | -| testland | 2084 (1161 – 3800) | Likely decreasing | 0.85 (0.63 – 1.1) | -0.035 (-0.091 – 0.024) | -20 (29 – -7.6) | - -A range of plots are again returned (with the single summary plot shown -below). - -``` r -estimates$summary$summary_plot -``` - -![](man/figures/unnamed-chunk-19-1.png) +A simple example of using the package to estimate a national Rt for +Covid-19 can be found +[here](https://gist.github.com/seabbs/163d0f195892cde685c70473e1f5e867). -### Reporting templates +
+
+ +Reporting templates + Rmarkdown templates are provided in the package (`templates`) for semi-automated reporting of estimates. If using these templates to @@ -421,12 +238,14 @@ report your results please highlight our [limitations](https://doi.org/10.12688/wellcomeopenres.16006.1) as these are key to understanding the results from `{EpiNow2}` . +
+ ## Contributing -File an issue [here](https://github.com/epiforecasts/EpiNow2/issues) if -you have identified an issue with the package. Please note that due to -operational constraints priority will be given to users informing -government policy or offering methodological insights. We welcome all -contributions, in particular those that improve the approach or the -robustness of the code base. We also welcome additions and extensions to -the underlying model either in the form of options or improvements. +We welcome all contributions. If you have identified an issue with the +package, you can file an issue +[here](https://github.com/epiforecasts/EpiNow2/issues). We also welcome +additions and extensions to the underlying model either in the form of +options or improvements. If you wish to contribute in any form, please +follow the [package contributing +guide](https://github.com/epiforecasts/EpiNow2/blob/main/.github/CONTRIBUTING.md).