diff --git a/DESCRIPTION b/DESCRIPTION index 9c2fa2b6..bbb76bc6 100644 --- a/DESCRIPTION +++ b/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")), diff --git a/NAMESPACE b/NAMESPACE index b794e52a..a9324c67 100644 --- a/NAMESPACE +++ b/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) diff --git a/NEWS.md b/NEWS.md index b9e49d5c..2d269989 100644 --- a/NEWS.md +++ b/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()`. diff --git a/R/param_ordinal_link.R b/R/param_ordinal_link.R new file mode 100644 index 00000000..c15a0439 --- /dev/null +++ b/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" +) diff --git a/_pkgdown.yml b/_pkgdown.yml index d1ec29a2..d5494ff6 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -84,6 +84,7 @@ reference: - num_comp - num_estimators - num_knots + - ordinal_link - penalty - predictor_prop - prune_method diff --git a/man/ordinal_link.Rd b/man/ordinal_link.Rd new file mode 100644 index 00000000..058f7340 --- /dev/null +++ b/man/ordinal_link.Rd @@ -0,0 +1,49 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/param_ordinal_link.R +\docType{data} +\name{ordinal_link} +\alias{ordinal_link} +\alias{values_ordinal_link} +\alias{odds_link} +\alias{values_odds_link} +\title{Ordinal Regression Link Functions (character)} +\format{ +An object of class \code{character} of length 5. + +An object of class \code{character} of length 4. +} +\usage{ +ordinal_link(values = values_ordinal_link) + +values_ordinal_link + +odds_link(values = values_odds_link) + +values_odds_link +} +\arguments{ +\item{values}{For \verb{*_link()}, a character string from among the possible +values encoded in \verb{values_*_link}. See the examples below.} +} +\description{ +The ordinal and odds link functions of an ordinal regression model. +} +\details{ +These parameters are used by ordinal regression models specified by +\code{parsnip::ordinal_reg()}, for example \code{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. +} +\examples{ +values_ordinal_link +ordinal_link() +values_odds_link +odds_link() +} +\references{ +Wurm, Michael J., Rathouz, Paul J., & Hanlon, Bret M. (2021). +Regularized Ordinal Regression and the ordinalNet R Package. \emph{Journal of +Statistical Software}, 99(6), 1–42. 10.18637/jss.v099.i06 +} +\keyword{datasets} diff --git a/tests/testthat/test-params.R b/tests/testthat/test-params.R index 7a94ace5..6fa0b825 100644 --- a/tests/testthat/test-params.R +++ b/tests/testthat/test-params.R @@ -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) })