Update documentation of survival models to new doc style (#582)

* doc update for `survival_reg()`

* doc update for `proportional_hazards()`

* doc update for `surv_reg()`

* use correct mode

* clean up

* update docs for `surv_reg()`

- tuning parameters
- other details

* update ref to pkg-level docs of flexsurv

Author: hfrick

R/proportional_hazards.R

@@ -1,35 +1,36 @@
 #' Proportional hazards regression
 #'
-#' `proportional_hazards()` is a way to generate a _specification_ of a model
-#' before fitting and allows the model to be created using different packages
-#' in R. The main arguments for the model are:
-#' \itemize{
-#'   \item \code{penalty}: The total amount of regularization
-#'  in the model. Note that this must be zero for some engines.
-#'   \item \code{mixture}: The mixture amounts of different types of
-#'   regularization (see below). Note that this will be ignored for some engines.
-#' }
-#' These arguments are converted to their specific names at the
-#'  time that the model is fit. Other options and arguments can be
-#'  set using `set_engine()`. If left to their defaults
-#'  here (`NULL`), the values are taken from the underlying model
-#'  functions. If parameters need to be modified, `update()` can be used
-#'  in lieu of recreating the object from scratch.
+#' @description
+#' `proportional_hazards()` defines a proportional hazards model.
 #'
-#' @param mode A single character string for the prediction outcome mode.
-#'  Possible values for this model are "unknown", or "censored regression".
-#' @param engine A single character string specifying what computational engine
-#'  to use for fitting. Possible engines are listed below. The default for this
-#'  model is `"survival"`.
+#' There are different ways to fit this model. The method of estimation is
+#' chosen by setting the model _engine_.
+#'
+#' \Sexpr[stage=render,results=rd]{parsnip:::make_engine_list("proportional_hazards")}
+#'
+#' More information on how \pkg{parsnip} is used for modeling is at
+#' \url{https://www.tidymodels.org/}.
+#'
+#' @inheritParams boost_tree
 #' @inheritParams linear_reg
+#' @param mode A single character string for the prediction outcome mode.
+#'  The only possible value for this model is "censored regression".
+#'
+#' @template spec-details
+#'
+#' @template spec-survival
 #'
 #' @details
 #' Proportional hazards models include the Cox model.
-#' For `proportional_hazards()`, the mode will always be "censored regression".
 #'
-#' @seealso [fit.model_spec()], [set_engine()], [update()]
+#' @template spec-references
+#'
+#' @seealso \Sexpr[stage=render,results=rd]{parsnip:::make_seealso_list("proportional_hazards")}
+#'
 #' @examples
 #' show_engines("proportional_hazards")
+#'
+#' proportional_hazards(mode = "censored regression")
 #' @keywords internal
 #' @export
 proportional_hazards <- function(

R/surv_reg.R

@@ -6,57 +6,34 @@
 #' 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
-#'  model is:
-#' \itemize{
-#'   \item \code{dist}: The probability distribution of the outcome.
-#' }
-#' This argument is converted to its specific names at the
-#'  time that the model is fit. Other options and arguments can be
-#'  set using `set_engine()`. If left to its default
-#'  here (`NULL`), the value is taken from the underlying model
-#'  functions.
+#' `surv_reg()` defines a parametric survival model.
 #'
-#' The data given to the function are not saved and are only used
-#'  to determine the _mode_ of the model. For `surv_reg()`,the
-#'  mode will always be "regression".
+#' There are different ways to fit this model. The method of estimation is
+#' chosen by setting the model _engine_.
 #'
-#'  Since survival models typically involve censoring (and require the use of
-#'  [survival::Surv()] objects), the [fit.model_spec()] function will require that the
-#'  survival model be specified via the formula interface.
+#' \Sexpr[stage=render,results=rd]{parsnip:::make_engine_list("surv_reg")}
 #'
-#' Also, for the `flexsurv::flexsurvfit` engine, the typical
-#'  `strata` function cannot be used. To achieve the same effect,
-#'  the extra parameter roles can be used (as described above).
+#' More information on how \pkg{parsnip} is used for modeling is at
+#' \url{https://www.tidymodels.org/}.
 #'
+#' @inheritParams boost_tree
 #' @param mode A single character string for the prediction outcome mode.
 #'  The only possible value for this model is "regression".
-#'  @param engine A single character string specifying what computational engine
-#'  to use for fitting. Possible engines are listed below. The default for this
-#'  model is `"survival"`.
-#' @param dist A character string for the outcome distribution. "weibull" is
-#'  the default.
-#' @details
-#' For `surv_reg()`, the mode will always be "regression".
+#' @param dist A character string for the probability distribution of the
+#'  outcome. The default is "weibull".
 #'
-#' The model can be created using the `fit()` function using the
-#'  following _engines_:
-#' \itemize{
-#' \item \pkg{R}:  `"flexsurv"`, `"survival"` (the default)
-#' }
+#' @template spec-details
 #'
-#' @includeRmd man/rmd/surv-reg.Rmd details
+#' @template spec-survival
+#'
+#' @template spec-references
+#'
+#' @seealso \Sexpr[stage=render,results=rd]{parsnip:::make_seealso_list("surv_reg")}
 #'
-#' @seealso [fit.model_spec()], [survival::Surv()], [set_engine()], [update()]
-#' @references Jackson, C. (2016). `flexsurv`: A Platform for Parametric Survival
-#'  Modeling in R. _Journal of Statistical Software_, 70(8), 1 - 33.
 #' @examples
 #' show_engines("surv_reg")
 #'
-#' surv_reg()
-#'
+#' surv_reg(mode = "regression", dist = "weibull")
 #' @keywords internal
 #' @export
 surv_reg <- function(mode = "regression", engine = "survival", dist = NULL) {

R/surv_reg_flexsurv.R

@@ -0,0 +1,9 @@
+#' Parametric survival regression
+#'
+#' [flexsurv::flexsurvreg()] fits a parametric survival model.
+#'
+#' @includeRmd man/rmd/surv_reg_flexsurv.Rmd details
+#'
+#' @name details_surv_reg_flexsurv
+#' @keywords internal
+NULL

R/surv_reg_survival.R

@@ -0,0 +1,9 @@
+#' Parametric survival regression
+#'
+#' [survival::survreg()] fits a parametric survival model.
+#'
+#' @includeRmd man/rmd/surv_reg_survival.Rmd details
+#'
+#' @name details_surv_reg_survival
+#' @keywords internal
+NULL

R/survival_reg.R

@@ -1,38 +1,35 @@
 #' Parametric survival regression
 #'
-#' `survival_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
-#'  model is:
-#' \itemize{
-#'   \item \code{dist}: The probability distribution of the outcome.
-#' }
-#' This argument is converted to its specific names at the
-#'  time that the model is fit. Other options and argument can be
-#'  set using `set_engine()`. If left to its default
-#'  here (`NULL`), the value is taken from the underlying model
-#'  functions. If parameters need to be modified, `update()` can be used
-#'  in lieu of recreating the object from scratch.
+#' @description
+#' `survival_reg()` defines a parametric survival model.
 #'
+#' There are different ways to fit this model. The method of estimation is
+#' chosen by setting the model _engine_.
+#'
+#' \Sexpr[stage=render,results=rd]{parsnip:::make_engine_list("survival_reg")}
+#'
+#' More information on how \pkg{parsnip} is used for modeling is at
+#' \url{https://www.tidymodels.org/}.
+#'
+#' @inheritParams boost_tree
 #' @param mode A single character string for the prediction outcome mode.
 #'  The only possible value for this model is "censored regression".
-#' @param engine A single character string specifying what computational engine
-#'  to use for fitting. Possible engines are listed below. The default for this
-#'  model is `"survival"`.
-#' @param dist A character string for the outcome distribution. "weibull" is
-#'  the default.
-#' @details
-#' The data given to the function are not saved and are only used
-#' to determine the _mode_ of the model. For `survival_reg()`,the
-#' mode will always be "censored regression".
+#' @param dist A character string for the probability distribution of the
+#'  outcome. The default is "weibull".
+#'
 #'
-#' Since survival models typically involve censoring (and require the use of
-#' [survival::Surv()] objects), the [fit.model_spec()] function will require that the
-#' survival model be specified via the formula interface.
+#' @template spec-details
+#'
+#' @template spec-survival
+#'
+#' @template spec-references
+#'
+#' @seealso \Sexpr[stage=render,results=rd]{parsnip:::make_seealso_list("survival_reg")}
 #'
-#' @seealso [fit.model_spec()], [survival::Surv()], [set_engine()], [update()]
 #' @examples
-#' survival_reg()
+#' show_engines("survival_reg")
+#'
+#' survival_reg(mode = "censored regression", dist = "weibull")
 #' @keywords internal
 #' @export
 survival_reg <- function(mode = "censored regression", engine = "survival", dist = NULL) {

man-roxygen/spec-survival.R

@@ -0,0 +1,4 @@
+#' @details
+#' Since survival models typically involve censoring (and require the use of
+#' [survival::Surv()] objects), the [fit.model_spec()] function will require that the
+#' survival model be specified via the formula interface.