negbin1: Alternative negative-binomial family
In spaMM: Mixed-Effect Models, with or without Spatial Random Effects

negbin1

R Documentation

Alternative negative-binomial family

Description

Returns a family object suitable as a fitme argument for fitting negative-binomial models with variance linearly (affinely) related to the mean \mu: variance=\mu+\mu/shape. This distribution can be represented as a Poisson-Gamma mixture, where the conditional Poisson mean is \mu times a Gamma random variable with mean 1 and variance 1/(shape*\mu) as produced by rgamma(., shape=sh,scale=1/sh) where sh=shape*\mu, meaning that the family shape parameter controls, but differs from, the gamma shape parameter.

The family described by this object is not a GLM family, so it should not be used as a glm argument unless one additionally uses method="llm.fit" (see Examples). But it is still characterized by the same concepts as GLMs: a linear predictor, a link function, and the given distribution of residual variation.

The zero-truncated variant of this family is also handled, and is never suitable as argument for glm.

A fixed-effect residual-dispersion model can be fitted, using the resid.model argument, which is used to specify the form of the logarithm of the shape parameter. Thus the variance of the response become \mu+\mu/exp(<specified linear expression>).

Usage

negbin1(shape, link = "log", trunc = -1L)

Arguments

`shape`	Shape parameter. The “outer-optimizing” functions, such as `fitme` (see `inner-vs-outer`) will estimate this parameter if called with `family=negbin1()` (no given `shape` value). In other usages of this family, `shape` must be specified.
`link`	log, sqrt or identity link, specified by any of the available ways for GLM links (name, character string, one-element character vector, or object of class `link-glm` as returned by `make.link`).
`trunc`	Either `0L` for zero-truncated distribution, or `-1L` for default untruncated distribution.

Details

The name NB_shape should be used to set values of shape in optimization control arguments of the fitting functions (e.g., fitme(.,init=list(NB_shape=1))); but fixed values are set by the shape argument.

Value

A list, formally of class c("LLF", "family"). See LL-family for details about the structure and usage of such objects.

Examples

data(scotlip)
## Shape estimated:
fitme(I(1+cases)~I(prop.ag/10)+offset(log(expec)),family=negbin1(), data=scotlip)

## Shape fixed:
fitme(I(1+cases)~I(prop.ag/10)+offset(log(expec)),family=negbin1(1), data=scotlip)

# => consistent with:
glm(I(1+cases)~I(prop.ag/10)+offset(log(expec)),family=negbin1(1), 
    data=scotlip, method="llm.fit")

# !! but not with !!
# glm(I(1+cases)~I(prop.ag/10)+offset(log(expec)),family=negbin1(1), 
#     data=scotlip) # WRONG !!

spaMM documentation built on Sept. 10, 2026, 1:07 a.m.