From 1ada66033d03e5068437ae975e546980c09281d7 Mon Sep 17 00:00:00 2001 From: Sebastian Funk Date: Fri, 22 Sep 2023 19:34:37 +0100 Subject: [PATCH] deprecate get functions for delay distributions --- R/get.R | 45 ++++++++++++++++++++++------------ R/opts.R | 10 +++----- man/generation_time_opts.Rd | 7 ++---- man/get_dist.Rd | 14 +++++------ man/get_generation_time.Rd | 9 ++++--- man/get_incubation_period.Rd | 11 ++++++--- tests/testthat/test-delays.R | 41 ++++++++++++++----------------- tests/testthat/test-get_dist.R | 19 +++----------- 8 files changed, 75 insertions(+), 81 deletions(-) diff --git a/R/get.R b/R/get.R index c865735da..7f06a9e93 100644 --- a/R/get.R +++ b/R/get.R @@ -184,10 +184,10 @@ get_regional_results <- function(regional_output, #' Get a Literature Distribution #' #' -#' @description `r lifecycle::badge("stable")` -#' Search a data frame for a distribution and return it in the format expected -#' by `delay_opts()` and the `generation_time` argument of `epinow` and -#' `estimate_infections`. +#' @description `r lifecycle::badge("deprecated")` +#' +#' This function has been deprecated. Please specify a distribution +#' using `dist_spec` instead #' #' @param data A `data.table` in the format of `generation_times`. #' @@ -203,12 +203,13 @@ get_regional_results <- function(regional_output, #' @return A list defining a distribution #' #' @author Sam Abbott +#' @seealso dist_spec #' @export -#' @examples -#' get_dist( -#' EpiNow2::generation_times, disease = "SARS-CoV-2", source = "ganyani" -#' ) get_dist <- function(data, disease, source, max_value = 15, fixed = FALSE) { + lifecycle::deprecate_warn( + "2.0.0", "get_dist()", "dist_spec()", + "The function will be removed completely in version 2.1.0." + ) target_disease <- disease target_source <- source data <- data[disease == target_disease][source == target_source] @@ -219,19 +220,25 @@ get_dist <- function(data, disease, source, max_value = 15, fixed = FALSE) { } return(do.call(dist_spec, dist)) } -#' Get a Literature Distribution for the Generation Time +#' Get a Literature Distribution for the Generation Time +#' +#' @description `r lifecycle::badge("deprecated")` #' -#' @description `r lifecycle::badge("stable")` #' Extracts a literature distribution from `generation_times`. +#' This function has been deprecated. Please specify a distribution +#' using `dist_spec` instead #' #' @inheritParams get_dist #' @inherit get_dist #' @export +#' @seealso dist_spec #' @author Sam Abbott -#' @examples -#' get_generation_time(disease = "SARS-CoV-2", source = "ganyani") get_generation_time <- function(disease, source, max_value = 15, fixed = FALSE) { + lifecycle::deprecate_warn( + "2.0.0", "get_generation_time()", "dist_spec()", + "The function will be removed completely in version 2.1.0." + ) dist <- get_dist(EpiNow2::generation_times, disease = disease, source = source, max_value = max_value, fixed = fixed @@ -241,17 +248,23 @@ get_generation_time <- function(disease, source, max_value = 15, } #' Get a Literature Distribution for the Incubation Period #' -#' @description `r lifecycle::badge("stable")` -#' Extracts a literature distribution from `incubation_periods`. +#' @description `r lifecycle::badge("deprecated")` +#' +#' Extracts a literature distribution from `generation_times`. +#' This function has been deprecated. Please specify a distribution +#' using `dist_spec` instead #' #' @inheritParams get_dist #' @inherit get_dist #' @author Sam Abbott #' @export -#' @examples -#' get_incubation_period(disease = "SARS-CoV-2", source = "lauer") +#' @seealso dist_spec get_incubation_period <- function(disease, source, max_value = 15, fixed = FALSE) { + lifecycle::deprecate_warn( + "2.0.0", "get_incubation_period()", "dist_spec()", + "The function will be removed completely in version 2.1.0." + ) dist <- get_dist(EpiNow2::incubation_periods, disease = disease, source = source, max_value = max_value, fixed = fixed diff --git a/R/opts.R b/R/opts.R index e71b7a71b..9cd576d79 100644 --- a/R/opts.R +++ b/R/opts.R @@ -1,13 +1,10 @@ #' Generation Time Distribution Options #' #' @description `r lifecycle::badge("stable")` -#' Returns generation time parameters in a format for lower level model use. The -#' generation time can either be given as a \code{disease} and \code{source} to -#' be passed to [get_generation_time], or as parameters of a distribution to be -#' passed to [dist_spec]. +#' Returns generation time parameters in a format for lower level model use. #' #' @param dist A delay distribution or series of delay distributions generated -#' using [dist_spec()] or [get_generation_time()]. If no distribution is given +#' using [dist_spec()]. If no distribution is given #' a fixed generation time of 1 will be assumed. #' #' @param ... deprecated; use `dist` instead @@ -89,8 +86,7 @@ generation_time_opts <- function(dist = dist_spec(mean = 1), ..., if (deprecated_options_given) { warning( "The generation time distribution must be given to ", - "`generation_time_opts` using a call to either ", - "`dist_spec` or `get_generation_time`. ", + "`generation_time_opts` using a call to `dist_spec`. ", "This behaviour has changed from previous versions of `EpiNow2` and ", "any code using it may need to be updated as any other ways of ", "specifying the generation time are deprecated and will be removed in ", diff --git a/man/generation_time_opts.Rd b/man/generation_time_opts.Rd index 4eef0a9b6..686686842 100644 --- a/man/generation_time_opts.Rd +++ b/man/generation_time_opts.Rd @@ -16,7 +16,7 @@ generation_time_opts( } \arguments{ \item{dist}{A delay distribution or series of delay distributions generated -using \code{\link[=dist_spec]{dist_spec()}} or \code{\link[=get_generation_time]{get_generation_time()}}. If no distribution is given +using \code{\link[=dist_spec]{dist_spec()}}. If no distribution is given a fixed generation time of 1 will be assumed.} \item{...}{deprecated; use \code{dist} instead} @@ -38,10 +38,7 @@ A list summarising the input delay distributions. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Returns generation time parameters in a format for lower level model use. The -generation time can either be given as a \code{disease} and \code{source} to -be passed to \link{get_generation_time}, or as parameters of a distribution to be -passed to \link{dist_spec}. +Returns generation time parameters in a format for lower level model use. } \examples{ # default settings with a fixed generation time of 1 diff --git a/man/get_dist.Rd b/man/get_dist.Rd index d579a10fe..b50fe5aad 100644 --- a/man/get_dist.Rd +++ b/man/get_dist.Rd @@ -22,15 +22,13 @@ as fixed values (vs with uncertainty)?} A list defining a distribution } \description{ -\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Search a data frame for a distribution and return it in the format expected -by \code{delay_opts()} and the \code{generation_time} argument of \code{epinow} and -\code{estimate_infections}. +\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. Please specify a distribution +using \code{dist_spec} instead } -\examples{ -get_dist( - EpiNow2::generation_times, disease = "SARS-CoV-2", source = "ganyani" -) +\seealso{ +dist_spec } \author{ Sam Abbott diff --git a/man/get_generation_time.Rd b/man/get_generation_time.Rd index 8d5474c6f..bcbef7dcc 100644 --- a/man/get_generation_time.Rd +++ b/man/get_generation_time.Rd @@ -20,11 +20,14 @@ as fixed values (vs with uncertainty)?} A list defining a distribution } \description{ -\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} + Extracts a literature distribution from \code{generation_times}. +This function has been deprecated. Please specify a distribution +using \code{dist_spec} instead } -\examples{ -get_generation_time(disease = "SARS-CoV-2", source = "ganyani") +\seealso{ +dist_spec } \author{ Sam Abbott diff --git a/man/get_incubation_period.Rd b/man/get_incubation_period.Rd index 6ac1a5cf4..0e5df6f60 100644 --- a/man/get_incubation_period.Rd +++ b/man/get_incubation_period.Rd @@ -20,11 +20,14 @@ as fixed values (vs with uncertainty)?} A list defining a distribution } \description{ -\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Extracts a literature distribution from \code{incubation_periods}. +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} + +Extracts a literature distribution from \code{generation_times}. +This function has been deprecated. Please specify a distribution +using \code{dist_spec} instead } -\examples{ -get_incubation_period(disease = "SARS-CoV-2", source = "lauer") +\seealso{ +dist_spec } \author{ Sam Abbott diff --git a/tests/testthat/test-delays.R b/tests/testthat/test-delays.R index a7917125a..fee894a15 100644 --- a/tests/testthat/test-delays.R +++ b/tests/testthat/test-delays.R @@ -34,29 +34,6 @@ test_that("generation times can be specified in different ways", { ), digits = 2), c(0.02, 0.11, 0.22, 0.30, 0.35) ) - expect_equal( - round(test_stan_delays( - generation_time = generation_time_opts( - get_generation_time( - disease = "SARS-CoV-2", source = "ganyani", - max = 10, fixed = TRUE - ) - ), - params = delay_params - ), digits = 2), - c(0.18, 0.20, 0.17, 0.13, 0.10, 0.07, 0.05, 0.04, 0.03, 0.02) - ) - expect_equal( - round(test_stan_delays( - generation_time = generation_time_opts( - get_generation_time( - disease = "SARS-CoV-2", source = "ganyani", max = 10 - ) - ), - params = delay_params - ), digits = 2), - c(3.64, 0.71, 3.08, 0.77, 10.00) - ) }) test_that("delay parameters can be specified in different ways", { @@ -136,4 +113,22 @@ test_that("deprecated arguments are caught", { params = delay_params ), "deprecated" ) + expect_warning( + test_stan_delays( + generation_time = generation_time_opts( + get_generation_time( + disease = "SARS-CoV-2", source = "ganyani", + ) + ), + ), "deprecated" + ) + expect_warning( + test_stan_delays( + delays = delay_opts( + get_incubation_period( + disease = "SARS-CoV-2", source = "lauer" + ) + ), + ), "deprecated" + ) }) diff --git a/tests/testthat/test-get_dist.R b/tests/testthat/test-get_dist.R index 0785ebd2f..5ab7a4768 100644 --- a/tests/testthat/test-get_dist.R +++ b/tests/testthat/test-get_dist.R @@ -1,18 +1,7 @@ -test_that("get_dist returns distributional definition data in the format expected by EpiNow2", { +test_that("get_dist is deprecated", { data <- data.table::data.table(mean = 1, mean_sd = 1, sd = 1, sd_sd = 1, source = "test", disease = "test", dist = "gamma") - dist <- get_dist(data, disease = "test", source = "test") - expect_equal( - dist[c("mean_mean", "mean_sd", "sd_mean", "sd_sd", "max")], - list(mean_mean = array(1), mean_sd = array(1), - sd_mean = array(1), sd_sd = array(1), max = array(15L)) - ) -}) - -test_that("get_dist returns distributional definition data in the format expected by EpiNow2 with no uncertainty", { - data <- data.table::data.table(mean = 1, mean_sd = 1, sd = 1, sd_sd = 1, source = "test", disease = "test", dist = "lognormal") - dist <- get_dist(data, disease = "test", source = "test", fixed = TRUE) - expect_equal( - round(dist$np_pmf[1:7], digits = 2), - array(c(0.17, 0.23, 0.17, 0.12, 0.08, 0.06, 0.04)) + expect_warning( + get_dist(data, disease = "test", source = "test"), + "deprecated" ) })