Joint bivariate custom family with negative-binomial components for brms
Source:R/binegbin.R
binegbin.RdReturns a brms custom family for the joint distribution of a pair of
counts (y1, y2), constructed by trivariate reduction with
negative-binomial components: y1 = N_s + N1 and y2 = N_s + N2, where
N_s ~ NB2(mu, shapes), N1 ~ NB2(lambdaone, shapexone), and
N2 ~ NB2(lambdatwo, shapextwo) are mutually independent given their
rates. NB2(m, phi) has mean m and variance m + m^2/phi
(neg_binomial_2 in Stan, dnbinom(size = phi, mu = m) in R). shapes is
the dispersion of the shared component, and shapexone and shapextwo are
the dispersions of the two exclusive components. All six dpars have a log
link.
Use binegbin() when both counts were recorded on every row. brms drops
any row with a missing value of y1 or y2. If only one source has
missing counts, make that source y1 and use binegbin_partialobs(),
which keeps every row in the model.
y1 is the response. y2 is passed as supplementary integer data through
the brms vint() addition term:
brm(
bf(y1 | vint(y2) ~ 1,
lambdaone ~ 1, lambdatwo ~ 1,
shapes ~ 1, shapexone ~ 1, shapextwo ~ 1),
family = binegbin(),
stanvars = binegbin_stanvars(),
data = dat
)This template is for the native parameterisation. To fit the model in the
congruence–bias parameterisation, which we recommend, write the formula
with bf_mfd().
Usage
binegbin()
binegbin_stanvars()
log_lik_binegbin(i, prep)
posterior_predict_binegbin(i, prep, ...)
posterior_epred_binegbin(prep)Value
binegbin() returns a brms custom_family object. binegbin_stanvars()
returns a stanvars object holding the Stan code for the corresponding
_lpmf. log_lik_binegbin() returns a numeric vector of log-densities,
one per posterior draw, for observation i.
posterior_predict_binegbin() returns an integer vector of draws of y1
from its marginal distribution, one per posterior draw, for observation
i. posterior_epred_binegbin() returns a numeric matrix of
mu + lambdaone, with posterior draws in rows and observations in
columns.
Details
The correlation between the two counts cannot be negative, because it is generated by the shared component, which is part of both counts.
brms requires every custom family to have a dpar named mu. In
binegbin(), mu is the rate of the shared component, not the mean of
either count. brms also rejects dpar names that end in a digit, so the
exclusive rates are lambdaone and lambdatwo, written
\(\lambda_1\) and \(\lambda_2\) in the
documentation.
Because every dpar has a log link, a non-linear formula for a dpar is
written on the log scale, without exp(): nlf(lambdaone ~ lamx) gives
lambdaone = exp(lamx).
shapexone and shapextwo are estimated separately. To constrain them to
be equal in the congruence–bias parameterisation, give bf_mfd() the
single formula kappax ~ 1 in place of kappaxone ~ 1 and
kappaxtwo ~ 1:
bf_mfd(
y1 | vint(y2),
logM ~ 1,
logitf ~ 1,
delta ~ 1,
kappas ~ 1,
kappax ~ 1
)In the native parameterisation, route both dispersions through one
non-linear parameter, and set the prior on shapexx with
nlpar = "shapexx":
See also
binegbin_partialobs() for partially observed pairs; bipois()
for the equidispersed Poisson counterpart; vignette("prediction") for
the prediction functions.