Help for package ordered

Title:

'parsnip' Engines and Wrappers for Ordinal Classification Models

Version:

0.1.0

Description:

Bindings, methods, and tuners for using ordinal classification models with the 'parsnip' and 'dials' packages. These include the regularized elastic net ordinal regression of Wurm, Hanlon, and Rathouz (2021) <doi:10.18637/jss.v099.i06> in 'ordinalNet', the ordinal classification trees of Galimberti, Soffritti, and Di Maso (2012) <doi:10.18637/jss.v047.i10> in 'rpartScore', and the latent variable ordinal forests of Hornung (2020) <doi:10.1007/s00357-018-9302-x> in 'ordinalForest'.

License:

MIT + file LICENSE

Depends:

parsnip (≥ 1.5)

Imports:

cli, dials (≥ 1.4.3), purrr, rlang (≥ 1.1.4), tibble, tidyr

Suggests:

dplyr, MASS, ordinalNet, VGAM, rpartScore, ordinalForest, QSARdata, spelling, testthat (≥ 3.0.0)

Config/testthat/edition:

Encoding:

UTF-8

Language:

en-US

RoxygenNote:

7.3.3

NeedsCompilation:

Packaged:

2026-04-21 20:28:09 UTC; jasoncorybrunson

Author:

Max Kuhn

[aut], Jason Cory Brunson

[aut, cre], Posit Software PBC [cph]

Maintainer:

Jason Cory Brunson <cornelioid@gmail.com>

Repository:

CRAN

Date/Publication:

2026-04-21 21:22:15 UTC

ordered: parsnip Engines for Ordinal Regression Models

Description

ordered provides engines for ordinal regression models for the parsnip package. The models may have cumulative, sequential, or adjacent-category structure, and in future these may be disaggregated into separate model types. A vignette will provide thorough illustrations of ordered functionality. See below for examples of fitting ordinal regression models with ordered.

Author(s)

Maintainer: Jason Cory Brunson cornelioid@gmail.com (ORCID)

Authors:

Max Kuhn max@posit.co (ORCID)

Other contributors:

Posit Software PBC [copyright holder]

Examples

if (rlang::is_installed("MASS")) {

# Weighted sample

set.seed(561246)
house_sub <- MASS::housing %>%
  dplyr::sample_n(size = 120, replace = TRUE, weight = Freq) %>%
  subset(select = -Freq)
train_inds <- sample(120, 80)
house_train <- house_sub[train_inds, ]
house_test <- house_sub[-train_inds, ]

# Cumulative-link proportional-odds probit regression model

fit_cpop <- ordinal_reg() %>%
  set_engine("polr") %>%
  set_args(ordinal_link = "probit") %>%
  fit(Sat ~ Infl + Type + Cont, data = house_train)
predict(fit_cpop, house_test, type = "prob")

if (rlang::is_installed("ordinalForest")) {

# Ordinal forest

fit_orf <- rand_forest(mode = "classification") %>%
  set_engine("ordinalForest") %>%
  set_args(nsets = 50, ntreefinal = 100, perffunction = "probability") %>%
  fit(Sat ~ Infl + Type + Cont, data = house_train)
predict(fit_orf, house_test, type = "prob")

}
}

Wrappers for `VGAM`

Description

These wrappers convert the standardized odds_link options encoded in dials::values_odds_link to VGAM::vglmff objects passed to the family argument of VGAM::vglm() and VGAM::vgam().

Usage

VGAM_vglm_wrapper(
  formula,
  data,
  family = "cumulative_link",
  link = "logistic",
  parallel = TRUE,
  ...
)

VGAM_vgam_wrapper(
  formula,
  data,
  family = "cumulative_link",
  link = "logistic",
  parallel = TRUE,
  ...
)

values_ordinal_link_VGAM

Arguments

formula

The formula to pass.

data

The data frame to pass.

...

Additional arguments to pass.

Format

An object of class character of length 10.

Details

Note that VGAM::vglm() and VGAM::vgam() treat the rows of data as the units of observation: Compressed data with one row per predictor set will be understood as having a multinomial-valued outcome; only expanded data with one row per case will be understood as having a single-valued ordinal outcome. (This divide cannot be bridged by passing a column of counts to the weights argument.) These wrappers require a single ordinal outcome column and therefore do not accept the convenient cbind(y1, y2, ...) ~ x1 + x2 + ... encoding commonly used in VGAM.

Value

An object of S3 parent class VGAM and primary classes vglm or vgam as returned by VGAM::vglm() and VGAM::vgam().

Examples

values_ordinal_link_VGAM
dials::ordinal_link(values = values_ordinal_link_VGAM)

house_data <-
  MASS::housing[rep(seq(nrow(MASS::housing)), MASS::housing$Freq), -5]
# fit wrapper for linear model
( fit_orig <- VGAM::vglm(
  Sat ~ Type + Infl + Cont,
  family = VGAM::sratio(link = "probitlink", parallel = TRUE),
  data = house_data
) )
( fit_wrap <- VGAM_vglm_wrapper(
  Sat ~ Type + Infl + Cont,
  family = "stopping_ratio", link = "probit",
  data = house_data
) )
# fit wrapper for additive model
( fit_orig <- VGAM::vgam(
  Sat ~ Type + Infl + Cont,
  family = VGAM::cratio(link = "clogloglink", parallel = TRUE),
  data = house_data
) )
( fit_wrap <- VGAM_vgam_wrapper(
  Sat ~ Type + Infl + Cont,
  family = "continuation_ratio", link = "cloglog",
  data = house_data
) )

Dials for `ordinalForest` engine parameters

Description

These parameters are auxiliary to random forest models that use the "ordinalForest" engine. They correspond to tuning parameters that would be specified using set_engine("ordinalForest", ...).

Usage

naive_scores(values = c(FALSE, TRUE))

num_scores(range = c(100L, 2000L), trans = NULL)

num_score_perms(range = c(100L, 500L), trans = NULL)

num_score_trees(range = c(10L, 200L), trans = NULL)

num_scores_best(range = c(2L, 20L), trans = NULL)

ord_metric(values = values_ord_metric)

values_ord_metric

Arguments

values

A character string of possible values. See values_ord_metric.

range

A two-element vector holding the defaults for the smallest and largest possible values, respectively. If a transformation is specified, these values should be in the transformed units.

trans

A trans object from the scales package, such as scales::transform_log10() or scales::transform_reciprocal(). If not provided, the default is used which matches the units used in range. If no transformation, NULL.

Format

An object of class character of length 4.

Details

These functions generate parameters for parsnip::rand_forest() models using the "ordinalForest" engine. See ?ordinalForest::ordfor() for more details on the original parameters. These parameters are engine-specific, not general to decision tree models, so are provided here rather than in dials.

naive_scores(): Whether to construct only a "naive" ordinal forest using the scores 1,2,3,\ldots for the ordinal values; tunes naive.
num_scores(): The number of score sets tried prior to optimization; tunes nsets.
num_score_perms(): The number of permutations of the class width ordering to try for each score set tried (after the first); tunes npermtrial.
num_score_trees(): The number of trees in the score set–specific forests; tunes ntreeperdiv.
num_scores_best(): The number of top-performing score sets used to calculate the optimized score set; tunes nbest.
ord_metric(): The performance function used to evaluate score set–specific forests; tunes perffunction. See also ?ordinalForest::perff.

Value

An object of S3 parent class param and primary class qual_param or quant_param; see dials::new_qual_param() and [dials::new_quant_param().

Examples

naive_scores()
num_scores()
num_score_perms()
num_score_trees()
num_scores_best()
ord_metric()

A wrapper for `ordinalForest`

Description

A wrapper is needed since they have a non-standard model interface that required the data set and the column name (character string) for the outcome.

Usage

ordinalForest_wrapper(x, y, ...)

Arguments

x

The predictor data.

y

The outcome factor.

...

Arguments to pass to the underlying model function.

Value

An object of S3 class ordfor as returned by ordinalForest::ordfor().

Examples


house_data <-
  MASS::housing[rep(seq(nrow(MASS::housing)), MASS::housing$Freq), -5]
# subsample to reduce runtime
house_data <- house_data[sample(nrow(house_data), nrow(house_data) / 10), ]
# fit wrapper
# (using inadvisedly few score sets and trees to reduce runtime)
( fit_orig <- ordinalForest::ordfor(
  depvar = "Sat",
  data = house_data,
  nsets = 25, ntreefinal = 100
) )
( fit_wrap <- ordinalForest_wrapper(
  x = subset(house_data, select = -Sat),
  y = house_data$Sat,
  nsets = 25, ntreefinal = 100
) )

Wrappers for `ordinalNet`

Description

The fit wrapper converts the standardized odds_link options encoded in dials::values_odds_link to the family options of ordinalNet::ordinalNet(). The prediction wrapper interpolates between fitted penalties to enable submodel prediction at specified penalties.

Usage

ordinalNet_wrapper(
  x,
  y,
  weights = NULL,
  family = "cumulative_link",
  link = "logistic",
  ...
)

predict_ordinalNet_wrapper(
  object,
  newx,
  type,
  lambda,
  criteria = c("aic", "bic")
)

## S3 method for class ''_ordinalNet''
predict(
  object,
  new_data,
  type = NULL,
  opts = list(),
  penalty = NULL,
  multi = FALSE,
  ...
)

## S3 method for class ''_ordinalNet''
multi_predict(
  object,
  new_data,
  type = NULL,
  opts = list(),
  penalty = NULL,
  ...
)

## S3 method for class ''_ordinalNet''
predict_raw(object, new_data, opts = list(), ...)

## S3 method for class ''_ordinalNet''
predict_classprob(object, new_data, ...)

## S3 method for class ''_ordinalNet''
predict_class(object, new_data, ...)

Arguments

x

The predictor data.

y

The outcome vector.

...

Additional arguments to pass.

penalty

A numeric vector of penalty values.

Value

An object of S3 class ordinalNet as returned by ordinalNet::ordinalNet(), or a vector or matrix of predictions as returned by ordinalNet::predict.ordinalNet⁠()⁠.

Examples


house_data <-
  MASS::housing[rep(seq(nrow(MASS::housing)), MASS::housing$Freq), -5]
house_matrix <- model.matrix(
  Sat ~ Type + Infl + Cont + 0,
  data = house_data,
  contrasts.arg = lapply(house_data[, 2:4], contrasts, contrasts = FALSE)
)
pen_vec <- 10 ^ seq(-2.5, -.5, 1)
# fit wrapper
( fit_orig <- ordinalNet::ordinalNet(
  house_matrix, y = house_data$Sat,
  family = "sratio", link = "logit",
  lambdaVals = pen_vec
) )
( fit_wrap <- ordinalNet_wrapper(
  house_matrix, y = house_data$Sat,
  family = "stopping_ratio", link = "logistic",
  lambdaVals = pen_vec
) )
fit_tidy <-
  ordinal_reg(ordinal_link = "logistic", odds_link = "stopping_ratio") %>%
  set_engine("ordinalNet") %>%
  set_args(path_values = pen_vec, penalty = 1) %>%
  fit(formula = Sat ~ Type + Infl + Cont + 0, data = house_data)
fit_tidy$fit
# predict wrapper
predict(
  fit_orig,
  newx = head(house_matrix),
  whichLambda = 2,
  type = "response"
)
predict_ordinalNet_wrapper(
  fit_tidy$fit,
  newx = head(house_matrix),
  type = "prob",
  lambda = pen_vec[2]
)
predict_ordinalNet_wrapper(
  fit_tidy$fit,
  newx = head(house_matrix),
  type = "prob",
  lambda = .01
)

Dials for `rpartScore` engine parameters

Description

These parameters are auxiliary to decision tree models that use the "rpartScore" engine. They correspond to tuning parameters that would be specified using set_engine("rpartScore", ...).

Usage

split_func(values = c("abs", "quad"))

prune_func(values = c("mr", "mc"))

Arguments

values

A character string of possible values.

Details

split_func and prune_func are dials for split and prune, respectively. See ?rpartScore::rpartScore for more details on the original parameters. These parameters are engine-specific, not general to decision tree models, so are provided here rather than in dials.

Value

An object of S3 parent class param and primary class qual_param; see dials::new_qual_param().

Examples

split_func()
prune_func()

A wrapper for `rpartScore`

Description

A wrapper is used because the model interface requires the response variable to be numeric rather than ordered or factor; the wrapper edits the input data accordingly.

Usage

rpartScore_wrapper(formula, data, ...)

Arguments

formula

The formula to pass.

data

The data frame to pass.

...

Additional arguments to pass.

Value

An object of S3 class rpart as returned by rpartScore::rpartScore().

Examples


house_data <-
  MASS::housing[rep(seq(nrow(MASS::housing)), MASS::housing$Freq), -5]
# subsample to reduce runtime
house_data <- house_data[sample(nrow(house_data), nrow(house_data) / 5), ]
# fit wrapper
( fit_orig <- rpartScore::rpartScore(
  formula = Sat ~ Infl + Type + Cont,
  data = transform(house_data, Sat = as.integer(Sat))
) )
( fit_wrap <- rpartScore_wrapper(
  formula = Sat ~ Infl + Type + Cont,
  data = house_data
) )

ordered: parsnip Engines for Ordinal Regression Models

Description

Author(s)

Examples

Wrappers for VGAM

Description

Usage

Arguments

Format

Details

Value

Examples

Dials for ordinalForest engine parameters

Description

Usage

Arguments

Format

Details

Value

See Also

Examples

A wrapper for ordinalForest

Description

Usage

Arguments

Value

Examples

Wrappers for ordinalNet

Description

Usage

Arguments

Value

Examples

Dials for rpartScore engine parameters

Description

Usage

Arguments

Details

Value

See Also

Examples

A wrapper for rpartScore

Description

Usage

Arguments

Value

Examples

Wrappers for `VGAM`

Dials for `ordinalForest` engine parameters

A wrapper for `ordinalForest`

Wrappers for `ordinalNet`

Dials for `rpartScore` engine parameters

A wrapper for `rpartScore`