% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/negbin.R
\name{negbin}
\alias{negbin}
\title{Negative binomial family with known dispersion}
\usage{
negbin(theta, link = "log")
}
\arguments{
\item{theta}{the (known) dispersion parameter; must be positive.}

\item{link}{character; one of `"log"` (default), `"sqrt"`, or `"identity"`.}
}
\value{
A `family` object with class `"family"` and
  `family$family == "Negative Binomial(theta)"`. The object also carries
  the slot `family$theta`, which `family_code()` and the dispatch layer
  use to detect the native NB fast path.
}
\description{
A built-in negative-binomial family for use with [fastglm()] and
[fastglmPure()] when `theta` (the NB2 dispersion) is known. Equivalent to
`MASS::negative.binomial(theta, link)` but without taking a hard dependency
on the **MASS** package. The variance is `mu + mu^2 / theta`; as
`theta -> Inf` it reduces to Poisson.
}
\details{
For joint estimation of `theta` together with `beta`, use the dedicated
(forthcoming) `fastglm_nb()` entry point. The `negbin()` family here is
intended for use cases where `theta` has been pre-specified or estimated
separately.
}
\examples{
set.seed(1)
n <- 500
x  <- cbind(1, matrix(rnorm(n * 2), n, 2))
mu <- exp(x \%*\% c(0.3, 0.4, -0.2))
y  <- rpois(n, lambda = mu * rgamma(n, shape = 2, rate = 2))   # NB(theta=2)

fit <- fastglm(x, y, family = negbin(theta = 2, link = "log"))
coef(fit)

}
