Fast Continuation-Ratio Regression, Direct MLE via Row Augmentation (C++ Backend)

Fits the (forward) continuation-ratio logit ordinal regression model: for cut \(j = 1, \dots, K-1\), \(\log \Pr(Y > j \mid Y \ge j) / \Pr(Y = j \mid Y \ge j) = \alpha_j + \beta^\top x\), i.e. the log-odds of continuing past cut \(j\) (rather than stopping there), among subjects who have reached it. This orientation — numerator is the higher-category event — keeps a positive \(\beta\) meaning "pushes toward higher categories of y", consistent with every other ordinal estimator in the package (contrast the cumulative-logit \(-x^T \beta\) convention in fast_ordinal_regression.cpp and the adjacent-category model's \(\Pr(Y = j+1 \mid \cdot)\) numerator), and matches expand_continuation_ratio_data_cpp() (a separate, standalone row-expansion utility not used by this backend, but documenting the same "continue past this cut" = 1 orientation). This backend fits the model as a single unconditional logistic regression MLE on an internally-built augmented design: build_continuation_ratio_augmented_data() constructs an augmented matrix X_aug with one dummy column per cut (n_alpha = K - 1 columns) followed by the original p covariate columns, and an augmented binary response z (1 = "continued past this cut", 0 = "stopped here"). Because the cut effects \(\alpha_j\) are simply K - 1 ordinary coefficients on dummy columns (not nuisance parameters requiring conditioning), an unconditional logistic fit on the augmented data is exactly equivalent to the continuation-ratio likelihood — no stratification/conditioning machinery is needed for this standalone use case.

Usage

fast_continuation_ratio_regression_cpp(
  X,
  y,
  maxit = 100L,
  tol = 1e-08,
  warm_start_beta = NULL,
  smart_cold_start = TRUE,
  fixed_idx = NULL,
  fixed_values = NULL,
  optimization_alg = "lbfgs",
  warm_start_fisher_info = NULL
)

Arguments

X

A numeric matrix of predictors, \(n \times p\) (no intercept column; threshold intercepts are estimated internally).

y

A numeric vector of length \(n\) giving each subject's ordinal category; need not be pre-coded 1:K (see Details).

maxit

Maximum number of optimizer iterations.

tol

Convergence tolerance.

warm_start_beta

Optional starting values for the full c(alpha, beta) parameter vector.

smart_cold_start

Logical. If TRUE, use an initial OLS-based guess when no warm start is provided.

fixed_idx

Optional integer indices (into the c(alpha, beta) parameter layout) of parameters to hold fixed rather than estimate.

fixed_values

Optional values to fix the parameters named by fixed_idx at.

optimization_alg

Optimization algorithm; see Details.

warm_start_fisher_info

Optional initial Fisher Information matrix (over the full c(alpha, beta) parameter vector) to warm-start curvature information.

Value

A list with components b (the shared covariate coefficients \(\hat\beta\), length p), alpha (the K - 1 estimated cut intercepts), params/beta_full (the full c(alpha, b) parameter vector, identical to each other), neg_loglik (the augmented-data logistic negative log-likelihood, which equals the continuation-ratio model's negative log-likelihood), X_aug/ z (the augmented design matrix and binary response actually fit, exposed for reuse, e.g. by get_continuation_ratio_regression_hessian_cpp()), converged (logical), and fisher_information (the exact observed information Hessian at the fitted parameters). See Details for the degenerate fewer-than-2-categories case, which returns a reduced subset of these fields.

Details

Category coding. As in expand_continuation_ratio_data_cpp(), distinct values of y are extracted and sorted; K is the number of distinct observed values (not an externally supplied count), and each observation contributes min(observed_level + 1, K - 1) augmented rows.

Parameter vector layout. The optimizer's parameter vector (returned as params/beta_full) is c(alpha_1, ..., alpha_{K-1}, beta_1, ..., beta_p). Optimized via optimization_alg ("lbfgs" default), for at most maxit iterations at tolerance tol; when no warm start is supplied, smart_cold_start = TRUE seeds the optimizer via OLS on the augmented binary response z. fixed_idx/fixed_values hold specific parameters (by index into this layout) fixed rather than estimated, and warm_start_fisher_info warm-starts curvature information.

Degenerate case. If y has fewer than 2 distinct observed values (K < 2), no model can be fit: the function returns early with b zeroed (length p) and an empty alpha, without attempting optimization or setting converged/neg_loglik/etc.

See also

expand_continuation_ratio_data_cpp() for the full continuation- ratio model equation and the shared row-augmentation logic; fast_continuation_ratio_regression_with_var_cpp for the variance-augmented variant; fast_adjacent_category_logit_cpp for the analogous direct-MLE fit of the adjacent-category (rather than continuation-ratio) ordinal model. Ordinal regression for orientation.