Better set_engine() docs (#667)

* Replace list of engines (no longer needed) with details on engines + engine arguments

* Update spec details to link to `set_engine()` (mention eng args)

* Redocument

* added a note about naming conventions

* cleaned up show_engines docs a bit

* Clarify naming of main vs. engine args

* Fix quotes again

Co-authored-by: Max Kuhn <mxkuhn@gmail.com>

Author: juliasilge

R/engine_docs.R

@@ -285,33 +285,6 @@ find_details_topics <- function(mod, pkg = "parsnip") {
   unique(res)
 }
 
-# For use in `set_engine()` docs
-generate_set_engine_bullets <- function() {
-  env <- get_model_env()
-  models <- env$models
-  info <- rlang::env_get_list(env, models)
-
-  model_engines <- purrr::map(info, get_sorted_unique_engines)
-
-  model_prefixes <- glue::glue(
-    "\\code{\\link[=.{models}.]{.{models}.()}}:",
-    .open = ".{",
-    .close = "}."
-  )
-
-  bullets <- purrr::map2(
-    .x = model_prefixes,
-    .y = model_engines,
-    .f = combine_prefix_with_engines
-  )
-
-  bullets <- glue::glue("\\item {bullets}")
-  bullets <- glue::glue_collapse(bullets, sep = "\n")
-  bullets <- paste("\\itemize{", bullets, "}", sep = "\n")
-
-  bullets
-}
-
 sort_c <- function(x) {
   withr::with_collate("C", sort(x))
 }

R/engines.R

@@ -54,26 +54,54 @@ load_libs <- function(x, quiet, attach = FALSE) {
 #' `set_engine()` is used to specify which package or system will be used
 #'  to fit the model, along with any arguments specific to that software.
 #'
-#' @section Engines:
-#' Based on the currently loaded packages, the following lists the set of
-#' engines available to each model specification.
+#' @details
+#' In parsnip,
+#'
+#' - the model **type** differentiates basic modeling approaches, such as random
+#' forests, logistic regression, linear support vector machines, etc.,
+#' - the **mode** denotes in what kind of modeling context it will be used
+#' (most commonly, classification or regression), and
+#' - the computational **engine** indicates how the model is fit, such as with
+#' a specific R package implementation or even methods outside of R like Keras
+#' or Stan.
+#'
+#' Use [show_engines()] to get a list of possible engines for the model of
+#' interest.
+#'
+#' Modeling functions in parsnip separate model arguments into two categories:
+#'
+#' - _Main arguments_ are more commonly used and tend to be available across
+#' engines. These names are standardized to work with different engines in a
+#' consistent way, so you can use the \pkg{parsnip} main argument `trees`,
+#' instead of the heterogeneous arguments for this parameter from \pkg{ranger}
+#' and  \pkg{randomForest} packages (`num.trees` and `ntree`, respectively). Set
+#' these in your model type function, like `rand_forest(trees = 2000)`.
+#' - _Engine arguments_ are either specific to a particular engine or used
+#' more rarely; there is no change for these argument names from the underlying
+#' engine. Set these in `set_engine()`, like
+#' `set_engine("ranger", importance = "permutation")`.
 #'
-#' \Sexpr[stage=render,results=rd]{parsnip:::generate_set_engine_bullets()}
 #'
 #' @param object A model specification.
 #' @param engine A character string for the software that should
 #'  be used to fit the model. This is highly dependent on the type
 #'  of model (e.g. linear regression, random forest, etc.).
 #' @param ... Any optional arguments associated with the chosen computational
-#'  engine. These are captured as quosures and can be `tune()`.
+#'  engine. These are captured as quosures and can be tuned with `tune()`.
 #' @return An updated model specification.
 #' @examples
-#' # First, set general arguments using the standardized names
-#' mod <-
-#'   logistic_reg(penalty = 0.01, mixture = 1/3) %>%
-#'   # now say how you want to fit the model and another other options
-#'   set_engine("glmnet", nlambda = 10)
-#' translate(mod, engine = "glmnet")
+#' # First, set main arguments using the standardized names
+#' logistic_reg(penalty = 0.01, mixture = 1/3) %>%
+#'   # Now specify how you want to fit the model with another argument
+#'   set_engine("glmnet", nlambda = 10) %>%
+#'   translate()
+#'
+#' # Many models have possible engine-specific arguments
+#' decision_tree(tree_depth = 5) %>%
+#'   set_engine("rpart", parms = list(prior = c(.65,.35))) %>%
+#'   set_mode("classification") %>%
+#'   translate()
+#'
 #' @export
 set_engine <- function(object, engine, ...) {
   mod_type <- class(object)[1]
@@ -107,11 +135,12 @@ set_engine <- function(object, engine, ...) {
 #' Display currently available engines for a model
 #'
 #' The possible engines for a model can depend on what packages are loaded.
-#' Some `parsnip`-adjacent packages add engines to existing models. For example,
-#' the `multilevelmod` package adds additional engines for the [linear_reg()]
-#' model and these are not available unless `multilevelmod` is loaded.
+#' Some \pkg{parsnip} extension add engines to existing models. For example,
+#' the \pkg{poissonreg} package adds additional engines for the [poisson_reg()]
+#' model and these are not available unless \pkg{poissonreg} is loaded.
 #' @param x The name of a `parsnip` model (e.g., "linear_reg", "mars", etc.)
 #' @return A tibble.
+#'
 #' @examples
 #' show_engines("linear_reg")
 #' @export

man-roxygen/spec-details.R

@@ -1,6 +1,8 @@
 #' @details
 #' This function only defines what _type_ of model is being fit. Once an engine
-#'  is specified, the _method_ to fit the model is also defined.
+#'  is specified, the _method_ to fit the model is also defined. See
+#'  [set_engine()] for more on setting the engine, including how to set engine
+#'  arguments.
 #'
 #' The model is not trained or fit until the [`fit()`][fit.model_spec()] function is used
 #' with the data.