add examples for all functions (#35)

Author: simonpcouch

R/adjust-equivocal-zone.R

@@ -5,23 +5,34 @@
 #' value is the size of the buffer around the threshold.
 #' @param threshold A numeric value (between zero and one) or [hardhat::tune()].
 #' @examplesIf rlang::is_installed("modeldata")
-#' library(dplyr)
 #' library(modeldata)
 #'
-#' post_obj <-
+#' head(two_class_example)
+#'
+#' # `predicted` gives hard class predictions based on probabilities
+#' two_class_example %>% count(predicted)
+#'
+#' # when probabilities are within (.25, .75), consider them equivocal
+#' tlr <-
 #'   tailor() %>%
 #'   adjust_equivocal_zone(value = 1 / 4)
 #'
+#' tlr
 #'
-#' post_res <- fit(
-#'   post_obj,
+#' # fit by supplying column names. situate in a modeling workflow
+#' # with `workflows::add_tailor()` to avoid having to do so manually
+#' tlr_fit <- fit(
+#'   tlr,
 #'   two_class_example,
 #'   outcome = c(truth),
 #'   estimate = c(predicted),
 #'   probabilities = c(Class1, Class2)
 #' )
 #'
-#' predict(post_res, two_class_example)
+#' tlr_fit
+#'
+#' # adjust hard class predictions
+#' predict(tlr_fit, two_class_example) %>% count(predicted)
 #' @export
 adjust_equivocal_zone <- function(x, value = 0.1, threshold = 1 / 2) {
   check_tailor(x)

R/adjust-numeric-calibration.R

@@ -6,26 +6,29 @@
 #' package [probably::cal_estimate_linear()],
 #' [probably::cal_estimate_isotonic()], or
 #' [probably::cal_estimate_isotonic_boot()], respectively.
-#' @examplesIf rlang::is_installed("modeldata")
-#' library(modeldata)
-#' library(probably)
+#' @examples
 #' library(tibble)
 #'
 #' # create example data
 #' set.seed(1)
-#' dat <- tibble(y = rnorm(100), y_pred = y/2 + rnorm(100))
+#' d_potato <- tibble(y = rnorm(100), y_pred = y/2 + rnorm(100))
+#' d_test <- tibble(y = rnorm(100), y_pred = y/2 + rnorm(100))
 #'
-#' dat
+#' d_potato
 #'
 #' # specify calibration
-#' reg_tailor <-
+#' tlr <-
 #'   tailor() %>%
 #'   adjust_numeric_calibration(method = "linear")
 #'
-#' # train tailor
-#' reg_tailor_trained <- fit(reg_tailor, dat, outcome = y, estimate = y_pred)
+#' # train tailor on a subset of data. situate in a modeling workflow with
+#' # `workflows::add_tailor()` to avoid having to specify column names manually
+#' tlr_fit <- fit(tlr, d_potato, outcome = y, estimate = y_pred)
 #'
-#' predict(reg_tailor_trained, dat)
+#' # apply to predictions on another subset of data
+#' d_test
+#'
+#' predict(tlr_fit, d_test)
 #' @export
 adjust_numeric_calibration <- function(x, method = NULL) {
   check_tailor(x, calibration_type = "numeric")

R/adjust-numeric-range.R

@@ -3,6 +3,26 @@
 #' @param x A [tailor()].
 #' @param upper_limit,lower_limit A numeric value, NA (for no truncation) or
 #' [hardhat::tune()].
+#'
+#' @examplesIf FALSE
+# # TODO: unskip -- fn currently requires estimate to be called `.pred` (#22)
+#' library(tibble)
+#'
+#' # create example data
+#' set.seed(1)
+#' d <- tibble(y = rnorm(100), y_pred = y/2 + rnorm(100))
+#' d
+#'
+#' # specify calibration
+#' tlr <-
+#'   tailor() %>%
+#'   adjust_numeric_range(lower_limit = 1)
+#'
+#' # train tailor by passing column names. situate in a modeling workflow with
+#' # `workflows::add_tailor()` to avoid having to specify column names manually
+#' tlr_fit <- fit(tlr, d, outcome = y, estimate = y_pred)
+#'
+#' predict(tlr_fit, d)
 #' @export
 adjust_numeric_range <- function(x, lower_limit = -Inf, upper_limit = Inf) {
   # remaining input checks are done via probably::bound_prediction

R/adjust-predictions-custom.R

@@ -5,24 +5,24 @@
 #' the commands.
 #' @param ... Name-value pairs of expressions. See [dplyr::mutate()].
 #' @examplesIf rlang::is_installed("modeldata")
-#' library(dplyr)
 #' library(modeldata)
 #'
-#' post_obj <-
+#' head(two_class_example)
+#'
+#' tlr <-
 #'   tailor() %>%
 #'   adjust_equivocal_zone() %>%
 #'   adjust_predictions_custom(linear_predictor = binomial()$linkfun(Class2))
 #'
-#'
-#' post_res <- fit(
-#'   post_obj,
+#' tlr_fit <- fit(
+#'   tlr,
 #'   two_class_example,
 #'   outcome = c(truth),
 #'   estimate = c(predicted),
 #'   probabilities = c(Class1, Class2)
 #' )
 #'
-#' predict(post_res, two_class_example)
+#' predict(tlr_fit, two_class_example) %>% head()
 #' @export
 adjust_predictions_custom <- function(x, ..., .pkgs = character(0)) {
   check_tailor(x)

R/adjust-probability-calibration.R

@@ -5,6 +5,40 @@
 #' `"beta"`, `"isotonic"`, or `"isotonic_boot"`, corresponding to the
 #' function from the \pkg{probably} package [probably::cal_estimate_logistic()],
 #' [probably::cal_estimate_multinomial()], etc., respectively.
+#'
+# TODO: see #36
+#' @examplesIf FALSE
+# @examplesIf rlang::is_installed("modeldata")
+#' library(modeldata)
+#'
+#' # split example data
+#' set.seed(1)
+#' in_rows <- sample(c(TRUE, FALSE), nrow(two_class_example), replace = TRUE)
+#' d_potato <- two_class_example[in_rows, ]
+#' d_test <- two_class_example[!in_rows, ]
+#'
+#' head(d_potato)
+#'
+#' # specify calibration
+#' tlr <-
+#'   tailor() %>%
+#'   adjust_probability_calibration(method = "logistic")
+#'
+#' # train tailor on a subset of data. situate in a modeling workflow with
+#' # `workflows::add_tailor()` to avoid having to specify column names manually
+#' tlr_fit <- fit(
+#'   tlr,
+#'   d_potato,
+#'   outcome = c(truth),
+#'   estimate = c(predicted),
+#'   probabilities = c(Class1, Class2)
+#' )
+#'
+#' # apply to predictions on another subset of data
+#' head(d_test)
+#'
+#' predict(tlr_fit, d_test)
+#'
 #' @export
 adjust_probability_calibration <- function(x, method = NULL) {
   check_tailor(x, calibration_type = "probability")

R/adjust-probability-threshold.R

@@ -3,24 +3,28 @@
 #' @param x A [tailor()].
 #' @param threshold A numeric value (between zero and one) or [hardhat::tune()].
 #' @examplesIf rlang::is_installed("modeldata")
-#' library(dplyr)
 #' library(modeldata)
 #'
-#' post_obj <-
-#'   tailor() %>%
-#'   adjust_probability_threshold(threshold = .1)
+#' # `predicted` gives hard class predictions based on probability threshold .5
+#' head(two_class_example)
 #'
-#' two_class_example %>% count(predicted)
+#' # use a threshold of .1 instead:
+#' tlr <-
+#'   tailor() %>%
+#'   adjust_probability_threshold(.1)
 #'
-#' post_res <- fit(
-#'   post_obj,
+#' # fit by supplying column names. situate in a modeling workflow
+#' # with `workflows::add_tailor()` to avoid having to do so manually
+#' tlr_fit <- fit(
+#'   tlr,
 #'   two_class_example,
 #'   outcome = c(truth),
 #'   estimate = c(predicted),
 #'   probabilities = c(Class1, Class2)
 #' )
 #'
-#' predict(post_res, two_class_example) %>% count(predicted)
+#' # adjust hard class predictions
+#' predict(tlr_fit, two_class_example) %>% head()
 #' @export
 adjust_probability_threshold <- function(x, threshold = 0.5) {
   check_tailor(x)

R/tailor.R

@@ -28,7 +28,6 @@
 #' classification, these should be given in the order of the factor levels of
 #' the `estimate`.
 #' @examplesIf rlang::is_installed("modeldata")
-#' library(dplyr)
 #' library(modeldata)
 #'
 #' # `predicted` gives hard class predictions based on probabilities