Repository navigation
Expand file tree
/
Copy pathnbinom2.Rd
More file actions
140 lines (119 loc) · 10.6 KB
/
Copy pathnbinom2.Rd
File metadata and controls
140 lines (119 loc) · 10.6 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/family.R
\name{nbinom2}
\alias{nbinom2}
\alias{family_glmmTMB}
\alias{nbinom1}
\alias{nbinom12}
\alias{compois}
\alias{truncated_compois}
\alias{genpois}
\alias{truncated_genpois}
\alias{truncated_poisson}
\alias{truncated_nbinom2}
\alias{truncated_nbinom1}
\alias{beta_family}
\alias{betabinomial}
\alias{combinomial}
\alias{tweedie}
\alias{skewnormal}
\alias{lognormal}
\alias{ziGamma}
\alias{t_family}
\alias{ordbeta}
\alias{ordinal}
\alias{bell}
\title{Family functions for glmmTMB}
\usage{
nbinom2(link = "log")
nbinom1(link = "log")
nbinom12(link = "log")
compois(link = "log")
truncated_compois(link = "log")
genpois(link = "log")
truncated_genpois(link = "log")
truncated_poisson(link = "log")
truncated_nbinom2(link = "log")
truncated_nbinom1(link = "log")
beta_family(link = "logit")
betabinomial(link = "logit")
combinomial(link = "logit", allow_negative_nu = FALSE)
tweedie(link = "log")
skewnormal(link = "identity")
lognormal(link = "log")
ziGamma(link = "inverse")
t_family(link = "identity")
ordbeta(link = "logit")
ordinal(link = "logit")
bell(link = "log")
}
\arguments{
\item{link}{(character) link function for the conditional mean ("log", "logit", "probit", "inverse", "cloglog", "identity", or "sqrt")}
\item{allow_negative_nu}{(\code{combinomial} only) if \code{TRUE}, use an
identity link (rather than the default log link) for the dispersion
model, allowing the dispersion parameter \eqn{\nu}{nu} to go negative
(super-dispersion, i.e. over-dispersion beyond \eqn{\nu \to 0}{nu -> 0})}
}
\value{
returns a list with (at least) components
\item{family}{length-1 character vector giving the family name}
\item{link}{length-1 character vector specifying the link function}
\item{variance}{a function of either 1 (mean) or 2 (mean and dispersion
parameter) arguments giving a value proportional to the
predicted variance (scaled by \code{sigma(.)})
}
}
\description{
Family functions for glmmTMB
}
\details{
If specified, the dispersion model uses a log link; additional family parameters
(Student-t df, Tweedie power parameters, ordered beta cutpoints,
skew-normal skew parameters, etc.) use various link functions and
are accessible via \code{\link{family_params}}.
Denoting the variance as \eqn{V}, the dispersion parameter
as \eqn{\phi=\exp(\eta)}{phi=exp(eta)} (where \eqn{\eta}{eta} is the linear predictor from the dispersion model),
and the predicted mean as \eqn{\mu}{mu}:
\describe{
\item{gaussian}{(from base R): constant \eqn{V=\phi^2}{V=phi^2}}
\item{Gamma}{(from base R) phi is the shape parameter. \eqn{V=\mu\phi}{V=mu*phi}}
\item{ziGamma}{a modified version of \code{Gamma} that skips checks for zero values, allowing it to be used to fit hurdle-Gamma models}
\item{nbinom2}{Negative binomial distribution: quadratic parameterization (Hardin & Hilbe 2007). \eqn{V=\mu(1+\mu/\phi) = \mu+\mu^2/\phi}{V=mu*(1+mu/phi) = mu+mu^2/phi}.}
\item{nbinom1}{Negative binomial distribution: linear parameterization (Hardin & Hilbe 2007). \eqn{V=\mu(1+\phi)}{V=mu*(1+phi)}. \emph{Note} that the \eqn{phi} parameter has opposite meanings in the \code{nbinom1} and \code{nbinom2} families. In \code{nbinom1} overdispersion increases with increasing \code{phi} (the Poisson limit is \code{phi=0}); in \code{nbinom2} overdispersion decreases with increasing \code{phi} (the Poisson limit is reached as \code{phi} goes to infinity).}
\item{nbinom12}{Negative binomial distribution: mixed linear/quadratic, as in the \code{DESeq2} package or as described by Lindén and Mäntyniemi (2011). \eqn{V=\mu(1+\phi+\mu/\psi)}{V=mu*(1+phi+mu/\psi)}. (In Lindén and Mäntyniemi's parameterization, \eqn{\omega = \phi}{omega=phi} and \eqn{\theta=1/\psi}{theta=1/\psi}.) If a dispersion model is specified, it applies only to the linear (\code{phi}) term.}
\item{truncated_nbinom2}{Zero-truncated version of nbinom2: variance expression from Shonkwiler 2016. Simulation code (for this and the other truncated count distributions) is taken from C. Geyer's functions in the \code{aster} package; the algorithms are described in \href{https://cran.r-project.org/package=aster/vignettes/trunc.pdf}{this vignette}.}
\item{compois}{Conway-Maxwell Poisson distribution: parameterized with the exact mean (Huang 2017), which differs from the parameterization used in the \pkg{COMPoissonReg} package (Sellers & Shmueli 2010, Sellers & Lotze 2015). \eqn{V=\mu\phi}{V=mu*phi}.}
\item{genpois}{Generalized Poisson distribution (Consul & Famoye 1992). \eqn{V=\mu\exp(\eta)}{V=mu*exp(eta)}. (Note that Consul & Famoye (1992) define \eqn{\phi}{phi} differently.) Our implementation is taken from the \code{HMMpa} package, based on Joe and Zhu (2005) and implemented by Vitali Witowski.}
\item{beta}{Beta distribution: parameterization of Ferrari and Cribari-Neto (2004)
and the \pkg{betareg} package (Cribari-Neto and Zeileis 2010); \eqn{V=\mu(1-\mu)/(\phi+1)}{V=mu*(1-mu)/(phi+1)}}
\item{betabinomial}{Beta-binomial distribution: parameterized according to Morris (1997). \eqn{V=\mu(1-\mu)(n(\phi+n)/(\phi+1))}{V=mu*(1-mu)*(n*(phi+n)/(phi+1))}}
\item{combinomial}{Conway-Maxwell-Binomial distribution: mean-parameterized as in Huang (2017) but for the binomial. The dispersion parameter \eqn{\nu}{nu} controls under- (\eqn{\nu>1}) and over- (\eqn{\nu<1}) dispersion relative to the binomial; \eqn{\nu=1} recovers the binomial. \eqn{V} has no closed form and is computed numerically.}
\item{tweedie}{Tweedie distribution: \eqn{V=\phi\mu^{power}}{V=phi*mu^power}. The power parameter is restricted to the interval \eqn{1<power<2}, i.e. the compound Poisson-gamma distribution. Code taken from the \code{tweedie} package, written by Peter Dunn. The power parameter (designated \code{psi} in the list of parameters) uses the link function \code{qlogis(psi-1.0)}; thus one can fix the power parameter to a specified value using \code{start = list(psi = qlogis(fixed_power-1.0)), map = list(psi = factor(NA))}.}
\item{t_family}{Student-t distribution with adjustable scale and location parameters (also called a \href{https://en.wikipedia.org/wiki/Pearson_distribution#The_Pearson_type_VII_distribution}{Pearson type VII distribution}). The shape (degrees of freedom parameter) is fitted with a log link; it may be often be useful to fix the shape parameter using \code{start = list(psi = log(fixed_df)), map = list(psi = factor(NA))}.}
\item{ordbeta}{Ordered beta regression from Kubinec (2022); fits continuous (e.g. proportion) data in the \emph{closed} interval [0,1]. Unlike the implementation in the \code{ordbeta} package, this family will not automatically scale the data. If your response variable is defined on the closed interval [a,b], transform it to [0,1] via \code{y_scaled <- (y-a)/(b-a)}.}
\item{lognormal}{Log-normal, parameterized by the mean and standard deviation \emph{on the data scale}}
\item{skewnormal}{Skew-normal, parameterized by the mean, standard deviation, and shape (Azzalini & Capitanio, 2014); constant \eqn{V=\phi^2}{V=phi^2}}
\item{bell}{Bell distribution (see Castellares et al 2018).
}
\item{ordinal}{Cumulative-link (proportional odds) model for an ordinal response (Agresti 2010; e.g. \code{MASS::polr}, \code{ordinal::clm}). The response should be an ordered factor (or 1-based integer category codes). The K-1 ordered thresholds (cutpoints) are stored internally in the \code{psi} parameter vector via a softmax parameterization (cf. Koslik et al 2025): \code{psi} contains the log-weights of the K baseline (linear predictor = 0) category probabilities relative to the last category, and \code{theta = qlogis(cumsum(softmax(c(psi, 0))))}, which is increasing by construction; use \code{family_params()} to extract the thresholds on the threshold scale. As in other cumulative-link software, the linear predictor enters the model as \eqn{\theta_j - \eta}{theta_j - eta} (so positive coefficients shift the response toward higher categories) and the fixed-effect intercept is fixed to zero (absorbed into the thresholds). Fitted/predicted mean values are reported as the expected category index \eqn{E[Y] = \sum_j j P(Y=j)}{E[Y] = sum_j j P(Y=j)}. \code{REML=TRUE} integrates out the fixed effects but not the thresholds, so the appropriate REML correction for this family is unsettled; it is allowed but warns.}
}
}
\references{
\itemize{
\item Agresti A (2010). "Analysis of Ordinal Categorical Data." 2nd ed. Hoboken, NJ: Wiley.
\item Koslik J-O, Dupont F, Auger-Méthé M, Marcoux M, Hussey N, & Heckman N (2025). "Flexible Unimodal Density Estimation in Hidden Markov Models." arXiv:2511.17071. \doi{10.48550/arXiv.2511.17071}
\item Azzalini A & Capitanio A (2014). "The skew-normal and related families." Cambridge: Cambridge University Press.
\item Castellares F, Ferrari SLP, & Lemonte AJ (2018) "On the Bell Distribution and Its Associated Regression Model for Count Data" Applied Mathematical Modelling 56: 172–85. \doi{10.1016/j.apm.2017.12.014}
\item Consul PC & Famoye F (1992). "Generalized Poisson regression model." Communications in Statistics: Theory and Methods 21:89–109.
\item Ferrari SLP, Cribari-Neto F (2004). "Beta Regression for Modelling Rates and Proportions." \emph{J. Appl. Stat.} 31(7), 799-815.
\item Hardin JW & Hilbe JM (2007). "Generalized linear models and extensions." Stata Press.
\item Huang A (2017). "Mean-parametrized Conway–Maxwell–Poisson regression models for dispersed counts." \emph{Statistical Modelling} 17(6), 1-22.
\item Joe H & Zhu R (2005). "Generalized Poisson Distribution: The Property of Mixture of Poisson and Comparison with Negative Binomial Distribution." \emph{Biometrical Journal} 47(2): 219–29. \doi{10.1002/bimj.200410102}.
\item Lindén, A & Mäntyniemi S. (2011). "Using the Negative Binomial Distribution to Model Overdispersion in Ecological Count Data." \emph{Ecology} 92 (7): 1414–21. \doi{10.1890/10-1831.1}.
\item Morris W (1997). "Disentangling Effects of Induced Plant Defenses and Food Quantity on Herbivores by Fitting Nonlinear Models." \emph{American Naturalist} 150:299-327.
\item Kubinec R (2022). "Ordered Beta Regression: A Parsimonious, Well-Fitting Model for Continuous Data with Lower and Upper Bounds." \emph{Political Analysis}. doi:10.1017/pan.2022.20.
\item Sellers K & Lotze T (2015). "COMPoissonReg: Conway-Maxwell Poisson (COM-Poisson) Regression". R package version 0.3.5. https://CRAN.R-project.org/package=COMPoissonReg
\item Sellers K & Shmueli G (2010) "A Flexible Regression Model for Count Data." \emph{Annals of Applied Statistics} 4(2), 943–61. \doi{10.1214/09-AOAS306}.
\item Shonkwiler, J. S. (2016). "Variance of the truncated negative binomial distribution." \emph{Journal of Econometrics} 195(2), 209–210. \doi{10.1016/j.jeconom.2016.09.002}.
}
}