clarify hyperparameters associated with extracted objects

NEWS.md

@@ -14,6 +14,7 @@
 
 * Handles edge cases for `tune_bayes()`' `iter` argument more soundly. For `iter = 0`, the output of `tune_bayes()` should match `tune_grid()`, and `tune_bayes()` will now error when `iter < 0`. `tune_bayes()` will now alter the state of RNG slightly differently, resulting in changed Bayesian optimization search output. (#720)
 
+* Improves documentation related to the hyperparameters associated with extracted objects that are generated from submodels. See the "Extracting with submodels" section of `?collect_extracts` to learn more.
 
 # tune 1.1.2
 

R/collect.R

@@ -52,9 +52,28 @@
 #' indicators, the location (preprocessor, model, etc.), type (error or warning),
 #' and the notes.
 #'
-#' [collect_extracts()] returns a tibble with columns for the resampling
-#' indicators, the location (preprocessor, model, etc.), and objects extracted
-#' from workflows via the `extract` argument to [control functions][control_grid()].
+#' [collect_extracts()] collects objects extracted from fitted workflows
+#' via the `extract` argument to [control functions][control_grid()]. The
+#' function returns a tibble with columns for the resampling
+#' indicators, the location (preprocessor, model, etc.), and extracted objects.
+#'
+#' @section Hyperparameters and extracted objects:
+#'
+#' When making use of submodels, tune can generate predictions and calculate
+#' metrics for multiple model `.config`urations using only one model fit.
+#' However, this means that if a function was supplied to a
+#' [control function's][control_grid()] `extract` argument, tune can only
+#' execute that extraction on the one model that was fitted. As a result,
+#' in `collect_extracts()` output, tune opts to associate the hyperparameter
+#' combination used to fit the workflow that results in the extracted object
+#' with the extracted object, rather than with the `.config` entry that
+#' hyperparameter combination is usually associated with. In output, this
+#' appears like a hyperparameter entry is recycled across many `.config`
+#' entries---this is intentional.
+#'
+#' See \url{https://parsnip.tidymodels.org/articles/Submodels.html} to learn
+#' more about submodels.
+#'
 #' @examplesIf tune:::should_run_examples(suggests = "kknn")
 #' data("example_ames_knn")
 #' # The parameters for the model:

R/control.R

@@ -2,6 +2,8 @@
 #'
 #' @inheritParams control_bayes
 #'
+#' @inheritSection collect_predictions Hyperparameters and extracted objects
+#'
 #' @details
 #'
 #' For `extract`, this function can be used to output the model object, the
@@ -190,6 +192,8 @@ print.control_last_fit <- function(x, ...) {
 #' @param allow_par A logical to allow parallel processing (if a parallel
 #'   backend is registered).
 #'
+#' @inheritSection collect_predictions Hyperparameters and extracted objects
+#'
 #' @details
 #'
 #' For `extract`, this function can be used to output the model object, the

R/grid_code_paths.R

@@ -392,8 +392,6 @@ tune_grid_loop_iter <- function(split,
         outcome_names = outcome_names
       )
 
-      # FIXME: I think this might be wrong? Doesn't use submodel parameters,
-      # so `extracts` column doesn't list the correct parameters.
       iter_grid <- dplyr::bind_cols(
         iter_grid_preprocessor,
         iter_grid_model