dials for 'ordinal_reg' models (#435)

* add polr method (ordinal link function) as tuning parameter

* increment version number + update ordinal_link documentation

* draft new dials for rpartScore params

* typo

* move engine-specific dials to ordered

* oops - complete last commit

* introduce odds_link param

* note need to harmonize ordinal_link options

* add caution re engines and link functions

* add tests for ordinal_reg model params

* rename cumulative_logits to cumulative_link

* add news entry for ordinal_reg dials

* touch-ups

---------

Co-authored-by: Hannah Frick <hannah@posit.co>

Author: corybrunson

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: dials
 Title: Tools for Creating Tuning Parameter Values
-Version: 1.4.2.9000
+Version: 1.4.2.9001
 Authors@R: c(
     person("Max", "Kuhn", , "max@posit.co", role = "aut"),
     person("Hannah", "Frick", , "hannah@posit.co", role = c("aut", "cre")),

NAMESPACE

@@ -129,6 +129,8 @@ export(num_random_splits)
 export(num_runs)
 export(num_terms)
 export(num_tokens)
+export(odds_link)
+export(ordinal_link)
 export(over_ratio)
 export(parameters)
 export(parameters_constr)
@@ -206,6 +208,8 @@ export(values_activation)
 export(values_cal_cls)
 export(values_cal_reg)
 export(values_initial_umap)
+export(values_odds_link)
+export(values_ordinal_link)
 export(values_prune_method)
 export(values_regularization_method)
 export(values_scheduler)

NEWS.md

@@ -1,5 +1,7 @@
 # dials (development version)
 
+* `ordinal_link()` and `odds_link()` are two new parameters for the new `ordinal_reg()` models in parsnip (@corybrunson, #435).
+
 * A bug was fixed where some space-filling designs did not respect the `original` argument (#409).
 
 * Parameters were added for the `tab_pfn` model: `num_estimators()`, `softmax_temperature()`, `balance_probabilities()`, `average_before_softmax()`, and `training_set_limit()`.

R/param_ordinal_link.R

@@ -0,0 +1,60 @@
+#' Ordinal Regression Link Functions (character)
+#'
+#' The ordinal and odds link functions of an ordinal regression model.
+#'
+#' @param values For `*_link()`, a character string from among the possible
+#'   values encoded in `values_*_link`. See the examples below.
+#'
+#' @details These parameters are used by ordinal regression models specified by
+#'   `parsnip::ordinal_reg()`, for example `parsnip::set_engine('polr')`. The
+#'   nomenclature is taken from Wurm et al (2021), who characterize the pair of
+#'   functions as a composite link function. Note that different engines support
+#'   different subsets of link functions.
+#'
+#' @references Wurm, Michael J., Rathouz, Paul J., & Hanlon, Bret M. (2021).
+#'   Regularized Ordinal Regression and the ordinalNet R Package. _Journal of
+#'   Statistical Software_, 99(6), 1–42. 10.18637/jss.v099.i06
+#' @examples
+#' values_ordinal_link
+#' ordinal_link()
+#' values_odds_link
+#' odds_link()
+#' @export
+ordinal_link <- function(values = values_ordinal_link) {
+  new_qual_param(
+    type = "character",
+    values = values,
+    label = c(ordinal_link = "Ordinal Link"),
+    finalize = NULL
+  )
+}
+
+#' @rdname ordinal_link
+#' @export
+values_ordinal_link <- c(
+  "logistic",
+  "probit",
+  "loglog",
+  "cloglog",
+  "cauchit"
+)
+
+#' @rdname ordinal_link
+#' @export
+odds_link <- function(values = values_odds_link) {
+  new_qual_param(
+    type = "character",
+    values = values,
+    label = c(odds_link = "Odds Link"),
+    finalize = NULL
+  )
+}
+
+#' @rdname ordinal_link
+#' @export
+values_odds_link <- c(
+  "cumulative_link",
+  "adjacent_categories",
+  "continuation_ratio",
+  "stopping_ratio"
+)

_pkgdown.yml

@@ -84,6 +84,7 @@ reference:
   - num_comp
   - num_estimators
   - num_knots
+  - ordinal_link
   - penalty
   - predictor_prop
   - prune_method

man/ordinal_link.Rd

@@ -199,4 +199,8 @@ test_that("param values", {
   expect_equal(cal_method_reg()$values, values_cal_reg)
   expect_equal(balance_probabilities(TRUE)$values, TRUE)
   expect_equal(average_before_softmax(TRUE)$values, TRUE)
+  expect_equal(ordinal_link(letters[1:3])$values, letters[1:3])
+  expect_equal(ordinal_link()$values, values_ordinal_link)
+  expect_equal(odds_link(letters[4:6])$values, letters[4:6])
+  expect_equal(odds_link()$values, values_odds_link)
 })