nbinom2: Negative-binomial NB2 family with a log link

View source: R/FUN_glmm_families.R

nbinom2R Documentation

Negative-binomial NB2 family with a log link

Description

Creates a sommer-native negative-binomial family with variance \mu+\mu^2/\theta. It can be used in native Laplace fits without another package providing the family or fitting engine.

Usage

nbinom2(theta = 1, link = "log")

Arguments

theta

Positive starting shape. Larger values approach a Poisson distribution.

link

Currently "log" only.

Details

For mmes() with method$integration="laplace", shape is estimated jointly with fixed effects and free random covariance coordinates by default. Use familyParameters=list(theta=2, estimate=FALSE) to fix shape. For familym(), nest this configuration under the trait's name. The constructor's theta is the default starting value; an explicitly supplied control value overrides it. Counts must be non-negative integers.

The full likelihood includes the negative-binomial normalization constants. Native derivatives include shape dependence of both the conditional mode and Laplace determinant correction. The fitted shape and approximate uncertainty are available as theta.nb, theta.nb.se, and familyParameters for a single-family fit. Uncertainty requires a converged, interior fit with valid joint curvature. Shape near the Poisson limit can be weakly identified; numerical boundary/curvature warnings are not calibrated hypothesis tests.

This family also supplies the ordinary R family methods needed by PQL, where shape is fixed unless the separate PQL shape-estimation control is enabled. PQL is not changed into a marginal-likelihood estimator by choosing this family.

Value

An object of class "family".

See Also

mmes, familym, mmes_control

Examples

family <- nbinom2(theta=2)
family$variance(c(1, 2, 3))
method <- mmes_method(objective="ml", integration="laplace")
# Pass familyParameters=list(theta=2, estimate=FALSE) to mmes().

sommer documentation built on Nov. 14, 2026, 5:07 p.m.