Deprecate init_cumulative_fit() (#572)

* Point out deprecation of "cumulative" option

* Deprecate init_cumulative_fit function

* Add NEWS item

* Add PR number to NEWS item

* Linting: trailing white spaces

* Change versions

* Add deprecation warning for init_fit  argument

* Move deprecation statement to separate paragraph

* Add deprecation test

* Add reviewer

* Move deprecation warning to where the argument is called

* Revise deprecation message

* Don't use explicit namespacing

* Throw deprecation warning if init_fit argument isn't NULL

* Fix test

NEWS.md

@@ -8,6 +8,7 @@
 * 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.
 * A new `simulate_infections` function has been added that can be used to simulate from the model from given initial conditions and parameters. By @sbfnk in #557 and reviewed by @jamesmbaazam.
+* The function `init_cumulative_fit()` has been deprecated. By @jamesmbaazam in #541 and reviewed by @sbfnk.
 
 ## Documentation
 

R/estimate_infections.R

@@ -285,7 +285,10 @@ estimate_infections <- function(reported_cases,
 
 #' Generate initial conditions by fitting to cumulative cases
 #'
-#' @description `r lifecycle::badge("experimental")`
+#' @description `r lifecycle::badge("deprecated")`
+#'
+#' This function has been deprecated and will be removed in version 2.0.0.
+#'
 #' Fits a model to cumulative cases. This may be a useful approach to
 #' initialising a full model fit for certain data sets where the sampler gets
 #' stuck or cannot easily be initialised as fitting to cumulative cases changes
@@ -315,6 +318,11 @@ estimate_infections <- function(reported_cases,
 init_cumulative_fit <- function(args, samples = 50, warmup = 50,
                                 id = "init", verbose = FALSE,
                                 backend = "rstan") {
+  deprecate_warn(
+    when = "1.5.0",
+    what = "init_cumulative_fit()",
+    details = "The function will be removed completely in version 2.0.0."
+  )
   futile.logger::flog.debug(
     "%s: Fitting to cumulative data to initialise chains", id,
     name = "EpiNow2.epinow.estimate_infections.fit"

R/opts.R

@@ -853,13 +853,16 @@ rstan_opts <- function(object = NULL,
 #' national level fit to parametrise regional level fits. Optionally a
 #' character string can be passed with the currently supported option being
 #' "cumulative". This fits the model to cumulative cases and may be useful for
-#'  certain data sets where the sampler gets stuck or struggles to initialise.
+#' certain data sets where the sampler gets stuck or struggles to initialise.
 #' See [init_cumulative_fit()] for details.
 #'
 #' This implementation is based on the approach taken in
 #' [epidemia](https://github.com/ImperialCollegeLondon/epidemia/) authored by
 #' James Scott.
 #'
+#' This argument is deprecated and the default (NULL) will be used from
+#' version 2.0.0.
+#'
 #' @param return_fit Logical, defaults to TRUE. Should the fit stan model be
 #' returned.
 #'
@@ -915,6 +918,12 @@ stan_opts <- function(object = NULL,
     opts <- c(opts, stan_vb_opts(samples = samples, ...))
   }
   if (!is.null(init_fit)) {
+    deprecate_warn(
+      when = "1.5.0",
+      what = "stan_opts(init_fit)",
+      details = paste("This argument is deprecated and the default (NULL)",
+                      "will be used from version 2.0.0.")
+    )
     if (is.character(init_fit)) {
       init_fit <- arg_match(init_fit, values = "cumulative")
     }

tests/testthat/test-opts.R

@@ -0,0 +1,3 @@
+test_that("deprecated arguments are caught", {
+  expect_deprecated(stan_opts(init_fit = "cumulative"))
+})