give big-picture @description for each adjustment

Author: simonpcouch

R/adjust-equivocal-zone.R

@@ -1,5 +1,10 @@
 #' Apply an equivocal zone to a binary classification model.
 #'
+#' Equivocal zones describe intervals of predicted probabilities that are deemed
+#' too uncertain or ambiguous to be assigned a hard class. Rather than
+#' predicting a hard class when the probability is very close to a threshold,
+#' tailors using this adjustment predict "\[EQ\]".
+#'
 #' @param x A [tailor()].
 #' @param value A numeric value (between zero and 1/2) or [hardhat::tune()]. The
 #' value is the size of the buffer around the threshold.

R/adjust-numeric-range.R

@@ -1,5 +1,12 @@
 #' Truncate the range of numeric predictions
 #'
+#' @description
+#' Truncating ranges involves limiting the output of a model to a specific
+#' range of values, typically to avoid extreme or unrealistic predictions.
+#' This technique can help improve the practical applicability of a model's
+#' outputs by constraining them within reasonable bounds based on domain
+#' knowledge or physical limitations.
+#'
 #' @param x A [tailor()].
 #' @param upper_limit,lower_limit A numeric value, NA (for no truncation) or
 #' [hardhat::tune()].

R/adjust-predictions-custom.R

@@ -1,5 +1,8 @@
 #' Change or add variables
 #'
+#' This adjustment functions allows for arbitrary transformations of model
+#' predictions using [dplyr::mutate()] statements.
+#'
 #' @param x A [tailor()].
 #' @param .pkgs A character string of extra packages that are needed to execute
 #' the commands.

R/adjust-probability-calibration.R

@@ -1,5 +1,12 @@
 #' Re-calibrate classification probability predictions
 #'
+#' @description
+#' Calibration is the process of adjusting a model's outputted probabilities
+#' to match the observed frequencies of events. This technique aims to
+#' ensure that when a model predicts a certain probability for an outcome,
+#' that probability accurately reflects the true likelihood of that outcome
+#' occurring.
+#'
 #' @param x A [tailor()].
 #' @param method Character. One of `"logistic"`, `"multinomial"`,
 #' `"beta"`, `"isotonic"`, or `"isotonic_boot"`, corresponding to the

R/adjust-probability-threshold.R

@@ -1,5 +1,15 @@
 #' Change the event threshold
 #'
+#' @description
+#' Many machine learning systems determine hard class predictions by
+#' first predicting the probability of an event and then predicting that
+#' an event will occur if its respective probability is above 0.5. This
+#' adjustment allows practitioners to determine hard class predictions using
+#' a threshold other than 0.5. By setting appropriate thresholds, one can
+#' balance the trade-off between different types of errors (such as
+#' false positives and false negatives) to optimize the model's performance
+#' for specific use cases.
+#'
 #' @param x A [tailor()].
 #' @param threshold A numeric value (between zero and one) or [hardhat::tune()].
 #' @examplesIf rlang::is_installed("modeldata")