dials for threshold structure and parallel regression assumption arguments

NAMESPACE

@@ -148,6 +148,7 @@ export(num_tokens)
 export(odds_link)
 export(ordinal_link)
 export(over_ratio)
+export(parallel_reg)
 export(parameters)
 export(parameters_constr)
 export(penalty)
@@ -209,6 +210,7 @@ export(svm_margin)
 export(target_token)
 export(target_weight)
 export(threshold)
+export(threshold_structure)
 export(token)
 export(training_set_limit)
 export(tree_depth)
@@ -234,6 +236,7 @@ export(values_initial_umap)
 export(values_normalization)
 export(values_odds_link)
 export(values_ordinal_link)
+export(values_parallel_reg)
 export(values_penalty_type)
 export(values_prune_method)
 export(values_regularization_method)
@@ -243,6 +246,7 @@ export(values_surv_dist)
 export(values_survival_link)
 export(values_test_statistic)
 export(values_test_type)
+export(values_threshold_structure)
 export(values_token)
 export(values_weight_func)
 export(values_weight_scheme)

NEWS.md

@@ -1,5 +1,7 @@
 # dials (development version)
 
+* `threshold_structure()` and `parallel_reg()` are new parameter dials for the `ordinal_reg()` model. They respectively control threshold constraints and the parallel regression assumption (applied to all terms).
+
 # dials 1.4.4
 
 * `attention_type()`, `dropout_hidden()`, `dropout_last()`, and `target_token()` are new parameters for the SAINT model in the brulee package (#452).

R/param_parallel_reg.R

@@ -0,0 +1,30 @@
+#' Parallel Regression Specification (logical)
+#'
+#' Whether and how the parallel regression assumption is relaxed in an ordinal
+#' regression model.
+#'
+#' @param values A logical value or `NULL`. See the examples below.
+#'
+#' @details This parameter is used by ordinal regression models specified by
+#'   `parsnip::ordinal_reg()`, for example `parsnip::set_engine("clm")`. It
+#'   controls whether the regression coefficients are shared across all ordinal
+#'   thresholds (e.g. proportional odds in logit-linked models) or allowed to
+#'   vary (generalized ordered logit). `TRUE` makes all effects parallel,
+#'   `FALSE` makes all effects nominal or category-specific. The default is
+#'   `NULL`, which uses the engine default.
+#' @examples
+#' values_parallel_reg
+#' parallel_reg()
+#' @export
+parallel_reg <- function(values = values_parallel_reg) {
+  new_qual_param(
+    type = "logical",
+    values = values,
+    label = c(parallel_reg = "Parallel Regression"),
+    finalize = NULL
+  )
+}
+
+#' @rdname parallel_reg
+#' @export
+values_parallel_reg <- c(TRUE, FALSE)

R/param_threshold_structure.R

@@ -0,0 +1,33 @@
+#' Threshold structure (character)
+#'
+#' The threshold structure for the cutpoints of an ordinal regression model.
+#'
+#' @param values A character string of possible values. See the examples below.
+#'
+#' @details This parameter is used by ordinal regression models specified by
+#'   `parsnip::ordinal_reg()`, for example `parsnip::set_engine("clm")`. It
+#'   controls how thresholds/cutpoints are constrained. The default is
+#'   `"flexible"` (no constraints). Other options include symmetric and
+#'   equidistant structures. Different engines support different subsets of
+#'   threshold structures.
+#' @examples
+#' values_threshold_structure
+#' threshold_structure()
+#' @export
+threshold_structure <- function(values = values_threshold_structure) {
+  new_qual_param(
+    type = "character",
+    values = values,
+    label = c(threshold_structure = "Threshold Structure"),
+    finalize = NULL
+  )
+}
+
+#' @rdname threshold_structure
+#' @export
+values_threshold_structure <- c(
+  "flexible",
+  "symmetric_median",
+  "symmetric_zero",
+  "equidistant"
+)

_pkgdown.yml

@@ -91,6 +91,7 @@ reference:
   - num_knots
   - ordinal_link
   - penalty
+  - threshold_structure
   - predictor_prop
   - prune_method
   - starts_with("rate_")