rename simulate_infections -> forecast_infections (#544)

* rename simulate_infections -> forecast_infections

* Apply suggestions from code review

Co-authored-by: Sam Abbott <[email protected]>

* fix typo

---------

Co-authored-by: Sam Abbott <[email protected]>

NAMESPACE

@@ -48,6 +48,7 @@ export(extract_CrIs)
 export(extract_inits)
 export(extract_stan_param)
 export(fix_dist)
+export(forecast_infections)
 export(forecast_secondary)
 export(gamma_dist_def)
 export(generation_time_opts)

NEWS.md

@@ -6,6 +6,7 @@
 * The utility function `update_list()` has been deprecated in favour of `utils::modifyList()` because it comes with an installation of R. By @jamesmbaazam in #491 and reviewed by @seabbs.
 * The `fixed` argument to `dist_spec` has been deprecated and replaced by a `fix_dist()` function. By @sbfnk in #503 and reviewed by @seabbs.
 * Updated `estimate_infections()` so that rather than imputing missing data, it now skips these data points in the likelihood. This is a breaking change as it alters the behaviour of the model when dates are missing from a time series but are known to be zero. We recommend that users check their results when updating to this version but expect this to in most cases improve performance. By @seabbs in #528 and reviewed by @sbfnk.
+* `simulate_infections` has been renamed to `forecast_infections` in line with `simulate_secondary` and `forecast_secondary`. The terminology is: a forecast is done from a fit to existing data, a simulation from first principles. By @sbfnk in #544 and reviewed by @seabbs.
 
 ## Documentation
 
@@ -168,8 +169,8 @@ reporting delay and the generation time. These are based on an implementation in
 
 ## Deprecated features
 
-* `simulate_cases()` and `forecast_infections()` have been deprecated and have been removed. These functions depend on `EpiSoon` which itself is archived and near equivalent functionality is available within `EpiNow2` and in other packages (@seabbs).
-* Functions supporting secondary forecasting using `forecast_infections()` (i.e in `epinow())
+* `simulate_cases()` and `simulate_infections()` have been deprecated and have been removed. These functions depend on `EpiSoon` which itself is archived and near equivalent functionality is available within `EpiNow2` and in other packages (@seabbs).
+* Functions supporting secondary forecasting using `simulate_infections()` (i.e in `epinow())
 have been removed along with the arguments that supported them (@seabbs).
 * `global_map()`, `country_map()`, and `theme_map()` have all been deprecated and have been removed. These functions were used to support reporting of reproduction number
 estimates and are considered out of scope for `EpiNow2`. If finding useful contacting the

R/epinow.R

@@ -24,7 +24,7 @@
 #'   summarising results and reporting errors if they have occurred.
 #' @author Sam Abbott
 #' @export
-#' @seealso [estimate_infections()] [simulate_infections()] [regional_epinow()]
+#' @seealso [estimate_infections()] [forecast_infections()] [regional_epinow()]
 #' @inheritParams setup_target_folder
 #' @inheritParams estimate_infections
 #' @inheritParams setup_default_logging

R/estimate_infections.R

@@ -51,7 +51,7 @@
 #' samples, data used to fit the model, and the fit object itself.
 #'
 #' @author Sam Abbott
-#' @seealso [epinow()] [regional_epinow()] [simulate_infections()]
+#' @seealso [epinow()] [regional_epinow()] [forecast_infections()]
 #' [estimate_truncation()]
 #' @inheritParams create_stan_args
 #' @inheritParams create_stan_data

R/simulate_infections.R

@@ -1,4 +1,22 @@
-#' Simulate infections using a given trajectory of the time-varying
+#' Deprecated; use [forecast_infections()] instead
+#'
+#' Calling this function passes all arguments to [forecast_infections()]
+#' @description `r lifecycle::badge("deprecated")`
+#' @param ... Arguments to be passed to [forecast_infections()]
+#' @return the result of [forecast_infections()]
+#' @export
+simulate_infections <- function(...) {
+    deprecate_warn(
+      "2.0.0",
+      "simulate_infections()",
+      "forecast_infections()",
+      "A new [simulate_infections()] function for simulating from given ",
+      "parameters is planned for implementation in the future."
+    )
+   forecast_infections(...)
+}
+
+#' Forecast infections from a given fit and trajectory of the time-varying
 #' reproduction number
 #'
 #' @description `r lifecycle::badge("stable")`
@@ -63,7 +81,7 @@
 #'
 #' # update Rt trajectory and simulate new infections using it
 #' R <- c(rep(NA_real_, 26), rep(0.5, 10), rep(0.8, 7))
-#' sims <- simulate_infections(est, R)
+#' sims <- forecast_infections(est, R)
 #' plot(sims)
 #'
 #' # with a data.frame input of samples
@@ -74,7 +92,7 @@
 #'   ),
 #'   value = R
 #' )
-#' sims <- simulate_infections(est, R_dt)
+#' sims <- forecast_infections(est, R_dt)
 #' plot(sims)
 #'
 #' #' # with a data.frame input of samples
@@ -83,12 +101,12 @@
 #'  .(date, sample, value)][sample <= 1000][date <= "2020-04-10"
 #' ]
 #' R_samples <- R_samples[date >= "2020-04-01", value := 1.1]
-#' sims <- simulate_infections(est, R_samples)
+#' sims <- forecast_infections(est, R_samples)
 #' plot(sims)
 #'
 #' options(old_opts)
 #' }
-simulate_infections <- function(estimates,
+forecast_infections <- function(estimates,
                                 R = NULL,
                                 model = NULL,
                                 samples = NULL,

R/utilities.R

@@ -163,7 +163,7 @@ allocate_delays <- function(delay_var, no_delays) {
 #'
 #' @description `r lifecycle::badge("stable")`
 #' Allocate missing parameters to be empty two dimensional arrays. Used
-#' internally by [simulate_infections()].
+#' internally by [forecast_infections()].
 #' @param data A list of parameters
 #' @param params A character vector of parameters to allocate to
 #' empty if missing.
@@ -423,7 +423,7 @@ set_dt_single_thread <- function() {
 
 #' @importFrom stats glm median na.omit pexp pgamma plnorm quasipoisson rexp
 #' @importFrom lifecycle deprecate_warn
-#' @importFrom stats rlnorm rnorm rpois runif sd var rgamma
+#' @importFrom stats rlnorm rnorm rpois runif sd var rgamma pnorm
 globalVariables(
   c(
     "bottom", "cases", "confidence", "confirm", "country_code", "crps",

_pkgdown.yml

@@ -68,7 +68,7 @@ reference:
     desc: Function to estimate, simulate and forecast parameters of interest.
     contents:
       - estimate_infections
-      - simulate_infections
+      - forecast_infections
       - estimate_secondary
       - forecast_secondary
       - estimate_delay
@@ -126,7 +126,7 @@ reference:
   - title: Simulate
     desc: Functions to help with simulating data or mapping to reported cases
     contents:
-      - simulate_infections
+      - forecast_infections
       - simulate_secondary
       - adjust_infection_to_report
   - title: Data

inst/dev/recover-synthetic/rt.R

@@ -26,7 +26,7 @@ R <- c(
 )
 noisy_R <- R * rnorm(length(R), 1, 0.05)
 # update Rt trajectory and simulate new infections using it
-sims <- simulate_infections(init, R = noisy_R, samples = 10)
+sims <- forecast_infections(init, R = noisy_R, samples = 10)
 
 sim_R <- sims$summarised[variable == "R"]$median