Skip to contents

Fast Poisson Regression, Estimate-Only (C++ Backend)

Source: R/helper_glm_fit.R
fast_poisson_regression_cpp.Rd

Fits a Poisson regression with the canonical log link, \(Y_i \sim \mathrm{Poisson}(\mu_i)\), \(\mu_i = \exp(x_i^\top\beta)\) (with \(\eta_i = x_i^\top\beta\) clamped above at 700 before exponentiating, to avoid overflow), by maximum likelihood. By default (optimization_alg = "irls"), fitting uses iteratively reweighted least squares: at each iteration the Fisher-scoring (Poisson canonical-link, so Fisher = observed) system \(X^\top W X \, \delta = X^\top(y - \mu)\) is solved via Eigen::LDLT, with a backtracking step-halving line search (up to 10 halvings) accepting the step only if it does not increase the negative log-likelihood; convergence is declared when the score norm falls below tol. Passing optimization_alg = "lbfgs" or "newton_raphson" instead routes through the generic likelihood optimizer (.normalize_optimizer_algorithm) on the raw (non-IRLS) negative log-likelihood/gradient/Hessian.

Usage

fast_poisson_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 nonnegative-integer counts.

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 a Poisson-specific heuristic initial guess rather than a zero cold start.

maxit

Maximum number of iterations. 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), "lbfgs", or "newton_raphson".

warm_start_weights

Accepted but unused; see Details.

warm_start_fisher_info

Optional initial curvature (information) matrix to warm-start the first iteration.

estimate_only

If TRUE, skip computing mu, XtWX/fisher_information, and score, 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 Poisson regression coefficients \(\hat\beta\).

mu

(omitted if estimate_only = TRUE) The fitted means \(\hat\mu_i\).

XtWX, fisher_information

(omitted if estimate_only = TRUE) Two aliases for the same curvature matrix \(X^\top W X\) (\(W = \mathrm{diag}(\hat\mu_i)\)) at the fitted coefficients — the Fisher information, which for the canonical log link coincides with the observed information.

score

(omitted if estimate_only = TRUE) The score vector \(X^\top(y - \hat\mu)\) at the fitted coefficients.

neg_ll

(omitted if estimate_only = TRUE) The negative log-likelihood at the fitted coefficients.

converged

A logical value indicating whether the final gradient norm was below tol (gradient_norm < tol); uniform across the "irls"/"lbfgs"/"newton_raphson" optimizers.

num_iter

The number of iterations performed.

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.

Fixed parameters, warm starts

fixed_idx and fixed_values optionally hold a subset of coefficients fixed at caller-supplied constant values (their contribution is folded into the linear predictor as an offset) rather than estimated. warm_start_beta supplies starting coefficients directly; otherwise, if smart_cold_start = TRUE, a Poisson-specific heuristic start is used, and if warm_start_fisher_info is also supplied (or, absent that, when smart_cold_start = TRUE), it seeds the curvature estimate used for the very first IRLS step (or first quasi-Newton step, for the non-IRLS algorithms). warm_start_weights is accepted for interface parity with sibling functions but is not consulted anywhere in this function's fitting logic.

See also

fast_poisson_regression_weighted_cpp for the observation-weighted variant; fast_poisson_regression_with_var_cpp for the variance-computing variant; fast_quasipoisson_regression_with_var_cpp for the overdispersion-corrected variant.