Fast Logistic Regression, Estimate Only (C++ Backend)

Fits the standard binary logistic regression model, \(\mathrm{logit}(\mu_i) = \Pr(Y_i = 1) \text{'s log-odds} = x_i^\top \beta\), \(\mu_i = \mathrm{logit}^{-1}(x_i^\top \beta)\), via maximum likelihood. Coefficients are directly interpretable as log odds ratios: \(e^{\beta_j}\) is the multiplicative change in the odds \(\mu_i / (1 - \mu_i)\) per unit change in covariate \(j\). This is the package's baseline binary-response fitting backend, used wherever an incidence/binary outcome needs a logit-link fit (as opposed to the log-link or identity-link constrained binomial models in fast_log_binomial_regression_cpp/ fast_identity_binomial_regression_cpp, which target relative risk / risk difference scales instead of odds ratios).

Usage

fast_logistic_regression_cpp(
  X,
  y,
  warm_start_beta = NULL,
  smart_cold_start = FALSE,
  maxit = 100L,
  tol = 1e-8,
  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 predictor variables. It is assumed that an intercept column (e.g., a column of ones) is already included in X if desired.
y: A numeric vector of the response variable, expected to be binary (0 or 1).
warm_start_beta: Optional starting values for coefficients \(\beta\). If provided, smart_cold_start is ignored.
smart_cold_start: Logical. If TRUE and no warm_start_beta is supplied, use an OLS-based initial guess rather than a zero cold start. Default FALSE for this function (unlike most of the package's other fast_* fitters, which default this to TRUE), since IRLS (the default optimizer here) is typically robust enough from a zero start for well-behaved logistic regression problems.
maxit: Maximum number of iterations for the algorithm. Defaults to 100.
tol: Convergence tolerance. Defaults to 1e-8.
fixed_idx: Optional integer indices of coefficients to hold fixed rather than estimate.
fixed_values: Optional values to fix the parameters named by fixed_idx at.
optimization_alg: Optimization algorithm: "irls" (default, classical iteratively-reweighted-least-squares Fisher scoring), "lbfgs", or "newton_raphson"; see .normalize_optimizer_algorithm.
warm_start_weights: Optional initial IRLS working weights for the first iteration.
warm_start_fisher_info: Optional initial Fisher Information matrix to warm-start curvature information.
estimate_only: Logical. If TRUE, skip the working-weights/ score/Fisher-information computation after convergence, returning only b, converged, num_iter, hit_iteration_cap, and gradient_norm.

Value

A list containing the following components:

b: A numeric vector of the estimated logistic regression coefficients \(\hat\beta\).
w: The IRLS working weights \(\hat\mu_i(1-\hat\mu_i)\) at the final iteration (the Bernoulli variance function evaluated at the fitted probabilities); omitted when estimate_only = TRUE.
num_iter: The number of optimizer iterations performed.
fisher_information: The working-weights curvature matrix \(X^\top W X\); omitted when estimate_only = TRUE.
score: The score (gradient of the log-likelihood) vector at the fitted coefficients; omitted when estimate_only = TRUE.
neg_ll: The negative log-likelihood at the fitted coefficients; omitted when estimate_only = TRUE.
converged: A logical value indicating whether the final gradient norm was below tol (gradient_norm < tol); uniform across the "irls"/"lbfgs" optimizers.
hit_iteration_cap: A logical value, mutually exclusive with converged: TRUE iff the optimizer exhausted maxit iterations without meeting the gradient-norm convergence criterion.
gradient_norm: The norm of the score vector at the returned coefficients, a diagnostic of how tightly the convergence criterion was met.

Usage

Arguments

Value

See also