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.

See also

fast_dnbinom_mu_vec_cpp for the mean/dispersion density parameterization used here; fast_neg_bin_with_var_cpp for the variance-augmented variant.

Examples

X = matrix(rnorm(100), 10, 10)
y = rpois(10, 2)
fast_neg_bin_cpp(X, y)
#> $b
#>  [1]  0.68493798 -0.53773797  1.22978747  0.41917934  0.86204468  0.68942285
#>  [7]  0.32298807  0.02978373  0.70335557 -1.91858106
#> 
#> $theta_hat
#> [1] 98495.82
#> 
#> $logLik
#> [1] -13.22329
#> 
#> $converged
#> [1] TRUE
#> 
#> $num_iter
#> [1] 98
#> 
#> $hit_iteration_cap
#> [1] FALSE
#> 
#> $gradient_norm
#> [1] 0.01021522
#> 
#> $min_eigenvalue_information
#> [1] NaN
#> 
#> $dispersion_at_poisson_boundary
#> [1] FALSE
#> 
#> $fisher_information
#>                [,1]          [,2]          [,3]          [,4]          [,5]
#>  [1,]  2.412359e+01  9.544724e+00 -4.170831e+00  7.515808e-01  4.942490e+00
#>  [2,]  9.544724e+00  2.334970e+01 -1.047863e+01  1.753619e+00 -1.989988e+00
#>  [3,] -4.170831e+00 -1.047863e+01  1.984555e+01  1.513932e+00 -6.419127e+00
#>  [4,]  7.515808e-01  1.753619e+00  1.513932e+00  1.419309e+01 -1.734259e+00
#>  [5,]  4.942490e+00 -1.989988e+00 -6.419127e+00 -1.734259e+00  1.089819e+01
#>  [6,]  1.840738e+00  9.318040e+00 -6.833781e+00 -1.108784e+00 -2.338519e+00
#>  [7,]  5.397291e+00  1.046262e+00 -1.152816e+00 -7.225351e+00  3.398249e+00
#>  [8,] -1.611530e+01 -1.278481e+01  4.473394e+00 -3.093805e+00 -1.131138e+00
#>  [9,] -2.296203e+00  9.028583e+00 -3.996183e+00  4.916618e-01 -4.484827e-01
#> [10,]  1.569081e+01  1.626416e-01 -3.370392e-01  3.134370e+00  1.024153e+01
#> [11,] -2.216430e-07 -1.294724e-07  7.368438e-08  2.926776e-07 -1.772920e-07
#>                [,6]          [,7]          [,8]          [,9]         [,10]
#>  [1,]  1.840738e+00  5.397291e+00 -1.611530e+01 -2.296203e+00  1.569081e+01
#>  [2,]  9.318040e+00  1.046262e+00 -1.278481e+01  9.028583e+00  1.626416e-01
#>  [3,] -6.833781e+00 -1.152816e+00  4.473394e+00 -3.996183e+00 -3.370392e-01
#>  [4,] -1.108784e+00 -7.225351e+00 -3.093805e+00  4.916618e-01  3.134370e+00
#>  [5,] -2.338519e+00  3.398249e+00 -1.131138e+00 -4.484827e-01  1.024153e+01
#>  [6,]  3.607141e+01  9.012093e+00 -1.466975e+00  6.479777e+00  6.087901e+00
#>  [7,]  9.012093e+00  9.282773e+00  4.951410e-01  1.168242e+00  6.624417e+00
#>  [8,] -1.466975e+00  4.951410e-01  3.329068e+01 -4.937248e+00 -1.199335e+01
#>  [9,]  6.479777e+00  1.168242e+00 -4.937248e+00  9.675219e+00 -8.744126e-01
#> [10,]  6.087901e+00  6.624417e+00 -1.199335e+01 -8.744126e-01  2.373752e+01
#> [11,] -3.488955e-08 -1.860319e-07  1.963356e-07  2.420296e-07 -2.362990e-07
#>               [,11]
#>  [1,] -2.216430e-07
#>  [2,] -1.294724e-07
#>  [3,]  7.368438e-08
#>  [4,]  2.926776e-07
#>  [5,] -1.772920e-07
#>  [6,] -3.488955e-08
#>  [7,] -1.860319e-07
#>  [8,]  1.963356e-07
#>  [9,]  2.420296e-07
#> [10,] -2.362990e-07
#> [11,]  1.268994e-04
#>