From e231ae890b11581f55d2d9ec98a7a81699f8c9b0 Mon Sep 17 00:00:00 2001
From: simonpcouch <simonpatrickcouch@gmail.com>
Date: Wed, 16 Oct 2024 09:46:05 -0700
Subject: [PATCH 1/5] add `buffer()` for `adjust_equivocal_zone()`

---
 NAMESPACE                    |  1 +
 R/param_buffer.R             | 26 ++++++++++++++++++++++++++
 man/buffer.Rd                | 25 +++++++++++++++++++++++++
 tests/testthat/test-params.R |  1 +
 4 files changed, 53 insertions(+)
 create mode 100644 R/param_buffer.R
 create mode 100644 man/buffer.Rd

diff --git a/NAMESPACE b/NAMESPACE
index a6cf4ca2..f4dd6048 100644
--- a/NAMESPACE
+++ b/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)
diff --git a/R/param_buffer.R b/R/param_buffer.R
new file mode 100644
index 00000000..62a57a7b
--- /dev/null
+++ b/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 buffer
+#' @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
+  )
+}
diff --git a/man/buffer.Rd b/man/buffer.Rd
new file mode 100644
index 00000000..1462eddb
--- /dev/null
+++ b/man/buffer.Rd
@@ -0,0 +1,25 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/param_buffer.R
+\name{buffer}
+\alias{buffer}
+\title{Buffer size}
+\usage{
+buffer(range = c(0, 0.5), trans = NULL)
+}
+\description{
+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."
+}
+\details{
+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 \code{min(threshold, 1 - threshold)}.
+}
+\examples{
+buffer()
+}
+\seealso{
+\code{\link[=threshold]{threshold()}}
+}
diff --git a/tests/testthat/test-params.R b/tests/testthat/test-params.R
index 70e114f6..639f5320 100644
--- a/tests/testthat/test-params.R
+++ b/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))

From 21ac622be4763c0c2c43ac27f757a088d8d56022 Mon Sep 17 00:00:00 2001
From: simonpcouch <simonpatrickcouch@gmail.com>
Date: Wed, 16 Oct 2024 09:56:39 -0700
Subject: [PATCH 2/5] add `*_limit()`s for `adjust_numeric_range()`

---
 NAMESPACE                    |  2 ++
 R/param_range_limits.R       | 37 ++++++++++++++++++++++++++++++++++++
 man/range_limits.Rd          | 30 +++++++++++++++++++++++++++++
 tests/testthat/test-params.R |  2 ++
 4 files changed, 71 insertions(+)
 create mode 100644 R/param_range_limits.R
 create mode 100644 man/range_limits.Rd

diff --git a/NAMESPACE b/NAMESPACE
index f4dd6048..4214e39c 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -94,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)
@@ -185,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)
diff --git a/R/param_range_limits.R b/R/param_range_limits.R
new file mode 100644
index 00000000..9b759531
--- /dev/null
+++ b/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
+  )
+}
diff --git a/man/range_limits.Rd b/man/range_limits.Rd
new file mode 100644
index 00000000..633173f6
--- /dev/null
+++ b/man/range_limits.Rd
@@ -0,0 +1,30 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/param_range_limits.R
+\name{range_limits}
+\alias{range_limits}
+\alias{lower_limit}
+\alias{upper_limit}
+\title{Limits for the range of predictions}
+\usage{
+lower_limit(range = c(-Inf, Inf), trans = NULL)
+
+upper_limit(range = c(-Inf, Inf), trans = NULL)
+}
+\arguments{
+\item{range}{A two-element vector holding the \emph{defaults} for the smallest and
+largest possible values, respectively. If a transformation is specified,
+these values should be in the \emph{transformed units}.}
+
+\item{trans}{A \code{trans} object from the \code{scales} package, such as
+\code{scales::transform_log10()} or \code{scales::transform_reciprocal()}. If not provided,
+the default is used which matches the units used in \code{range}. If no
+transformation, \code{NULL}.}
+}
+\description{
+Range limits truncate model predictions to a specific range of values,
+typically to avoid extreme or unrealistic predictions.
+}
+\examples{
+lower_limit()
+upper_limit()
+}
diff --git a/tests/testthat/test-params.R b/tests/testthat/test-params.R
index 639f5320..68f6eb6b 100644
--- a/tests/testthat/test-params.R
+++ b/tests/testthat/test-params.R
@@ -84,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))
 })
 
 

From bf96841c709b5b8f5ecaaf94e5e11a6c7752b4d7 Mon Sep 17 00:00:00 2001
From: simonpcouch <simonpatrickcouch@gmail.com>
Date: Wed, 16 Oct 2024 09:59:55 -0700
Subject: [PATCH 3/5] add NEWS entry

---
 NEWS.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/NEWS.md b/NEWS.md
index d15ebbc9..1d938332 100644
--- a/NEWS.md
+++ b/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

From d7e03e0fb4098ca3f5a985cefd9d0aec9fd2fad7 Mon Sep 17 00:00:00 2001
From: simonpcouch <simonpatrickcouch@gmail.com>
Date: Wed, 16 Oct 2024 10:05:29 -0700
Subject: [PATCH 4/5] correct `inheritParams`

---
 R/param_buffer.R |  2 +-
 man/buffer.Rd    | 10 ++++++++++
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/R/param_buffer.R b/R/param_buffer.R
index 62a57a7b..a9b058c8 100644
--- a/R/param_buffer.R
+++ b/R/param_buffer.R
@@ -9,7 +9,7 @@
 #' regardless of their value in \code{[0, 1]}.
 #' Otherwise, the maximum buffer is `min(threshold, 1 - threshold)`.
 #'
-#' @inheritParams buffer
+#' @inheritParams Laplace
 #' @seealso [threshold()]
 #' @examples
 #' buffer()
diff --git a/man/buffer.Rd b/man/buffer.Rd
index 1462eddb..00d3769f 100644
--- a/man/buffer.Rd
+++ b/man/buffer.Rd
@@ -6,6 +6,16 @@
 \usage{
 buffer(range = c(0, 0.5), trans = NULL)
 }
+\arguments{
+\item{range}{A two-element vector holding the \emph{defaults} for the smallest and
+largest possible values, respectively. If a transformation is specified,
+these values should be in the \emph{transformed units}.}
+
+\item{trans}{A \code{trans} object from the \code{scales} package, such as
+\code{scales::transform_log10()} or \code{scales::transform_reciprocal()}. If not provided,
+the default is used which matches the units used in \code{range}. If no
+transformation, \code{NULL}.}
+}
 \description{
 In equivocal zones, predictions are considered equivocal (i.e. "could
 go either way") if their probability falls within some distance on either

From 1a69084bc950f80865ddbf2e4908e17433e469de Mon Sep 17 00:00:00 2001
From: Hannah Frick <hannah@posit.co>
Date: Tue, 29 Oct 2024 15:46:28 +0000
Subject: [PATCH 5/5] update pkgdown index

---
 _pkgdown.yml | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/_pkgdown.yml b/_pkgdown.yml
index 68b4fb65..bb27589b 100644
--- a/_pkgdown.yml
+++ b/_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