clarify references to model specifications and fits (#1189)

---------

Co-authored-by: Hannah Frick <hfrick@users.noreply.github.com>

Author: simonpcouch

R/aaa_multi_predict.R

@@ -3,7 +3,7 @@
 #' Model predictions across many sub-models
 #'
 #' For some models, predictions can be made on sub-models in the model object.
-#' @param object A `model_fit` object.
+#' @param object A [model fit][model_fit].
 #' @param new_data A rectangular data object, such as a data frame.
 #' @param type A single character value or `NULL`. Possible values are
 #' `"numeric"`, `"class"`, `"prob"`, `"conf_int"`, `"pred_int"`, `"quantile"`,
@@ -38,7 +38,7 @@ multi_predict.default <- function(object, ...) {
 #' @export
 predict.model_spec <- function(object, ...) {
   cli::cli_abort(
-    "You must {.fun fit} your model specification
+    "You must {.fun fit} your {.help [model specification](parsnip::model_spec)}
      before you can use {.fun predict}."
   )
 }

R/arguments.R

@@ -35,7 +35,7 @@ check_eng_args <- function(args, obj, core_args) {
 #' `set_args()` can be used to modify the arguments of a model specification while
 #'  `set_mode()` is used to change the model's mode.
 #'
-#' @param object A model specification.
+#' @param object A [model specification][model_spec].
 #' @param ... One or more named model arguments.
 #' @param mode A character string for the model type (e.g. "classification" or
 #'  "regression")
@@ -134,7 +134,7 @@ maybe_eval <- function(x) {
 #' Evaluate parsnip model arguments
 #' @export
 #' @keywords internal
-#' @param spec A model specification
+#' @param spec A [model specification][model_spec].
 #' @param ... Not used.
 eval_args <- function(spec, ...) {
   spec$args   <- purrr::map(spec$args,   maybe_eval)

R/augment.R

@@ -2,7 +2,7 @@
 #'
 #' `augment()` will add column(s) for predictions to the given data.
 #'
-#' @param x A `model_fit` object produced by [fit.model_spec()] or
+#' @param x A [model fit][model_fit] produced by [fit.model_spec()] or
 #' [fit_xy.model_spec()].
 #' @param eval_time For censored regression models, a vector of time points at
 #' which the survival probability is estimated.

R/case_weights.R

@@ -72,7 +72,7 @@ patch_formula_environment_with_case_weights <- function(formula,
 #' Not all modeling engines can incorporate case weights into their
 #' calculations. This function can determine whether they can be used.
 #'
-#' @param spec A parsnip model specification.
+#' @param spec A parsnip [model specification][model_spec].
 #' @return A single logical.
 #' @examples
 #' case_weights_allowed(linear_reg())

R/convert_data.R

@@ -160,7 +160,7 @@
 }
 
 
-#' @param object An object of class `model_fit`.
+#' @param object A [model fit][model_fit].
 #' @inheritParams predict.model_fit
 #' @rdname convert_helpers
 #' @keywords internal

R/discrim_flexible.R

@@ -51,7 +51,7 @@ discrim_flexible <-
 # ------------------------------------------------------------------------------
 
 #' Update a model specification
-#' @param object A model specification.
+#' @param object A [model specification][model_spec].
 #' @param ... Not used for `update()`.
 #' @param fresh A logical for whether the arguments should be
 #'  modified in-place of or replaced wholesale.
@@ -92,7 +92,7 @@ check_args.discrim_flexible <- function(object, call = rlang::caller_env()) {
   check_number_whole(args$prod_degree, min = 1, allow_null = TRUE, call = call, arg = "prod_degree")
   check_number_whole(args$num_terms, min = 1, allow_null = TRUE, call = call, arg = "num_terms")
   check_string(args$prune_method, allow_empty = FALSE, allow_null = TRUE, call = call, arg = "prune_method")
-  
+
   invisible(object)
 }
 

R/engines.R

@@ -82,7 +82,7 @@ load_libs <- function(x, quiet, attach = FALSE) {
 #' `set_engine("ranger", importance = "permutation")`.
 #'
 #'
-#' @param object A model specification.
+#' @param object A [model specification][model_spec].
 #' @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.).

R/extract.R

@@ -4,7 +4,7 @@
 #' These functions extract various elements from a parsnip object. If they do
 #' not exist yet, an error is thrown.
 #'
-#' - `extract_spec_parsnip()` returns the parsnip model specification.
+#' - `extract_spec_parsnip()` returns the parsnip [model specification][model_spec].
 #'
 #' - `extract_fit_engine()` returns the engine specific fit embedded within
 #'   a parsnip model fit. For example, when using [parsnip::linear_reg()]

R/fit.R

@@ -116,7 +116,9 @@ fit.model_spec <-
            ...
   ) {
     if (object$mode == "unknown") {
-      cli::cli_abort("Please set the mode in the model specification.")
+      cli::cli_abort(
+        "Please set the mode in the {.help [model specification](parsnip::model_spec)}."
+      )
     }
     control <- condense_control(control, control_parsnip())
     check_case_weights(case_weights, object)
@@ -249,7 +251,10 @@ fit_xy.model_spec <-
            ...
   ) {
     if (object$mode == "unknown") {
-      cli::cli_abort("Please set the mode in the model specification.")
+      cli::cli_abort(
+        "Please set the mode in the
+        {.help [model specification](parsnip::model_spec)}."
+      )
     }
 
     if (inherits(object, "surv_reg")) {

R/model_object_docs.R

@@ -1,7 +1,32 @@
-#' Model Specification Information
+#' Model Specifications
 #'
+#' @description
 #'
-#' An object with class "model_spec" is a container for
+#' The parsnip package splits the process of fitting models into two steps:
+#'
+#' 1) Specify how a model will be fit using a _model specification_
+#' 2) Fit a model using the model specification
+#'
+#' This is a different approach to many other model interfaces in R, like `lm()`,
+#' where both the specification of the model and the fitting happens in one
+#' function call. Splitting the process into two steps allows users to
+#' iteratively define model specifications throughout the model development
+#' process.
+#'
+#' This intermediate object that defines how the model will be fit is called
+#' a _model specification_ and has class `model_spec`. Model type functions,
+#' like [linear_reg()] or [boost_tree()], return `model_spec` objects.
+#'
+#' Fitted model objects, resulting from passing a `model_spec` to
+#' [fit()][fit.model_spec()] or [fit_xy][fit_xy.model_spec()], have
+#' class `model_fit`, and contain the original `model_spec` objects inside
+#' them. See [?model_fit][model_fit] for more on that object type, and
+#' [?extract_spec_parsnip][extract_spec_parsnip.model_fit] to
+#' extract `model_spec`s from `model_fit`s.
+#'
+#' @details
+#'
+#' An object with class `"model_spec"` is a container for
 #'  information about a model that will be fit.
 #'
 #' The main elements of the object are:
@@ -140,10 +165,18 @@
 #' @name model_spec
 NULL
 
-#' Model Fit Object Information
+#' Model Fit Objects
+#'
+#' @description
+#'
+#' Model fits are trained [model specifications][model_spec] that are
+#' ready to [predict][predict.model_fit] on new data. Model fits have class
+#' `model_fit` and, usually, a subclass referring to the engine
+#' used to fit the model.
 #'
+#' @details
 #'
-#' An object with class "model_fit" is a container for
+#' An object with class `"model_fit"` is a container for
 #'  information about a model that has been fit to the data.
 #'
 #' The main elements of the object are: