From de267416f65ea7b9e9dbf2fdbe7957550f4ae735 Mon Sep 17 00:00:00 2001 From: jamesaazam Date: Wed, 21 Feb 2024 18:19:13 +0000 Subject: [PATCH 01/15] Point out deprecation of "cumulative" option --- R/opts.R | 6 ++++-- man/stan_opts.Rd | 4 +++- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/R/opts.R b/R/opts.R index b27a67453..f949b3e77 100644 --- a/R/opts.R +++ b/R/opts.R @@ -780,8 +780,10 @@ rstan_opts <- function(object = NULL, #' fit be used to initialise the full fit. An example scenario would be using a #' 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. +#' "cumulative". However, the "cumulative" option is being deprecated and will +#' be removed in version 2.0.0. The "cumulative" option fits the model to +#' cumulative cases and may be useful for +#' 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 diff --git a/man/stan_opts.Rd b/man/stan_opts.Rd index ea0ed150c..ec4ee3453 100644 --- a/man/stan_opts.Rd +++ b/man/stan_opts.Rd @@ -36,7 +36,9 @@ Character string or \code{stanfit} object, defaults to NULL. Should an initial fit be used to initialise the full fit. An example scenario would be using a 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 +"cumulative". However, the "cumulative" option is being deprecated and will +be removed in version 2.0.0. The "cumulative" option fits the model to +cumulative cases and may be useful for certain data sets where the sampler gets stuck or struggles to initialise. See \code{\link[=init_cumulative_fit]{init_cumulative_fit()}} for details. From d410e4eb75c985d306b40637b09470612ca75b9c Mon Sep 17 00:00:00 2001 From: jamesaazam Date: Wed, 21 Feb 2024 18:19:41 +0000 Subject: [PATCH 02/15] Deprecate init_cumulative_fit function --- R/estimate_infections.R | 10 +++++++++- man/init_cumulative_fit.Rd | 5 ++++- 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/R/estimate_infections.R b/R/estimate_infections.R index f52cee981..696a8cb2f 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") { + lifecycle::deprecate_warn( + when = "2.0.0", + what = "init_cumulative_fit()", + details = "The function will be removed completely in version 2.1.0." + ) futile.logger::flog.debug( "%s: Fitting to cumulative data to initialise chains", id, name = "EpiNow2.epinow.estimate_infections.fit" 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 From 73ec1259c61f3e49f25e393cf5f279919ba50ca6 Mon Sep 17 00:00:00 2001 From: jamesaazam Date: Wed, 21 Feb 2024 18:19:52 +0000 Subject: [PATCH 03/15] Add NEWS item --- NEWS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/NEWS.md b/NEWS.md index 9b9885889..25d9cecd3 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 # and reviewed by @. ## Documentation From 28537667d41af20ed177a899ca3420124360397d Mon Sep 17 00:00:00 2001 From: James Azam Date: Wed, 21 Feb 2024 18:22:42 +0000 Subject: [PATCH 04/15] Add PR number to NEWS item --- NEWS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/NEWS.md b/NEWS.md index 25d9cecd3..e89b3d0d0 100644 --- a/NEWS.md +++ b/NEWS.md @@ -8,7 +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 # and reviewed by @. +* The function `init_cumulative_fit()` has been deprecated. By @jamesmbaazam in #541 and reviewed by @. ## Documentation From da8a8fab7c8441791b9ffd0b2b970d61bbdf0284 Mon Sep 17 00:00:00 2001 From: jamesaazam Date: Thu, 22 Feb 2024 15:06:15 +0000 Subject: [PATCH 05/15] Linting: trailing white spaces --- R/estimate_infections.R | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/R/estimate_infections.R b/R/estimate_infections.R index 696a8cb2f..e69f97659 100644 --- a/R/estimate_infections.R +++ b/R/estimate_infections.R @@ -286,9 +286,9 @@ estimate_infections <- function(reported_cases, #' Generate initial conditions by fitting to cumulative cases #' #' @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 From 3d45933ce6f73c86eefaf589c45708741c6ff868 Mon Sep 17 00:00:00 2001 From: jamesaazam Date: Thu, 22 Feb 2024 15:18:26 +0000 Subject: [PATCH 06/15] Change versions --- R/estimate_infections.R | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/R/estimate_infections.R b/R/estimate_infections.R index e69f97659..b678525b7 100644 --- a/R/estimate_infections.R +++ b/R/estimate_infections.R @@ -318,10 +318,10 @@ estimate_infections <- function(reported_cases, init_cumulative_fit <- function(args, samples = 50, warmup = 50, id = "init", verbose = FALSE, backend = "rstan") { - lifecycle::deprecate_warn( - when = "2.0.0", + deprecate_warn( + when = "1.5.0", what = "init_cumulative_fit()", - details = "The function will be removed completely in version 2.1.0." + 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, From ae2790a249432aabdb52a01e3ce6e42f6dfd27fb Mon Sep 17 00:00:00 2001 From: jamesaazam Date: Thu, 22 Feb 2024 15:19:37 +0000 Subject: [PATCH 07/15] Add deprecation warning for init_fit argument --- R/opts.R | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/R/opts.R b/R/opts.R index f949b3e77..ddc0bba15 100644 --- a/R/opts.R +++ b/R/opts.R @@ -817,6 +817,11 @@ stan_opts <- function(object = NULL, init_fit = NULL, return_fit = TRUE, ...) { + lifecycle::deprecate_warn( + when = "1.5.0", + what = "stan_opts(init_fit)", + details = "This argument will be removed in version 2.0.0." + ) method <- arg_match(method, values = c("sampling", "vb")) backend <- arg_match(backend, values = c("rstan", "cmdstanr")) if (backend == "cmdstanr" && !requireNamespace("cmdstanr", quietly = TRUE)) { From 010b1ae761bf996d5d33bdf2112c9d7fd3eaa2ee Mon Sep 17 00:00:00 2001 From: jamesaazam Date: Thu, 22 Feb 2024 15:22:06 +0000 Subject: [PATCH 08/15] Move deprecation statement to separate paragraph --- R/opts.R | 7 ++++--- man/stan_opts.Rd | 9 +++++---- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/R/opts.R b/R/opts.R index ddc0bba15..8f1bea32c 100644 --- a/R/opts.R +++ b/R/opts.R @@ -780,9 +780,7 @@ rstan_opts <- function(object = NULL, #' fit be used to initialise the full fit. An example scenario would be using a #' national level fit to parametrise regional level fits. Optionally a #' character string can be passed with the currently supported option being -#' "cumulative". However, the "cumulative" option is being deprecated and will -#' be removed in version 2.0.0. The "cumulative" option fits the model to -#' cumulative cases and may be useful for +#' "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. #' See [init_cumulative_fit()] for details. #' @@ -790,6 +788,9 @@ rstan_opts <- function(object = NULL, #' [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. #' diff --git a/man/stan_opts.Rd b/man/stan_opts.Rd index ec4ee3453..f911c089f 100644 --- a/man/stan_opts.Rd +++ b/man/stan_opts.Rd @@ -36,15 +36,16 @@ Character string or \code{stanfit} object, defaults to NULL. Should an initial fit be used to initialise the full fit. An example scenario would be using a national level fit to parametrise regional level fits. Optionally a character string can be passed with the currently supported option being -"cumulative". However, the "cumulative" option is being deprecated and will -be removed in version 2.0.0. The "cumulative" option fits the model to -cumulative cases and may be useful for +"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. 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.} From 3964e3e98970bf38dc64d79c61ce7a40c0f5d556 Mon Sep 17 00:00:00 2001 From: jamesaazam Date: Thu, 22 Feb 2024 15:22:18 +0000 Subject: [PATCH 09/15] Add deprecation test --- tests/testthat/test-opts.R | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 tests/testthat/test-opts.R diff --git a/tests/testthat/test-opts.R b/tests/testthat/test-opts.R new file mode 100644 index 000000000..b770e6560 --- /dev/null +++ b/tests/testthat/test-opts.R @@ -0,0 +1,3 @@ +test_that("deprecated arguments are caught", { + expect_deprecated(stan_opts()) +}) \ No newline at end of file From 3c0fd778ae5e7f2e47e6aafadfc22bc25dfbf1f5 Mon Sep 17 00:00:00 2001 From: James Azam Date: Thu, 22 Feb 2024 16:56:56 +0000 Subject: [PATCH 10/15] Add reviewer --- NEWS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/NEWS.md b/NEWS.md index e89b3d0d0..ee9e7bae8 100644 --- a/NEWS.md +++ b/NEWS.md @@ -8,7 +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 @. +* The function `init_cumulative_fit()` has been deprecated. By @jamesmbaazam in #541 and reviewed by @sbfnk. ## Documentation From 9ce3ee1ec179ec9850a3a9a6c4e24b06347fc463 Mon Sep 17 00:00:00 2001 From: jamesaazam Date: Thu, 22 Feb 2024 17:05:59 +0000 Subject: [PATCH 11/15] Move deprecation warning to where the argument is called --- R/opts.R | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/R/opts.R b/R/opts.R index 8f1bea32c..3135f3095 100644 --- a/R/opts.R +++ b/R/opts.R @@ -818,11 +818,6 @@ stan_opts <- function(object = NULL, init_fit = NULL, return_fit = TRUE, ...) { - lifecycle::deprecate_warn( - when = "1.5.0", - what = "stan_opts(init_fit)", - details = "This argument will be removed in version 2.0.0." - ) method <- arg_match(method, values = c("sampling", "vb")) backend <- arg_match(backend, values = c("rstan", "cmdstanr")) if (backend == "cmdstanr" && !requireNamespace("cmdstanr", quietly = TRUE)) { @@ -852,6 +847,11 @@ stan_opts <- function(object = NULL, } if (!is.null(init_fit)) { if (is.character(init_fit)) { + lifecycle::deprecate_warn( + when = "1.5.0", + what = "stan_opts(init_fit)", + details = "This argument will be removed in version 2.0.0." + ) init_fit <- arg_match(init_fit, values = "cumulative") } opts$init_fit <- init_fit From 19355ef15f967f26c5e0cd0136b07b2314514ca4 Mon Sep 17 00:00:00 2001 From: jamesaazam Date: Thu, 22 Feb 2024 17:11:47 +0000 Subject: [PATCH 12/15] Revise deprecation message --- R/opts.R | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/R/opts.R b/R/opts.R index 3135f3095..52afdc548 100644 --- a/R/opts.R +++ b/R/opts.R @@ -850,7 +850,8 @@ stan_opts <- function(object = NULL, lifecycle::deprecate_warn( when = "1.5.0", what = "stan_opts(init_fit)", - details = "This argument will be removed in version 2.0.0." + details = paste("This argument is deprecated and the default (NULL)", + "will be used from version 2.0.0.") ) init_fit <- arg_match(init_fit, values = "cumulative") } From 313d4fd220aa2eda6da4bc0a3e4174391c8f4def Mon Sep 17 00:00:00 2001 From: jamesaazam Date: Thu, 22 Feb 2024 17:12:07 +0000 Subject: [PATCH 13/15] Don't use explicit namespacing --- R/opts.R | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/R/opts.R b/R/opts.R index 52afdc548..72f6d29fb 100644 --- a/R/opts.R +++ b/R/opts.R @@ -847,7 +847,7 @@ stan_opts <- function(object = NULL, } if (!is.null(init_fit)) { if (is.character(init_fit)) { - lifecycle::deprecate_warn( + deprecate_warn( when = "1.5.0", what = "stan_opts(init_fit)", details = paste("This argument is deprecated and the default (NULL)", From a7adc9561bd401f9bcc5ca0d29aa92ca437a20b1 Mon Sep 17 00:00:00 2001 From: jamesaazam Date: Thu, 22 Feb 2024 17:19:07 +0000 Subject: [PATCH 14/15] Throw deprecation warning if init_fit argument isn't NULL --- R/opts.R | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/R/opts.R b/R/opts.R index 72f6d29fb..01fda2452 100644 --- a/R/opts.R +++ b/R/opts.R @@ -846,13 +846,13 @@ 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)) { - 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.") - ) init_fit <- arg_match(init_fit, values = "cumulative") } opts$init_fit <- init_fit From 25a117e536ba83cf6181e2eb5c1e713bd07ea4ce Mon Sep 17 00:00:00 2001 From: jamesaazam Date: Thu, 22 Feb 2024 17:20:38 +0000 Subject: [PATCH 15/15] Fix test --- tests/testthat/test-opts.R | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/testthat/test-opts.R b/tests/testthat/test-opts.R index b770e6560..d53e5fdd4 100644 --- a/tests/testthat/test-opts.R +++ b/tests/testthat/test-opts.R @@ -1,3 +1,3 @@ test_that("deprecated arguments are caught", { - expect_deprecated(stan_opts()) + expect_deprecated(stan_opts(init_fit = "cumulative")) }) \ No newline at end of file