Fast Probit Regression, Estimate-Capable (C++)

Fits binary probit regression, \(Y_i \sim \mathrm{Bernoulli}(\Phi(\eta_i))\), \(\eta_i = x_i^\top\beta\), by maximum likelihood, using a numerically stable log-scale evaluation of \(\Phi\) (log_pnorm_lower/log_pnorm_upper, matching pnorm's log.p = TRUE for \(|\eta| < 6\) via a erfc-based identity, and falling back to a wider-range series approximation beyond that). By default (optimization_alg = "irls"), fitting uses iteratively reweighted least squares with working weights \(w_i = \phi(\eta_i)^2 / \max(\Phi(\eta_i)(1-\Phi(\eta_i)), 10^{-15})\) (the standard probit Fisher-scoring weight) and generalized residual \(r_i = y_i\,\phi(\eta_i)/\Phi(\eta_i) - (1-y_i)\,\phi(\eta_i)/(1-\Phi(\eta_i))\): each iteration solves \(X^\top W X\, \delta = X^\top r\) via Eigen::LDLT and takes the full Newton step (no step-halving line search), declaring convergence when either the score norm or the step norm falls below tol. Any optimization_alg value other than "lbfgs" runs this IRLS path; optimization_alg = "lbfgs" instead minimizes the exact negative log-likelihood directly via a bespoke L-BFGS driver with backtracking strong-Wolfe line search (mirroring RcppNumerical's optim_lbfgs defaults), bypassing IRLS entirely — in that path, warm_start_fisher_info is not consulted.

Usage

fast_probit_regression_cpp(
  X,
  y,
  warm_start_beta = NULL,
  smart_cold_start = TRUE,
  maxit = 100L,
  tol = 1e-08,
  fixed_idx = NULL,
  fixed_values = NULL,
  optimization_alg = "irls",
  warm_start_weights = NULL,
  warm_start_fisher_info = NULL,
  estimate_only = FALSE
)

Arguments

X: A numeric matrix of predictors (including an intercept column, if desired).
y: A numeric vector of binary responses (0/1).
warm_start_beta: Optional starting values for coefficients \(\beta\). If provided, smart_cold_start is ignored.
smart_cold_start: Logical. If TRUE (the default) and no warm_start_beta is supplied, use an OLS-based initial guess (see Details).
maxit: Maximum number of iterations (IRLS path only).
tol: Convergence tolerance.
fixed_idx: Optional indices of fixed parameters.
fixed_values: Optional values for fixed parameters.
optimization_alg: Optimization algorithm: any value other than "lbfgs" runs IRLS (default "irls"); "lbfgs" runs direct likelihood minimization.
warm_start_weights: Accepted but unused; see Details.
warm_start_fisher_info: Optional initial curvature matrix for the first IRLS iteration (IRLS path only).
estimate_only: If TRUE, skip the post-fit weight/curvature computation and return only b, converged, and iterations.

Value

If estimate_only = TRUE: a list with b, converged, iterations. Otherwise: a list additionally containing w (the final probit IRLS working weights, evaluated at the fitted \(\hat\beta\) regardless of which optimization_alg was used), fisher_information (\(X^\top W X\) at those weights), score, and neg_ll (the negative log-likelihood).

Fixed parameters, warm starts

fixed_idx and fixed_values optionally hold a subset of coefficients fixed at caller-supplied constant values (folded into the linear predictor as an offset) rather than estimated. warm_start_beta supplies starting coefficients directly; otherwise, if smart_cold_start = TRUE (the default), an OLS fit of the probit-transformed response \(\Phi^{-1}((y+0.5)/2)\) on X seeds the start. warm_start_fisher_info, if supplied, seeds the curvature matrix used for the IRLS path's very first iteration only (see above for the "lbfgs" exception). warm_start_weights is accepted for interface parity with sibling functions but is not consulted anywhere in this function's fitting logic.

Usage

Arguments

Value

Fixed parameters, warm starts

See also