rename and expand doc

epiforecasts · sbfnk · Sep 8, 2023 · Sep 7, 2023 · Sep 8, 2023 · Sep 8, 2023
commit 7c16faf33cb0d704dbf2cbcf32936abfb2566b10
diff --git a/NEWS.md b/NEWS.md
@@ -29,7 +29,7 @@ This release is in development. For a stable release install 1.3.5 from CRAN.
 * Added content to the vignette for the estimate_truncation model. By @sbfnk in #439 and reviewed by @seabbs.
 * Added a feature to the `estimate_truncation` to allow it to be applied to time series that are shorter than the truncation max. By @sbfnk in #438 and reviewed by @seabbs.
 * Changed the `estimate_truncation` to use the `dist_spec` interface, deprecating existing options `max_trunc` and `trunc_dist`. By @sbfnk in #448 reviewed by @seabbs.
-* Added a `weigh_prior_delays` argument to the main functions, allowing the users to choose whether to weigh delay priors by the number of data points or not. By @sbfnk in #450 and reviewed by @seabbs.
+* Added a `weigh_delay_priors` argument to the main functions, allowing the users to choose whether to weigh delay priors by the number of data points or not. By @sbfnk in #450 and reviewed by @seabbs.
 
 ## Documentation
 

diff --git a/R/estimate_infections.R b/R/estimate_infections.R
@@ -35,8 +35,9 @@
 #' @param horizon Numeric, defaults to 7. Number of days into the future to
 #' forecast.
 #'
-#' @param weigh_prior_delays Logical. If TRUE (default), all delay distribution
-#' priors will be weighted by the number of observation data points, usually
+#' @param weigh_delay_priors Logical. If TRUE (default), all delay distribution
+#' priors 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 posteriors from shifting. If FALSE, no weight will be applied,
 #' i.e. delay distributions will be treated as a single parameters.
 #'
@@ -251,7 +252,7 @@ estimate_infections <- function(reported_cases,
                                 CrIs = c(0.2, 0.5, 0.9),
                                 filter_leading_zeros = TRUE,
                                 zero_threshold = Inf,
-                                weigh_prior_delays = TRUE,
+                                weigh_delay_priors = TRUE,
                                 id = "estimate_infections",
                                 verbose = interactive()) {
   set_dt_single_thread()
@@ -319,7 +320,7 @@ estimate_infections <- function(reported_cases,
     delay = delays,
     trunc = truncation,
     weight = ifelse(
-      weigh_prior_delays, data$t - data$seeding_time - data$horizon, 1
+      weigh_delay_priors, data$t - data$seeding_time - data$horizon, 1
     )
   ))
 

diff --git a/R/estimate_secondary.R b/R/estimate_secondary.R
@@ -40,10 +40,12 @@
 #' use for estimation but not to fit to at the beginning of the time series.
 #' This must be less than the number of observations.
 #'
-#' @param weigh_prior_delays Logical. If TRUE, all delay distribution
-#' priors will be weighted by the number of observation data points, usually
+#' @param weigh_delay_priors Logical. If TRUE, all delay distribution priors
+#' 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 posteriors from shifting. If FALSE (default), no weight will
-#' be applied, i.e. delay distributions will be treated as a single parameters.
+#' be applied, i.e. delay distributions will be treated as a single
+#' parameters.
 #'
 #' @param verbose Logical, should model fitting progress be returned. Defaults
 #' to `interactive()`.
@@ -143,7 +145,7 @@ estimate_secondary <- function(reports,
                                CrIs = c(0.2, 0.5, 0.9),
                                priors = NULL,
                                model = NULL,
-                               weigh_prior_delays = FALSE,
+                               weigh_delay_priors = FALSE,
                                verbose = interactive(),
                                ...) {
   reports <- data.table::as.data.table(reports)
@@ -166,7 +168,7 @@ estimate_secondary <- function(reports,
   data <- c(data, create_stan_delays(
     delay = delays,
     trunc = truncation,
-    weight = ifelse(weigh_prior_delays, data$t, 1)
+    weight = ifelse(weigh_delay_priors, data$t, 1)
   ))
 
   # observation model data

diff --git a/R/estimate_truncation.R b/R/estimate_truncation.R
@@ -47,11 +47,13 @@
 #' @param model A compiled stan model to override the default model. May be
 #' useful for package developers or those developing extensions.
 #'
-#' @param weigh_prior_delays Logical. If TRUE, all delay distribution
-#' priors will be weighted by the number of observation data points, usually
+#' @param weigh_delay_priors Logical. If TRUE, all delay distribution priors
+#' 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 posteriors from shifting. If FALSE (default), no weight will
-#' be applied, i.e. delay distributions will be treated as a single parameters.
-#
+#' be applied, i.e. delay distributions will be treated as a single
+#' parameters.
+#'
 #' @param verbose Logical, should model fitting progress be returned.
 #'
 #' @param ... Additional parameters to pass to `rstan::sampling`.
@@ -143,7 +145,7 @@ estimate_truncation <- function(obs, max_truncation, trunc_max = 10,
                                 ),
                                 model = NULL,
                                 CrIs = c(0.2, 0.5, 0.9),
-                                weigh_prior_delays = FALSE,
+                                weigh_delay_priors = FALSE,
                                 verbose = TRUE,
                                 ...) {
 
@@ -224,7 +226,7 @@ estimate_truncation <- function(obs, max_truncation, trunc_max = 10,
 
   data <- c(data, create_stan_delays(
     trunc = truncation,
-    weight = ifelse(weigh_prior_delays, data$t, 1)
+    weight = ifelse(weigh_delay_priors, data$t, 1)
   ))
 
   ## convert to integer

diff --git a/man/estimate_infections.Rd b/man/estimate_infections.Rd
diff --git a/man/estimate_secondary.Rd b/man/estimate_secondary.Rd
diff --git a/man/estimate_truncation.Rd b/man/estimate_truncation.Rd
diff --git a/tests/testthat/test-estimate_secondary.R b/tests/testthat/test-estimate_secondary.R
@@ -101,14 +101,14 @@ test_that("forecast_secondary can return values from simulated data and plot
   expect_error(plot(inc_preds, new_obs = cases, from = "2020-05-01"), NA)
 })
 
-test_that("estimate_secondary works with weigh_prior_delays = TRUE", {
+test_that("estimate_secondary works with weigh_delay_priors = TRUE", {
   delays <- dist_spec(
     mean = 2.5, mean_sd = 0.5, sd = 0.47, sd_sd = 0.25, max = 30
   )
   inc_weigh <- estimate_secondary(
     cases[1:60], delays = delays,
     obs = obs_opts(scale = list(mean = 0.2, sd = 0.2), week_effect = FALSE),
-    weigh_prior_delays = TRUE, verbose = FALSE
+    weigh_delay_priors = TRUE, verbose = FALSE
   )
   expect_s3_class(inc_weigh, "estimate_secondary")
 })