Fast Negative Binomial Regression, Estimate Only (C++ Backend)

Fits the negative-binomial regression model in its mean/dispersion parameterization documented in full at fast_dnbinom_mu_vec_cpp: log link \(\log \mu_i = x_i^\top \beta\) (so \(e^{\beta_j}\) is a multiplicative change in the mean count, as in Poisson regression), with a single dispersion parameter \(\theta\) shared across all observations and \(\mathrm{Var}(Y_i) = \mu_i + \mu_i^2/\theta\) (smaller \(\theta\) means more overdispersion relative to Poisson; \(\theta \to \infty\) recovers Poisson). The optimizer's parameter vector is c(beta, log(theta)) (\(\theta\) optimized on the log scale for positivity).

High-performance negative binomial regression fitting.

Usage

fast_neg_bin_cpp(
  X,
  y,
  warm_start_params = NULL,
  smart_cold_start = FALSE,
  maxit = 1000L,
  eps_f = 1e-08,
  eps_g = 1e-06,
  fixed_idx = NULL,
  fixed_values = NULL,
  optimization_alg = "lbfgs",
  warm_start_fisher_info = NULL,
  estimate_only = FALSE
)

Arguments

X: A numeric matrix of predictors.
y: A numeric vector of responses.
warm_start_params: Optional starting values for coefficients and dispersion. If provided, smart_cold_start is ignored.
smart_cold_start: Logical. If TRUE, use an initial OLS-based guess when starting from scratch (a "cold start") with no prior knowledge. This is ignored if a warm start is provided.
maxit: Maximum number of iterations.
eps_f: Convergence tolerance for function value.
eps_g: Convergence tolerance for gradient.
fixed_idx: Optional indices of fixed parameters.
fixed_values: Optional values for fixed parameters.
optimization_alg: Optimization algorithm.
warm_start_fisher_info: Optional initial Fisher Information matrix for the first IRLS iteration.
estimate_only: Logical; if TRUE, may skip work not needed to produce point estimates (kept in sync with the package's other fast_* estimate-vs-inference split).

Value

A list containing the following components:

b: A numeric vector of the estimated negative binomial regression coefficients \(\hat\beta\).
theta_hat: The estimated dispersion parameter \(\hat\theta\) (natural scale).
logLik: The model's log-likelihood at the fitted parameters.
converged: A logical value indicating whether the final gradient norm was below the convergence tolerance (gradient_norm < tol); uniform across the "lbfgs"/"newton_raphson" optimizers.
num_iter: The number of optimizer 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 gradient at the returned parameters.
fisher_information: The working-weights curvature matrix used during fitting.

A list containing coefficients, theta, and convergence status.

Examples

X = matrix(rnorm(100), 10, 10)
y = rpois(10, 2)
fast_neg_bin_cpp(X, y)
#> $b
#>  [1]  -0.8267280  -2.1763596  -3.7221791   0.9514910  -3.7719738 -12.7913825
#>  [7]   0.1291975  -7.6429227   9.2618324  -6.1942061
#> 
#> $theta_hat
#> [1] 9286312831
#> 
#> $logLik
#> [1] NaN
#> 
#> $converged
#> [1] FALSE
#> 
#> $num_iter
#> [1] 1000
#> 
#> $hit_iteration_cap
#> [1] FALSE
#> 
#> $gradient_norm
#> [1] NaN
#> 
#> $min_eigenvalue_information
#> [1] NaN
#> 
#> $dispersion_at_poisson_boundary
#> [1] FALSE
#> 
#> $fisher_information
#>                [,1]          [,2]          [,3]          [,4]          [,5]
#>  [1,]  1.197096e+01  2.010164e+00 -4.094870e+00  2.209775e+00 -5.429091e-01
#>  [2,]  2.010164e+00  1.078014e+01  4.964431e+00  1.764905e-01 -1.444337e-01
#>  [3,] -4.094870e+00  4.964431e+00  1.991684e+01  6.163605e+00  3.289494e+00
#>  [4,]  2.209775e+00  1.764905e-01  6.163605e+00  2.041785e+01  3.243445e+00
#>  [5,] -5.429091e-01 -1.444337e-01  3.289494e+00  3.243445e+00  9.071717e+00
#>  [6,]  9.104917e-01  3.537191e+00 -4.768129e+00 -6.888085e+00 -3.329885e-01
#>  [7,]  2.406905e+00 -4.745558e+00 -6.322695e-01  8.558041e+00  5.635277e-01
#>  [8,]  6.152553e+00  8.896628e-01 -2.188671e+00  6.846197e+00 -1.797017e+00
#>  [9,]  3.260404e+00  4.476363e+00 -5.828514e+00 -4.014003e+00 -9.653195e-01
#> [10,] -3.501995e+00 -8.794750e+00 -8.701734e+00 -1.143893e+00 -4.649212e+00
#> [11,] -4.729230e-13 -1.384487e-13 -4.649295e-13 -2.761879e-12  1.103789e-13
#>                [,6]          [,7]          [,8]          [,9]         [,10]
#>  [1,]  9.104917e-01  2.406905e+00  6.152553e+00  3.260404e+00 -3.501995e+00
#>  [2,]  3.537191e+00 -4.745558e+00  8.896628e-01  4.476363e+00 -8.794750e+00
#>  [3,] -4.768129e+00 -6.322695e-01 -2.188671e+00 -5.828514e+00 -8.701734e+00
#>  [4,] -6.888085e+00  8.558041e+00  6.846197e+00 -4.014003e+00 -1.143893e+00
#>  [5,] -3.329885e-01  5.635277e-01 -1.797017e+00 -9.653195e-01 -4.649212e+00
#>  [6,]  1.241082e+01 -9.574151e+00  1.016188e+00  9.377450e+00 -1.354795e+01
#>  [7,] -9.574151e+00  3.061952e+01  2.054716e+01  8.903829e+00  9.565191e+00
#>  [8,]  1.016188e+00  2.054716e+01  2.544770e+01  1.992206e+01 -3.243816e+00
#>  [9,]  9.377450e+00  8.903829e+00  1.992206e+01  2.552553e+01 -7.509205e+00
#> [10,] -1.354795e+01  9.565191e+00 -3.243816e+00 -7.509205e+00  3.189715e+01
#> [11,]  2.402313e-12 -3.346815e-12 -2.619202e-13  2.592449e-12 -1.264418e-12
#>               [,11]
#>  [1,] -4.729230e-13
#>  [2,] -1.384487e-13
#>  [3,] -4.649295e-13
#>  [4,] -2.761879e-12
#>  [5,]  1.103789e-13
#>  [6,]  2.402313e-12
#>  [7,] -3.346815e-12
#>  [8,] -2.619202e-13
#>  [9,]  2.592449e-12
#> [10,] -1.264418e-12
#> [11,] -2.949564e-05
#>

Usage

Arguments

Value

See also

Examples