add parameters for postprocessing with tailor (#358)

* add `buffer()` for `adjust_equivocal_zone()`

* add `*_limit()`s for `adjust_numeric_range()`

* add NEWS entry

* correct `inheritParams`

* update pkgdown index

---------

Co-authored-by: Hannah Frick <[email protected]>

NAMESPACE

@@ -52,6 +52,7 @@ export(activation_2)
 export(adjust_deg_free)
 export(all_neighbors)
 export(batch_size)
+export(buffer)
 export(class_weights)
 export(conditional_min_criterion)
 export(conditional_test_statistic)
@@ -93,6 +94,7 @@ export(is_unknown)
 export(kernel_offset)
 export(learn_rate)
 export(loss_reduction)
+export(lower_limit)
 export(lower_quantile)
 export(max_nodes)
 export(max_num_terms)
@@ -184,6 +186,7 @@ export(unbiased_rules)
 export(under_ratio)
 export(unique_cut)
 export(unknown)
+export(upper_limit)
 export(validation_set_prop)
 export(value_inverse)
 export(value_sample)

NEWS.md

@@ -1,5 +1,12 @@
 # dials (development version)
 
+* Added three new parameters for use in postprocessing in the tailor package (#357).
+     - `buffer()` sets the distance on either side of a classification threshold 
+       within which predictions are considered equivocal in 
+       `tailor::adjust_equivocal_zone()`.
+     - `lower_limit()` and `upper_limit()` sets the ranges for
+       numeric predictions in `tailor::adjust_numeric_range()`.
+
 * All messages, warnings and errors has been translated to use {cli} package (#311). 
 
 # dials 1.3.0

R/param_buffer.R

@@ -0,0 +1,26 @@
+#' Buffer size
+#'
+#' In equivocal zones, predictions are considered equivocal (i.e. "could
+#' go either way") if their probability falls within some distance on either
+#' side of the classification threshold. That distance is called the "buffer."
+#'
+#' A buffer of .5 is only possible if the classification threshold is .5.
+#' In that case, all probability predictions are considered equivocal,
+#' regardless of their value in \code{[0, 1]}.
+#' Otherwise, the maximum buffer is `min(threshold, 1 - threshold)`.
+#'
+#' @inheritParams Laplace
+#' @seealso [threshold()]
+#' @examples
+#' buffer()
+#' @export
+buffer <- function(range = c(0, .5), trans = NULL) {
+  new_quant_param(
+    type = "double",
+    range = range,
+    inclusive = c(TRUE, TRUE),
+    trans = trans,
+    label = c(buffer = "buffer"),
+    finalize = NULL
+  )
+}

R/param_range_limits.R

@@ -0,0 +1,37 @@
+#' Limits for the range of predictions
+#'
+#' Range limits truncate model predictions to a specific range of values,
+#' typically to avoid extreme or unrealistic predictions.
+#'
+#' @inheritParams Laplace
+#' @examples
+#' lower_limit()
+#' upper_limit()
+#' @name range_limits
+#' @export
+
+#' @rdname range_limits
+#' @export
+lower_limit <- function(range = c(-Inf, Inf), trans = NULL) {
+  new_quant_param(
+    type = "double",
+    range = range,
+    inclusive = c(TRUE, FALSE),
+    trans = trans,
+    label = c(lower_limit = "Lower Limit"),
+    finalize = NULL
+  )
+}
+
+#' @rdname range_limits
+#' @export
+upper_limit <- function(range = c(-Inf, Inf), trans = NULL) {
+  new_quant_param(
+    type = "double",
+    range = range,
+    inclusive = c(FALSE, TRUE),
+    trans = trans,
+    label = c(upper_limit = "Upper Limit"),
+    finalize = NULL
+  )
+}

_pkgdown.yml

@@ -112,6 +112,11 @@ reference:
     - scale_pos_weight
     - shrinkage_correlation
 
+  - title: Parameter objects for post-processing
+    contents:
+    - buffer
+    - range_limits
+
   - title: Finalizing parameters
     contents:
     - finalize

tests/testthat/test-params.R

@@ -4,6 +4,7 @@ test_that("param ranges", {
   expect_equal(sample_size(1:2)$range, list(lower = 1L, upper = 2L))
   expect_equal(learn_rate(c(.1, .9))$range, list(lower = 0.1, upper = 0.9))
   expect_equal(loss_reduction(c(.1, .9))$range, list(lower = 0.1, upper = 0.9))
+  expect_equal(buffer(c(0, .25))$range, list(lower = 0, upper = .25))
   expect_equal(cost_complexity(c(.1, .9))$range, list(lower = 0.1, upper = 0.9))
   expect_equal(epochs(1:2)$range, list(lower = 1L, upper = 2L))
   expect_equal(degree()$range, list(lower = 1, upper = 3))
@@ -83,6 +84,8 @@ test_that("param ranges", {
   expect_equal(harmonic_frequency(c(2, 100))$range, list(lower = 2, upper = 100))
   expect_equal(validation_set_prop(c(0.1, 0.4))$range, list(lower = 0.1, upper = 0.4))
   expect_equal(target_weight(c(0.1, 0.4))$range, list(lower = 0.1, upper = 0.4))
+  expect_equal(lower_limit(c(Inf, 0))$range, list(lower = Inf, upper = 0))
+  expect_equal(upper_limit(c(0, Inf))$range, list(lower = 0, upper = Inf))
 })