Fast Cumulative Ordinal Regression with a Logit Link, i.e. Proportional-Odds Regression (C++)

Fits the classical proportional-odds ordinal regression model (a cumulative-link model with the logit link) via direct maximum likelihood, jointly optimizing the category thresholds and regression coefficients. y's distinct values (in sorted order, whatever their original coding) are treated as \(K\) ordered categories; for observation \(i\) in category \(k\) (\(k = 0, \ldots, K-1\)), $$\mathrm{logit}\,\Pr(Y_i \le k \mid x_i) = \alpha_k - x_i^\top \beta,$$ with \(\alpha_0 < \alpha_1 < \cdots < \alpha_{K-2}\) the (increasing) category thresholds and \(\beta\) the regression coefficients on X (no separate intercept column is needed — the thresholds serve that role); the category probability is the corresponding CDF difference, each clamped below at \(10^{-12}\) before taking logs for numerical safety. The "proportional odds" name reflects that \(\beta\) does not depend on \(k\): the odds ratio \(\exp(-\beta_j)\) for a unit increase in covariate \(j\) is the same across every cumulative cutpoint. If y has fewer than 2 distinct levels, fitting still proceeds with K = 1, n_alpha = 0 (degenerate: no thresholds to estimate); unlike the cauchit/probit/cloglog variants in this package, this function does not special-case that as an early return.

Usage

fast_ordinal_regression_cpp(
  X,
  y,
  warm_start_params = NULL,
  smart_cold_start = TRUE,
  maxit = 100L,
  tol = 1e-06,
  fixed_idx = NULL,
  fixed_values = NULL,
  optimization_alg = "lbfgs",
  warm_start_fisher_info = NULL,
  estimate_only = FALSE
)

Arguments

X

A numeric matrix of predictors (no intercept column needed; see Details).

y

A numeric vector of ordinal responses; only the rank order of distinct values matters, not their numeric coding.

warm_start_params

Optional starting values for \([\alpha, \beta]\). If provided, smart_cold_start is ignored.

smart_cold_start

Logical. If TRUE, use an initial OLS-based guess when starting from scratch (a "cold start") with no prior knowledge. This is ignored if a warm start is provided.

maxit

Maximum number of optimizer iterations.

tol

Convergence tolerance.

fixed_idx

Optional 1-indexed positions (into \([\alpha,\beta]\)) of parameters to hold fixed.

fixed_values

Optional values, parallel to fixed_idx, of the fixed parameters.

optimization_alg

Optimization algorithm (default "lbfgs").

warm_start_fisher_info

Optional initial curvature (Fisher/observed information) matrix.

estimate_only

If TRUE, skip the post-fit Hessian/variance computation and return only point estimates (faster). If FALSE (the default), also compute and return the observed information matrix and (if the resulting free-parameter information submatrix is invertible via Eigen::FullPivLU) the full variance-covariance matrix.

Value

A list with components b (the \(\beta\) coefficients), alpha (the \(K-1\) category thresholds), params (the concatenated \([\alpha, \beta]\) vector), n_params, converged, and iterations; when estimate_only = FALSE (the default), additionally neg_loglik, observed_information/fisher_information/information (all the same observed-information matrix), information_type (always "observed"), ssq_b_j (the variance of b[1], i.e. the coefficient on X's first column — conventionally the treatment effect, since X carries no separate intercept column here), and vcov (the full parameter covariance matrix) — the latter two are NA/omitted (vcov becomes NULL) if the free-parameter information matrix is not invertible.

Fixed parameters, warm starts, and optimization

fixed_idx (1-indexed into the combined \([\alpha, \beta]\) parameter vector, thresholds first) and fixed_values optionally hold a subset of parameters at caller-supplied constant values rather than estimating them. warm_start_params supplies starting values for \([\alpha, \beta]\) directly (skipping smart_cold_start); otherwise thresholds always start evenly spaced on \((-1, 1)\) at \(-1 + 2(k+1)/K\), and \(\beta\) starts at either zero, or (when smart_cold_start = TRUE, the default) an OLS fit of the rank-rescaled response \((y - 1)/(K - 1)\) on X — falling back silently to zero if that OLS solve is not well-posed. When smart_cold_start = TRUE and no warm_start_fisher_info is supplied, the Hessian at the starting values is additionally used to seed the optimizer's first-iteration curvature estimate. Optimization runs via optimization_alg (default "lbfgs") for up to maxit iterations or until the parameter/gradient change falls below tol.

See also

fast_ordinal_regression_weighted_cpp for the observation-weighted variant; fast_ordinal_regression_with_var_cpp, which additionally guards the non-invertible case with explicit NA placeholders.