Skip to contents

Returns 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":

bf(y1 | vint(y2) ~ 1,
   nlf(shapexone ~ shapexx),
   nlf(shapextwo ~ shapexx),
   shapexx ~ 1, lambdaone ~ 1, lambdatwo ~ 1, shapes ~ 1)

See also

binegbin_partialobs() for partially observed pairs; bipois() for the equidispersed Poisson counterpart; vignette("prediction") for the prediction functions.