diff --git a/NEWS.md b/NEWS.md index 090012dfc..6c0fa0300 100644 --- a/NEWS.md +++ b/NEWS.md @@ -6,7 +6,7 @@ * A new linear SVM model `svm_linear()` is now available with the `LiblineaR` engine (#424) and the `kernlab` engine (#438), and the `LiblineaR` engine is available for `logistic_reg()` as well (#429). These models can use sparse matrices via `fit_xy()` (#447). -* New model specification `survival_reg()` for the new mode `"censored regression"`. (#444) +* New model specification `survival_reg()` for the new mode `"censored regression"` (#444). `surv_reg()` is now soft-deprecated (#448). # parsnip 0.1.5 diff --git a/R/surv_reg.R b/R/surv_reg.R index deda279db..c848e1d55 100644 --- a/R/surv_reg.R +++ b/R/surv_reg.R @@ -1,5 +1,11 @@ #' General Interface for Parametric Survival Models #' +#' @description +#' `r lifecycle::badge("deprecated")` +#' +#' This function is soft-deprecated in favor of `survival_reg()` which uses the +#' `"censored regression"` mode. +#' #' `surv_reg()` is a way to generate a _specification_ of a model #' before fitting and allows the model to be created using #' R. The main argument for the @@ -51,9 +57,19 @@ #' # Parameters can be represented by a placeholder: #' surv_reg(dist = varying()) #' +#' # -> +#' show_engines("survival_reg") +#' +#' survival_reg() +#' # Parameters can be represented by a placeholder: +#' survival_reg(dist = varying()) +#' +#' @keywords internal #' @export surv_reg <- function(mode = "regression", dist = NULL) { + lifecycle::deprecate_soft("0.1.6", "surv_reg()", "survival_reg()") + args <- list( dist = enquo(dist) ) diff --git a/man/figures/lifecycle-archived.svg b/man/figures/lifecycle-archived.svg new file mode 100644 index 000000000..48f72a6f3 --- /dev/null +++ b/man/figures/lifecycle-archived.svg @@ -0,0 +1 @@ + lifecyclelifecyclearchivedarchived \ No newline at end of file diff --git a/man/figures/lifecycle-defunct.svg b/man/figures/lifecycle-defunct.svg new file mode 100644 index 000000000..01452e5fb --- /dev/null +++ b/man/figures/lifecycle-defunct.svg @@ -0,0 +1 @@ +lifecyclelifecycledefunctdefunct \ No newline at end of file diff --git a/man/figures/lifecycle-deprecated.svg b/man/figures/lifecycle-deprecated.svg new file mode 100644 index 000000000..4baaee01c --- /dev/null +++ b/man/figures/lifecycle-deprecated.svg @@ -0,0 +1 @@ +lifecyclelifecycledeprecateddeprecated \ No newline at end of file diff --git a/man/figures/lifecycle-experimental.svg b/man/figures/lifecycle-experimental.svg new file mode 100644 index 000000000..d1d060e92 --- /dev/null +++ b/man/figures/lifecycle-experimental.svg @@ -0,0 +1 @@ +lifecyclelifecycleexperimentalexperimental \ No newline at end of file diff --git a/man/figures/lifecycle-maturing.svg b/man/figures/lifecycle-maturing.svg new file mode 100644 index 000000000..df7131014 --- /dev/null +++ b/man/figures/lifecycle-maturing.svg @@ -0,0 +1 @@ +lifecyclelifecyclematuringmaturing \ No newline at end of file diff --git a/man/figures/lifecycle-questioning.svg b/man/figures/lifecycle-questioning.svg new file mode 100644 index 000000000..08ee0c903 --- /dev/null +++ b/man/figures/lifecycle-questioning.svg @@ -0,0 +1 @@ +lifecyclelifecyclequestioningquestioning \ No newline at end of file diff --git a/man/figures/lifecycle-stable.svg b/man/figures/lifecycle-stable.svg new file mode 100644 index 000000000..e015dc811 --- /dev/null +++ b/man/figures/lifecycle-stable.svg @@ -0,0 +1 @@ +lifecyclelifecyclestablestable \ No newline at end of file diff --git a/man/figures/lifecycle-superseded.svg b/man/figures/lifecycle-superseded.svg new file mode 100644 index 000000000..75f24f553 --- /dev/null +++ b/man/figures/lifecycle-superseded.svg @@ -0,0 +1 @@ + lifecyclelifecyclesupersededsuperseded \ No newline at end of file diff --git a/man/surv_reg.Rd b/man/surv_reg.Rd index 239c1d31a..556d0d731 100644 --- a/man/surv_reg.Rd +++ b/man/surv_reg.Rd @@ -29,6 +29,11 @@ modified in-place of or replaced wholesale.} \item{...}{Not used for \code{update()}.} } \description{ +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} + +This function is soft-deprecated in favor of \code{survival_reg()} which uses the +\code{"censored regression"} mode. + \code{surv_reg()} is a way to generate a \emph{specification} of a model before fitting and allows the model to be created using R. The main argument for the @@ -42,10 +47,6 @@ set using \code{set_engine()}. If left to its default here (\code{NULL}), the value is taken from the underlying model functions. -If parameters need to be modified, this function can be used -in lieu of recreating the object from scratch. -} -\details{ The data given to the function are not saved and are only used to determine the \emph{mode} of the model. For \code{surv_reg()},the mode will always be "regression". @@ -58,6 +59,10 @@ Also, for the \code{flexsurv::flexsurvfit} engine, the typical \code{strata} function cannot be used. To achieve the same effect, the extra parameter roles can be used (as described above). +If parameters need to be modified, this function can be used +in lieu of recreating the object from scratch. +} +\details{ For \code{surv_reg()}, the mode will always be "regression". The model can be created using the \code{fit()} function using the @@ -73,7 +78,10 @@ call. For this type of model, the template of the fit calls are below. set_engine("flexsurv") \%>\% set_mode("regression") \%>\% translate() -}\if{html}{\out{}}\preformatted{## Parametric Survival Regression Model Specification (regression) +}\if{html}{\out{}}\preformatted{## Warning: `surv_reg()` was deprecated in parsnip 0.1.6. +## Please use `survival_reg()` instead. + +## Parametric Survival Regression Model Specification (regression) ## ## Computational engine: flexsurv ## @@ -87,7 +95,10 @@ call. For this type of model, the template of the fit calls are below. set_engine("survival") \%>\% set_mode("regression") \%>\% translate() -}\if{html}{\out{}}\preformatted{## Parametric Survival Regression Model Specification (regression) +}\if{html}{\out{}}\preformatted{## Warning: `surv_reg()` was deprecated in parsnip 0.1.6. +## Please use `survival_reg()` instead. + +## Parametric Survival Regression Model Specification (regression) ## ## Computational engine: survival ## @@ -123,6 +134,13 @@ surv_reg() # Parameters can be represented by a placeholder: surv_reg(dist = varying()) +# -> +show_engines("survival_reg") + +survival_reg() +# Parameters can be represented by a placeholder: +survival_reg(dist = varying()) + model <- surv_reg(dist = "weibull") model update(model, dist = "lnorm") @@ -134,3 +152,4 @@ Modeling in R. \emph{Journal of Statistical Software}, 70(8), 1 - 33. \seealso{ \code{\link[=fit]{fit()}}, \code{\link[survival:Surv]{survival::Surv()}} } +\keyword{internal} diff --git a/tests/testthat/test_surv_reg.R b/tests/testthat/test_surv_reg.R index 2e5674c9d..424f48a9b 100644 --- a/tests/testthat/test_surv_reg.R +++ b/tests/testthat/test_surv_reg.R @@ -11,6 +11,8 @@ source("helpers.R") # ------------------------------------------------------------------------------ test_that('primary arguments', { + rlang::local_options(lifecycle_verbosity = "quiet") + basic <- surv_reg() basic_flexsurv <- translate(basic %>% set_engine("flexsurv")) @@ -46,6 +48,8 @@ test_that('primary arguments', { }) test_that('engine arguments', { + rlang::local_options(lifecycle_verbosity = "quiet") + fs_cl <- surv_reg() expect_equal(translate(fs_cl %>% set_engine("flexsurv", cl = .99))$method$fit$args, list( @@ -60,6 +64,8 @@ test_that('engine arguments', { test_that('updating', { + rlang::local_options(lifecycle_verbosity = "quiet") + expr1 <- surv_reg() %>% set_engine("flexsurv", cl = varying()) expr1_exp <- surv_reg(dist = "lnorm") %>% set_engine("flexsurv", cl = .99) expect_equal(update(expr1, dist = "lnorm", cl = 0.99), expr1_exp) @@ -75,7 +81,14 @@ test_that('updating', { }) test_that('bad input', { + rlang::local_options(lifecycle_verbosity = "quiet") + expect_error(surv_reg(mode = ", classification")) expect_error(translate(surv_reg() %>% set_engine("wat"))) expect_error(translate(surv_reg() %>% set_engine(NULL))) }) + +test_that("deprecation warning", { + rlang::local_options(lifecycle_verbosity = "warning") + expect_warning(surv_reg()) +}) diff --git a/tests/testthat/test_surv_reg_flexsurv.R b/tests/testthat/test_surv_reg_flexsurv.R index 7dc621967..1a88feb0f 100644 --- a/tests/testthat/test_surv_reg_flexsurv.R +++ b/tests/testthat/test_surv_reg_flexsurv.R @@ -8,17 +8,17 @@ library(tibble) source(test_path("helper-objects.R")) - basic_form <- Surv(time, status) ~ age complete_form <- Surv(time) ~ age -surv_basic <- surv_reg() %>% set_engine("flexsurv") - # ------------------------------------------------------------------------------ test_that('flexsurv execution', { skip_if_not_installed("flexsurv") + rlang::local_options(lifecycle_verbosity = "quiet") + surv_basic <- surv_reg() %>% set_engine("flexsurv") + expect_error( res <- fit( surv_basic, @@ -53,6 +53,9 @@ test_that('flexsurv execution', { test_that('flexsurv prediction', { skip_if_not_installed("flexsurv") + rlang::local_options(lifecycle_verbosity = "quiet") + surv_basic <- surv_reg() %>% set_engine("flexsurv") + res <- fit( surv_basic, Surv(time, status) ~ age, diff --git a/tests/testthat/test_surv_reg_survreg.R b/tests/testthat/test_surv_reg_survreg.R index c7f0d6512..a6ce8b969 100644 --- a/tests/testthat/test_surv_reg_survreg.R +++ b/tests/testthat/test_surv_reg_survreg.R @@ -10,15 +10,15 @@ source(test_path("helper-objects.R")) basic_form <- Surv(time, status) ~ group complete_form <- Surv(time) ~ group -surv_basic <- surv_reg() %>% set_engine("survival") -surv_lnorm <- surv_reg(dist = "lognormal") %>% set_engine("survival") - # ------------------------------------------------------------------------------ test_that('survival execution', { - skip_on_travis() + rlang::local_options(lifecycle_verbosity = "quiet") + surv_basic <- surv_reg() %>% set_engine("survival") + surv_lnorm <- surv_reg(dist = "lognormal") %>% set_engine("survival") + expect_error( res <- fit( surv_basic, @@ -51,6 +51,10 @@ test_that('survival execution', { test_that('survival prediction', { skip_on_travis() + rlang::local_options(lifecycle_verbosity = "quiet") + surv_basic <- surv_reg() %>% set_engine("survival") + surv_lnorm <- surv_reg(dist = "lognormal") %>% set_engine("survival") + res <- fit( surv_basic, Surv(time, status) ~ age + sex,