Export of C++ function fast_continuation_ratio_regression_with_var_cpp

Fits the same continuation-ratio model as fast_continuation_ratio_regression_cpp (see that page for the full model, row-augmentation mechanics, category coding, and parameter layout) and additionally computes the variance of the first covariate coefficient and (when converged) the full parameter variance-covariance matrix, from the same observed information Hessian.

Usage

fast_continuation_ratio_regression_with_var_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\)), ssq_b_j (the variance of the first covariate's coefficient), neg_loglik, vcov (the full parameter variance-covariance matrix, or NULL if not converged), converged (logical), params (the full c(alpha, b) parameter vector — cut intercepts are recoverable as params[1:n_alpha] but are not returned as a separate alpha field, unlike fast_continuation_ratio_regression_cpp), and fisher_information (the full observed information Hessian). See Details for the degenerate fewer-than-2-categories case, which returns a reduced subset of these fields.

Details

Variance computation. The observed information (Hessian of the augmented-data logistic negative log-likelihood, evaluated at the fitted parameters over all n_alpha + p parameters) is restricted to the free (non-fixed_idx) parameters. ssq_b_j — the variance of \(\hat\beta_1\) (the coefficient on the first covariate column of X, the package's usual treatment-effect position) — is obtained via a single targeted diagonal-entry inversion (compute_diagonal_inverse_entry()), not a full matrix inverse, and is NA if that coefficient is fixed via fixed_idx. The full vcov (over all n_alpha + p parameters, expanded back from the free-parameter block) is computed only when converged is TRUE (via covariance_from_information()); otherwise vcov is NULL.

Degenerate case. As in fast_continuation_ratio_regression_cpp, if y has fewer than 2 distinct observed values, the function returns early with b = NA_real_, ssq_b_j = NA_real_, and converged = FALSE, without vcov/params/fisher_information.

See also

fast_continuation_ratio_regression_cpp for the estimate-only variant and the full model/row-augmentation documentation.