Move all models' update docs (#479)

* Make new doc file for `update` methods

* Move models' `update` docs to centralized page

* Also include new survival models

* Needed to inherit some params

* Update pkgdown site

* Update NEWS

* Update R/update.R

Co-authored-by: Davis Vaughan <davis@rstudio.com>

* Updates to `parameters` description

Co-authored-by: Davis Vaughan <davis@rstudio.com>

Author: juliasilge

NEWS.md

@@ -12,6 +12,8 @@
 
 * Re-licensed package from GPL-2 to MIT. See [consent from copyright holders here](https://github.com/tidymodels/parsnip/issues/462).
 
+* Re-organized model documentation for `update` methods (#479).
+
 # parsnip 0.1.5
 
 * An RStudio add-in is available that makes writing multiple `parsnip` model specifications to the source window. It can be accessed via the IDE addin menus or by calling `parsnip_addin()`.

R/boost_tree.R

@@ -81,7 +81,7 @@
 #'  reloaded and reattached to the `parsnip` object.
 #'
 #' @importFrom purrr map_lgl
-#' @seealso [fit()], [set_engine()]
+#' @seealso [fit()], [set_engine()], [update()]
 #' @examples
 #' show_engines("boost_tree")
 #'
@@ -132,32 +132,8 @@ print.boost_tree <- function(x, ...) {
 
 # ------------------------------------------------------------------------------
 
-#' @export
-#' @param object A boosted tree model specification.
-#' @param parameters A 1-row tibble or named list with _main_
-#'  parameters to update. If the individual arguments are used,
-#'  these will supersede the values in `parameters`. Also, using
-#'  engine arguments in this object will result in an error.
-#' @param ... Not used for `update()`.
-#' @param fresh A logical for whether the arguments should be
-#'  modified in-place of or replaced wholesale.
-#' @return An updated model specification.
-#' @examples
-#' model <- boost_tree(mtry = 10, min_n = 3)
-#' model
-#' update(model, mtry = 1)
-#' update(model, mtry = 1, fresh = TRUE)
-#'
-#' param_values <- tibble::tibble(mtry = 10, tree_depth = 5)
-#'
-#' model %>% update(param_values)
-#' model %>% update(param_values, mtry = 3)
-#'
-#' param_values$verbose <- 0
-#' # Fails due to engine argument
-#' # model %>% update(param_values)
 #' @method update boost_tree
-#' @rdname boost_tree
+#' @rdname parsnip_update
 #' @export
 update.boost_tree <-
   function(object,

R/decision_tree.R

@@ -21,7 +21,6 @@
 #'  functions. If parameters need to be modified, `update()` can be used
 #'  in lieu of recreating the object from scratch.
 #'
-#' @inheritParams boost_tree
 #' @param mode A single character string for the type of model.
 #'  Possible values for this model are "unknown", "regression", or
 #'  "classification".
@@ -60,7 +59,7 @@
 #'  reloaded and reattached to the `parsnip` object.
 #'
 #' @importFrom purrr map_lgl
-#' @seealso [fit()]
+#' @seealso [fit()], [set_engine()], [update()]
 #' @examples
 #' show_engines("decision_tree")
 #'
@@ -102,16 +101,8 @@ print.decision_tree <- function(x, ...) {
 
 # ------------------------------------------------------------------------------
 
-#' @export
-#' @inheritParams update.boost_tree
-#' @param object A decision tree model specification.
-#' @examples
-#' model <- decision_tree(cost_complexity = 10, min_n = 3)
-#' model
-#' update(model, cost_complexity = 1)
-#' update(model, cost_complexity = 1, fresh = TRUE)
 #' @method update decision_tree
-#' @rdname decision_tree
+#' @rdname parsnip_update
 #' @export
 update.decision_tree <-
   function(object,

R/linear_reg.R

@@ -16,7 +16,6 @@
 #'  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.
-#' @inheritParams boost_tree
 #' @param mode A single character string for the type of model.
 #'  The only possible value for this model is "regression".
 #' @param penalty A non-negative number representing the total
@@ -60,7 +59,7 @@
 #'  separately saved to disk. In a new session, the object can be
 #'  reloaded and reattached to the `parsnip` object.
 #'
-#' @seealso [fit()], [set_engine()]
+#' @seealso [fit()], [set_engine()], [update()]
 #' @examples
 #' show_engines("linear_reg")
 #'
@@ -121,15 +120,8 @@ translate.linear_reg <- function(x, engine = x$engine, ...) {
 
 # ------------------------------------------------------------------------------
 
-#' @inheritParams update.boost_tree
-#' @param object A linear regression model specification.
-#' @examples
-#' model <- linear_reg(penalty = 10, mixture = 0.1)
-#' model
-#' update(model, penalty = 1)
-#' update(model, penalty = 1, fresh = TRUE)
 #' @method update linear_reg
-#' @rdname linear_reg
+#' @rdname parsnip_update
 #' @export
 update.linear_reg <-
   function(object,

R/logistic_reg.R

@@ -16,7 +16,6 @@
 #'  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.
-#' @inheritParams boost_tree
 #' @param mode A single character string for the type of model.
 #'  The only possible value for this model is "classification".
 #' @param penalty A non-negative number representing the total
@@ -59,7 +58,7 @@
 #'  separately saved to disk. In a new session, the object can be
 #'  reloaded and reattached to the `parsnip` object.
 #'
-#' @seealso [fit()]
+#' @seealso [fit()], [set_engine()], [update()]
 #' @examples
 #' show_engines("logistic_reg")
 #'
@@ -144,15 +143,8 @@ translate.logistic_reg <- function(x, engine = x$engine, ...) {
 
 # ------------------------------------------------------------------------------
 
-#' @inheritParams update.boost_tree
-#' @param object A logistic regression model specification.
-#' @examples
-#' model <- logistic_reg(penalty = 10, mixture = 0.1)
-#' model
-#' update(model, penalty = 1)
-#' update(model, penalty = 1, fresh = TRUE)
 #' @method update logistic_reg
-#' @rdname logistic_reg
+#' @rdname parsnip_update
 #' @export
 update.logistic_reg <-
   function(object,

R/mars.R

@@ -22,7 +22,6 @@
 #'  functions. If parameters need to be modified, `update()` can be used
 #'  in lieu of recreating the object from scratch.
 #'
-#' @inheritParams boost_tree
 #' @param mode A single character string for the type of model.
 #'  Possible values for this model are "unknown", "regression", or
 #'  "classification".
@@ -39,7 +38,7 @@
 #' @includeRmd man/rmd/mars.Rmd details
 #'
 #' @importFrom purrr map_lgl
-#' @seealso [fit()]
+#' @seealso [fit()], [set_engine()], [update()]
 #' @examples
 #' show_engines("mars")
 #'
@@ -79,16 +78,8 @@ print.mars <- function(x, ...) {
 
 # ------------------------------------------------------------------------------
 
-#' @export
-#' @inheritParams update.boost_tree
-#' @param object A MARS model specification.
-#' @examples
-#' model <- mars(num_terms = 10, prune_method = "none")
-#' model
-#' update(model, num_terms = 1)
-#' update(model, num_terms = 1, fresh = TRUE)
 #' @method update mars
-#' @rdname mars
+#' @rdname parsnip_update
 #' @export
 update.mars <-
   function(object,

R/mlp.R

@@ -27,7 +27,6 @@
 #'  If parameters need to be modified, `update()` can be used
 #'  in lieu of recreating the object from scratch.
 #'
-#' @inheritParams boost_tree
 #' @param mode A single character string for the type of model.
 #'  Possible values for this model are "unknown", "regression", or
 #'  "classification".
@@ -54,7 +53,7 @@
 #' @includeRmd man/rmd/mlp.Rmd details
 #'
 #' @importFrom purrr map_lgl
-#' @seealso [fit()]
+#' @seealso [fit()], [set_engine()], [update()]
 #' @examples
 #' show_engines("mlp")
 #'
@@ -100,21 +99,8 @@ print.mlp <- function(x, ...) {
 
 # ------------------------------------------------------------------------------
 
-#' Update a Single Layer Neural Network Specification
-#'
-#' If parameters need to be modified, this function can be used
-#'  in lieu of recreating the object from scratch.
-#'
-#' @export
-#' @inheritParams update.boost_tree
-#' @param object A multilayer perceptron model specification.
-#' @examples
-#' model <- mlp(hidden_units = 10, dropout = 0.30)
-#' model
-#' update(model, hidden_units = 2)
-#' update(model, hidden_units = 2, fresh = TRUE)
 #' @method update mlp
-#' @rdname mlp
+#' @rdname parsnip_update
 #' @export
 update.mlp <-
   function(object,

R/multinom_reg.R

@@ -16,7 +16,6 @@
 #'  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.
-#' @inheritParams boost_tree
 #' @param mode A single character string for the type of model.
 #'  The only possible value for this model is "classification".
 #' @param penalty A non-negative number representing the total
@@ -54,7 +53,7 @@
 #'  separately saved to disk. In a new session, the object can be
 #'  reloaded and reattached to the `parsnip` object.
 #'
-#' @seealso [fit()]
+#' @seealso [fit()], [set_engine()], [update()]
 #' @examples
 #' show_engines("multinom_reg")
 #'
@@ -101,15 +100,8 @@ translate.multinom_reg <- translate.linear_reg
 
 # ------------------------------------------------------------------------------
 
-#' @inheritParams update.boost_tree
-#' @param object A multinomial regression model specification.
-#' @examples
-#' model <- multinom_reg(penalty = 10, mixture = 0.1)
-#' model
-#' update(model, penalty = 1)
-#' update(model, penalty = 1, fresh = TRUE)
 #' @method update multinom_reg
-#' @rdname multinom_reg
+#' @rdname parsnip_update
 #' @export
 update.multinom_reg <-
   function(object,

R/nearest_neighbor.R

@@ -48,7 +48,7 @@
 #'
 #' @includeRmd man/rmd/nearest-neighbor.Rmd details
 #'
-#' @seealso [fit()]
+#' @seealso [fit()], [set_engine()], [update()]
 #'
 #' @examples
 #' show_engines("nearest_neighbor")
@@ -90,8 +90,9 @@ print.nearest_neighbor <- function(x, ...) {
 
 # ------------------------------------------------------------------------------
 
+#' @method update nearest_neighbor
 #' @export
-#' @inheritParams update.boost_tree
+#' @rdname parsnip_update
 update.nearest_neighbor <- function(object,
                                     parameters = NULL,
                                     neighbors = NULL,

R/proportional_hazards.R

@@ -24,6 +24,7 @@
 #' Proportional hazards models include the Cox model.
 #' For `proportional_hazards()`, the mode will always be "censored regression".
 #'
+#' @seealso [fit()], [set_engine()], [update()]
 #' @examples
 #' show_engines("proportional_hazards")
 #'
@@ -62,17 +63,8 @@ print.proportional_hazards <- function(x, ...) {
 
 # ------------------------------------------------------------------------------
 
-#' @param object A proportional hazards model specification.
-#' @param ... Not used for `update()`.
-#' @param fresh A logical for whether the arguments should be
-#'  modified in-place of or replaced wholesale.
-#' @examples
-#' model <- proportional_hazards(penalty = 10, mixture = 0.1)
-#' model
-#' update(model, penalty = 1)
-#' update(model, penalty = 1, fresh = TRUE)
 #' @method update proportional_hazards
-#' @rdname proportional_hazards
+#' @rdname parsnip_update
 #' @export
 update.proportional_hazards <- function(object,
                                         parameters = NULL,

R/rand_forest.R

@@ -20,7 +20,6 @@
 #'  functions. If parameters need to be modified, `update()` can be used
 #'  in lieu of recreating the object from scratch.
 #'
-#' @inheritParams boost_tree
 #' @param mode A single character string for the type of model.
 #'  Possible values for this model are "unknown", "regression", or
 #'  "classification".
@@ -54,7 +53,7 @@
 #'  reloaded and reattached to the `parsnip` object.
 #'
 #' @importFrom purrr map_lgl
-#' @seealso [fit()]
+#' @seealso [fit()], [set_engine()], [update()]
 #' @examples
 #' show_engines("rand_forest")
 #'
@@ -96,16 +95,8 @@ print.rand_forest <- function(x, ...) {
 
 # ------------------------------------------------------------------------------
 
-#' @export
-#' @inheritParams update.boost_tree
-#' @param object A random forest model specification.
-#' @examples
-#' model <- rand_forest(mtry = 10, min_n = 3)
-#' model
-#' update(model, mtry = 1)
-#' update(model, mtry = 1, fresh = TRUE)
 #' @method update rand_forest
-#' @rdname rand_forest
+#' @rdname parsnip_update
 #' @export
 update.rand_forest <-
   function(object,

R/surv_reg.R

@@ -31,7 +31,6 @@
 #'  `strata` function cannot be used. To achieve the same effect,
 #'  the extra parameter roles can be used (as described above).
 #'
-#' @inheritParams boost_tree
 #' @param mode A single character string for the type of model.
 #'  The only possible value for this model is "regression".
 #' @param dist A character string for the outcome distribution. "weibull" is
@@ -47,7 +46,7 @@
 #'
 #' @includeRmd man/rmd/surv-reg.Rmd details
 #'
-#' @seealso [fit()], [survival::Surv()]
+#' @seealso [fit()], [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
@@ -99,19 +98,8 @@ print.surv_reg <- function(x, ...) {
 
 # ------------------------------------------------------------------------------
 
-#' Update a Parametric Survival Regression Specification
-#'
-#' If parameters need to be modified, this function can be used
-#'  in lieu of recreating the object from scratch.
-#'
-#' @inheritParams update.boost_tree
-#' @param object A survival regression model specification.
-#' @examples
-#' model <- surv_reg(dist = "weibull")
-#' model
-#' update(model, dist = "lnorm")
 #' @method update surv_reg
-#' @rdname surv_reg
+#' @rdname parsnip_update
 #' @export
 update.surv_reg <- function(object, parameters = NULL, dist = NULL, fresh = FALSE, ...) {