add sections on data usage for each adjustment (closes #35)

Author: simonpcouch

R/adjust-equivocal-zone.R

@@ -9,6 +9,13 @@
 #' @param value A numeric value (between zero and 1/2) or [hardhat::tune()]. The
 #' value is the size of the buffer around the threshold.
 #' @param threshold A numeric value (between zero and one) or [hardhat::tune()].
+#'
+#' @section Data Usage:
+#' This adjustment doesn't require estimation and, as such, the same data that's
+#' used to train it with `fit()` can be predicted on with `predict()`; fitting
+#' this adjustment just collects metadata on the supplied column names and does
+#' not risk data leakage.
+#'
 #' @examplesIf rlang::is_installed("modeldata")
 #' library(modeldata)
 #'

R/adjust-numeric-calibration.R

@@ -1,11 +1,26 @@
 #' Re-calibrate numeric predictions
 #'
+#' @description
+#' Calibration for regression models involves adjusting the model's
+#' predictions to adjust for correlated errors, ensuring that predicted
+#' values align closely with actual observed values across the entire
+#' range of outputs.
+#'
 #' @param x A [tailor()].
 #' @param method Character. One of `"linear"`, `"isotonic"`, or
 #' `"isotonic_boot"`, corresponding to the function from the \pkg{probably}
 #' package [probably::cal_estimate_linear()],
 #' [probably::cal_estimate_isotonic()], or
 #' [probably::cal_estimate_isotonic_boot()], respectively.
+#'
+#' @section Data Usage:
+#' This adjustment requires estimation and, as such, different subsets of data
+#' should be used to train it and evaluate its predictions. See the section
+#' by the same name in [workflows::add_tailor()] for more information on
+#' preventing data leakage with postprocessors that require estimation. When
+#' situated in a workflow, tailors will automatically be estimated with
+#' appropriate subsets of data.
+#'
 #' @examples
 #' library(tibble)
 #'

R/adjust-numeric-range.R

@@ -11,6 +11,8 @@
 #' @param upper_limit,lower_limit A numeric value, NA (for no truncation) or
 #' [hardhat::tune()].
 #'
+#' @inheritSection adjust_equivocal_zone Data Usage
+#'
 #' @examplesIf FALSE
 # # TODO: unskip -- fn currently requires estimate to be called `.pred` (#22)
 #' library(tibble)

R/adjust-predictions-custom.R

@@ -7,6 +7,9 @@
 #' @param .pkgs A character string of extra packages that are needed to execute
 #' the commands.
 #' @param ... Name-value pairs of expressions. See [dplyr::mutate()].
+#'
+#' @inheritSection adjust_equivocal_zone Data Usage
+#'
 #' @examplesIf rlang::is_installed("modeldata")
 #' library(modeldata)
 #'

R/adjust-probability-calibration.R

@@ -13,6 +13,8 @@
 #' function from the \pkg{probably} package [probably::cal_estimate_logistic()],
 #' [probably::cal_estimate_multinomial()], etc., respectively.
 #'
+#' @inheritSection adjust_numeric_calibration Data Usage
+#'
 # TODO: see #36
 #' @examplesIf FALSE
 # @examplesIf rlang::is_installed("modeldata")

R/adjust-probability-threshold.R

@@ -12,6 +12,9 @@
 #'
 #' @param x A [tailor()].
 #' @param threshold A numeric value (between zero and one) or [hardhat::tune()].
+#'
+#' @inheritSection adjust_equivocal_zone Data Usage
+#'
 #' @examplesIf rlang::is_installed("modeldata")
 #' library(modeldata)
 #'