Fast Cumulative Ordinal Regression with a Probit Link (C++)

Fits a cumulative-link ordinal regression model with the probit link (the standard normal CDF) 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$), $$\Pr(Y_i \le k \mid x_i) = \Phi(\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, $\Pr(Y_i = k \mid x_i) = \Phi(\alpha_k - x_i^\top\beta) - \Phi(\alpha_{k-1} - x_i^\top\beta)$ (with $\Phi(\alpha_{-1} - \cdot) := 0$ and $\Phi(\alpha_{K-1} - \cdot) := 1$ at the boundaries), each clamped below at $10^{-12}$ before taking logs for numerical safety. This is the ordinal generalization of probit regression, and the thin-tailed counterpart to fast_ordinal_cauchit_regression_cpp and the standard-logit ordinal model. If y has fewer than 2 distinct levels, an empty result list is returned (the model is degenerate).

Usage

fast_ordinal_probit_regression_cpp(
  X,
  y,
  warm_start_params = NULL,
  smart_cold_start = TRUE,
  maxit = 100L,
  tol = 1e-06,
  optimization_alg = "lbfgs",
  fixed_idx = NULL,
  fixed_values = NULL,
  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.
optimization_alg: Optimization algorithm (default "lbfgs").
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.
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, when the fit converged, the full variance-covariance matrix (identical to what fast_ordinal_probit_regression_with_var_cpp always computes).

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) and the fit converged, additionally neg_loglik, observed_information/fisher_information/information (all the same observed-information matrix), information_type (always "observed"), vcov (the parameter covariance matrix), and 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; the thresholds alpha play that role — set to NA if it comes out non-finite or non-positive). Empty if y has fewer than 2 distinct levels.

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, when smart_cold_start = TRUE (the default), starting values come from an OLS-based heuristic, and when FALSE, thresholds start at $\Phi^{-1}(k/K)$ (inverse-normal spacing of the empirical marginal category proportions) with $\beta$ at zero. Optimization runs via optimization_alg (default "lbfgs") for up to maxit iterations or until the parameter/gradient change falls below tol; warm_start_fisher_info, if supplied, seeds the first iteration's curvature estimate.

Usage

Arguments

Value

Fixed parameters, warm starts, and optimization

See also