From 9372afd175f9ec074f5babdb68b7e72bb30058d8 Mon Sep 17 00:00:00 2001 From: James Azam Date: Mon, 26 Feb 2024 12:34:41 +0000 Subject: [PATCH] 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 | 1 + R/estimate_infections.R | 10 +++++++++- R/opts.R | 11 ++++++++++- man/init_cumulative_fit.Rd | 5 ++++- man/stan_opts.Rd | 5 ++++- tests/testthat/test-opts.R | 3 +++ 6 files changed, 31 insertions(+), 4 deletions(-) create mode 100644 tests/testthat/test-opts.R diff --git a/NEWS.md b/NEWS.md index 9b9885889..ee9e7bae8 100644 --- a/NEWS.md +++ b/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 diff --git a/R/estimate_infections.R b/R/estimate_infections.R index f52cee981..b678525b7 100644 --- a/R/estimate_infections.R +++ b/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" diff --git a/R/opts.R b/R/opts.R index c4dae704f..f0c4db67b 100644 --- a/R/opts.R +++ b/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") } diff --git a/man/init_cumulative_fit.Rd b/man/init_cumulative_fit.Rd index adc6b2927..f0578bb92 100644 --- a/man/init_cumulative_fit.Rd +++ b/man/init_cumulative_fit.Rd @@ -34,7 +34,10 @@ stan models. Supported arguments are "rstan" (default) or "cmdstanr".} A stanfit object } \description{ -\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[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 diff --git a/man/stan_opts.Rd b/man/stan_opts.Rd index ea0ed150c..f911c089f 100644 --- a/man/stan_opts.Rd +++ b/man/stan_opts.Rd @@ -42,7 +42,10 @@ See \code{\link[=init_cumulative_fit]{init_cumulative_fit()}} for details. This implementation is based on the approach taken in \href{https://github.com/ImperialCollegeLondon/epidemia/}{epidemia} authored by -James Scott.} +James Scott. + +This argument is deprecated and the default (NULL) will be used from +version 2.0.0.} \item{return_fit}{Logical, defaults to TRUE. Should the fit stan model be returned.} diff --git a/tests/testthat/test-opts.R b/tests/testthat/test-opts.R new file mode 100644 index 000000000..d53e5fdd4 --- /dev/null +++ b/tests/testthat/test-opts.R @@ -0,0 +1,3 @@ +test_that("deprecated arguments are caught", { + expect_deprecated(stan_opts(init_fit = "cumulative")) +}) \ No newline at end of file