From 9cc80898eba33acf02d01c784beaa866a841d4e3 Mon Sep 17 00:00:00 2001 From: Adam Howes Date: Tue, 15 Oct 2024 12:11:16 +0100 Subject: [PATCH] Issue #132: Updates to `README` (#387) * We don't have released versions! * Likewise need to remove this * Add citation information * Add vignettes and CAUTION * Better text * Render * Revert warning and add quickstart section * Code fold citation * Remove enforced breaks --- README.Rmd | 56 ++++++++++++++++++++---------------- README.md | 83 +++++++++++++++++++++++++++++++++++++++--------------- 2 files changed, 91 insertions(+), 48 deletions(-) diff --git a/README.Rmd b/README.Rmd index 563f9b1ed..6d9b2b98b 100644 --- a/README.Rmd +++ b/README.Rmd @@ -19,16 +19,14 @@ knitr::opts_chunk$set( [![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://www.tidyverse.org/lifecycle/#experimental) [![R-CMD-check](https://github.com/epinowcast/epidist/actions/workflows/R-CMD-check.yaml/badge.svg?branch=main)](https://github.com/epinowcast/epidist/actions/workflows/R-CMD-check.yaml) [![Codecov test coverage](https://codecov.io/gh/epinowcast/epidist/branch/main/graph/badge.svg)](https://app.codecov.io/gh/epinowcast/epidist) -
[![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/422611952.svg)](https://zenodo.org/badge/latestdoi/422611952) -*Warning: This package is a prototype and is under active development. Breaking changes are likely.* +*Warning! This package is a prototype and is under active development. Breaking changes are likely.* ## Summary @@ -36,6 +34,14 @@ license](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/ cat(gsub("\n[ ]+"," ",packageDescription("epidist")$Description)) ``` +## 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 @@ -58,25 +64,25 @@ remotes::install_github( ) ``` -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, eval = FALSE} -remotes::install_github( - "epinowcast/epidist", dependencies = TRUE, ref = "v0.2.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 -If you wish to do model fitting and nowcasting, 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/). The Stan team provides instructions in the [_Getting started with +If you wish to do model fitting, 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/). 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, eval = FALSE} -# if you not yet installed `epinowcast`, or you installed it without `Suggests` dependencies +# if you not yet installed `epidist`, or you installed it without `Suggests` dependencies install.packages("cmdstanr", repos = c("https://mc-stan.org/r-packages/", getOption("repos"))) # once `cmdstanr` is installed: cmdstanr::install_cmdstan() @@ -125,12 +131,23 @@ We welcome contributions and new contributors! We particularly appreciate help o ## Citation -If making use of our methodology or the methodology on which ours is based, please cite the relevant papers from our [model outline](https://epidist.epinowcast.org/articles/model.html). If you use `epidist` in your work, please consider citing it with `citation("epidist")`. +If you use `epidist` in your work, please consider citing it using `citation("epidist")`. -## Contributors +
Package citation information +```{r} +citation("epidist") +``` + +
+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://arxiv.org/abs/2405.08841) by Charniga *et al.* (2024) + +## Contributors @@ -140,36 +157,25 @@ All contributions to this project are gratefully acknowledged using the [`allcon ### Code - seabbs, athowes, parksw3, damonbayer, medewitt - - ### Issue Authors - kgostic, TimTaylor, jamesmbaazam - - ### Issue Contributors - pearsonca, sbfnk, SamuelBrand1, zsusswein - - - - diff --git a/README.md b/README.md index f75d029d6..a9b13c9dc 100644 --- a/README.md +++ b/README.md @@ -8,17 +8,15 @@ experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](h [![R-CMD-check](https://github.com/epinowcast/epidist/actions/workflows/R-CMD-check.yaml/badge.svg?branch=main)](https://github.com/epinowcast/epidist/actions/workflows/R-CMD-check.yaml) [![Codecov test coverage](https://codecov.io/gh/epinowcast/epidist/branch/main/graph/badge.svg)](https://app.codecov.io/gh/epinowcast/epidist) -
[![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/422611952.svg)](https://zenodo.org/badge/latestdoi/422611952) -*Warning: This package is a prototype and is under active development. +*Warning! This package is a prototype and is under active development. Breaking changes are likely.* ## Summary @@ -32,6 +30,19 @@ truncation, interval censoring, and dynamical biases. Despite their importance, these issues are frequently overlooked, often resulting in biased conclusions. +## 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
@@ -56,27 +67,20 @@ remotes::install_github( ) ``` -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( - "epinowcast/epidist", dependencies = TRUE, ref = "v0.2.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 -If you wish to do model fitting and nowcasting, you will need to install +If you wish to do model fitting, 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/). The Stan team @@ -86,7 +90,7 @@ vignette, with other details and support at the [package site](https://mc-stan.org/cmdstanr/), but the brief version is: ``` r -# if you not yet installed `epinowcast`, or you installed it without `Suggests` dependencies +# if you not yet installed `epidist`, or you installed it without `Suggests` dependencies install.packages("cmdstanr", repos = c("https://mc-stan.org/r-packages/", getOption("repos"))) # once `cmdstanr` is installed: cmdstanr::install_cmdstan() @@ -147,12 +151,45 @@ request](https://github.com/epinowcast/epidist/pulls). ## Citation -If making use of our methodology or the methodology on which ours is -based, please cite the relevant papers from our [model -outline](https://epidist.epinowcast.org/articles/model.html). If you use -`epidist` in your work, please consider citing it with +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 for infectious diseases_. + doi:10.5281/zenodo.5637165 . + +A BibTeX entry for LaTeX users is + + @Manual{, + title = {epidist: Estimate epidemiological delay distributions for infectious diseases}, + author = {{Adam Howes} and Sang Woo Park and {Sam Abbott}}, + year = {NULL}, + doi = {10.5281/zenodo.5637165}, + } +``` + +
+ +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://arxiv.org/abs/2405.08841) by Charniga *et + al.* (2024) + ## Contributors