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

As fast_ordinal_probit_regression_cpp (see that page for the full cumulative probit-link model, \(\Pr(Y_i \le k \mid x_i) = \Phi(\alpha_k - x_i^\top\beta)\)), but always fits with estimate_only = FALSE (equivalent to calling that function with its default), so the observed information matrix and variance-covariance matrix are always computed. It additionally guards the degenerate case: if y has fewer than 2 distinct levels (so the underlying fit is empty), this function returns list(b = NA, ssq_b_2 = NA) instead of an empty list.

Usage

fast_ordinal_probit_regression_with_var_cpp(
  X,
  y,
  warm_start_params = NULL,
  smart_cold_start = TRUE,
  optimization_alg = "lbfgs",
  fixed_idx = NULL,
  fixed_values = NULL,
  warm_start_fisher_info = NULL
)

Arguments

X

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

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.

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.

Value

A list with components b, alpha, params, n_params, neg_loglik, converged, iterations, observed_information/fisher_information/information (all the same observed-information matrix), information_type ("observed"), vcov, and ssq_b_2 (the variance of b[1], i.e. X's first-column coefficient — conventionally the treatment effect; NA if it comes out non-finite or non-positive). vcov is omitted (and ssq_b_2 is NA) if the fit did not converge; list(b = NA, ssq_b_2 = NA) 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.

See also

fast_ordinal_probit_regression_cpp for the estimate-only-capable variant and the full model documentation.