Clarify propagating truncation uncertainty

NEWS.md

@@ -24,6 +24,7 @@
 * Updated the code in `inst/CITATION` and added a GitHub Actions workflow to auto-generate `citation.cff` so that the two citation files are always in sync with `DESCRIPTION`. By @jamesmbazam in #467, with contributions from @Bisaloo, and reviewed by @seabbs and @sbfnk.
 * Updated the documentation of the `reported_cases` argument in `estimate_infections()` and `confirm` column in the `obs` argument of `estimate_truncation()` to allow `numeric` types, not just `integer`. See #594, by @jamesmbaazam, and reviewed by @sbfnk.
 * Removed the reporting templates that were previously provided. See #604 by @jamesmbaazam, and reviewed by @sbfnk.
+* Clarified how estimated or specified uncertainty around data truncation can be passed to `epinow()`, `regional_epinow()`, and `estimate_infections()` using the `truncation` argument. By @jamesmbaazam in #644 and reviewed by @sbnfk.
 
 ## Package
 

R/estimate_infections.R

@@ -31,8 +31,11 @@
 #' details.
 #'
 #' @param truncation A call to [trunc_opts()] defining the truncation of
-#'   observed data.  Defaults to [trunc_opts()]. See [estimate_truncation()] for
-#'   an approach to estimating truncation from data.
+#' the observed data. Defaults to [trunc_opts()], i.e. no truncation.  See the
+#' [estimate_truncation()] help file for an approach to estimating this from
+#' data where the `dist` list element returned by [estimate_truncation()] is
+#' used as the `truncation` argument here, thereby propagating the uncertainty
+#' in the estimate.
 #'
 #' @param horizon Numeric, defaults to 7. Number of days into the future to
 #' forecast.

R/estimate_truncation.R

@@ -2,10 +2,12 @@
 #'
 #' @description `r lifecycle::badge("stable")`
 #' Estimates a truncation distribution from multiple snapshots of the same
-#' data source over time. This distribution can then be used in
-#' [regional_epinow()], [epinow()], and [estimate_infections()] to adjust for
-#' truncated data. See
-#' [here](https://gist.github.com/seabbs/176b0c7f83eab1a7192a25b28bbd116a)
+#' data source over time. This distribution can then be used passed to the
+#' `truncation` argument in [regional_epinow()], [epinow()], and
+#' [estimate_infections()] to adjust for truncated data and propagage the
+#' uncertainty associated with data truncation into the estimates.
+#'
+#' See [here](https://gist.github.com/seabbs/176b0c7f83eab1a7192a25b28bbd116a)
 #' for an example of using this approach on Covid-19 data in England. The
 #' functionality offered by this function is now available in a more principled
 #' manner in the [`epinowcast` R package](https://package.epinowcast.org/).
@@ -57,9 +59,11 @@
 #' @param ... Additional parameters to pass to [rstan::sampling()].
 #'
 #' @return A list containing: the summary parameters of the truncation
-#'  distribution (`dist`), the estimated CMF of the truncation distribution
-#' (`cmf`, can be used to adjusted new data), a `<data.frame>` containing the
-#' observed truncated data, latest observed data and the adjusted for
+#' distribution (`dist`), which could be passed to the `truncation` argument
+#' of [epinow()], [regional_epinow()], and [estimate_infections()], the
+#' estimated CMF of the truncation distribution (`cmf`, can be used to
+#' adjusted new data), a `<data.frame>` containing the observed truncated
+#' data, latest observed data and the adjusted for
 #' truncation observations (`obs`), a `<data.frame>` containing the last
 #' observed data (`last_obs`, useful for plotting and validation), the data
 #' used for fitting (`data`) and the fit object (`fit`).
@@ -95,6 +99,15 @@
 #' # validation plot of observations vs estimates
 #' plot(est)
 #'
+#' # Pass the truncation distribution to `epinow()`.
+#' # Note, we're using the last snapshot as the observed data as it contains
+#' # all the previous snapshots. Also, we're using the default options for
+#' # illustrative purposes only.
+#' out <- epinow(
+#'   example_truncated[[5]],
+#'   truncation = est$dist
+#' )
+#' plot(out)
 #' options(old_opts)
 estimate_truncation <- function(data, max_truncation, trunc_max = 10,
                                 trunc_dist = "lognormal",

R/opts.R

@@ -262,8 +262,11 @@ delay_opts <- function(dist = Fixed(0), ..., fixed = FALSE, tolerance = 0.001,
 #' estimate these distributions.
 #'
 #' @param dist A delay distribution or series of delay distributions reflecting
-#' the truncation generated using [dist_spec()] or [estimate_truncation()].
-#' Default is fixed distribution with maximum 0, i.e. no truncation
+#' the truncation. It can be specified using the probability distributions
+#' interface in `EpiNow2` (See `?EpiNow2::Distributions`) or estimated using
+#' [estimate_truncation()], which returns a `dist` object, suited
+#' for use here out-of-box. Default is a fixed distribution with maximum 0, i.e.
+#' no truncation.
 #' @param weight_prior Logical; if TRUE, the truncation prior will be weighted
 #'   by the number of observation data points, in doing so approximately placing
 #'   an independent prior at each time step and usually preventing the