Builds the brms non-linear formula for the congruence–bias parameterisation,
in which the native parameters of a bipois() or binegbin() model are
functions of the congruence–bias coordinates: the midpoint M of the two
expected counts, the congruence f, the source bias (through delta, its
inverse hyperbolic tangent), and, for binegbin, the overdispersions
kappa. Each coordinate then takes its own linear predictor. A predictor
such as site in the formula for logM alone multiplies all three rates by a
common factor, so the congruence and the source bias are the same at every
site. In the native parameterisation, the same model needs the predictor in
all three rates, with the coefficients constrained to be equal.
Arguments
- formula
The response part of the model, written without
~:y1 | vint(y2)forbipois()andbinegbin(), andy1 | vint(y2, y1_obs)forbipois_partialobs()andbinegbin_partialobs(). The response is passed to the brms formula unchanged.- ...
Two-sided formulae, one for each coordinate, in any order. The left-hand side names the coordinate and the right-hand side gives its linear predictor, as in
logM ~ 0 + siteordelta ~ 1. Every coordinate of the chosen set is required, including those with an intercept only.
Value
A brmsformula object, as returned by brms::bf().
Details
The coordinates are related to the native parameters by
$$\mu = M f, \quad \lambda_1 = M (1 - f)(1 + \beta), \quad \lambda_2 = M (1 - f)(1 - \beta), \quad \beta = \tanh \delta,$$
where \(\mu\) is mu, the rate of the shared component, and
\(\lambda_1\) and \(\lambda_2\) are lambdaone and lambdatwo, the
rates of the source-exclusive components. Each NB2 (inverse) dispersion
parameter \(\phi\) is \(1/\kappa^2\), where \(\kappa\) is the
corresponding overdispersion. The non-linear parameters are logM
(\(\log M\)), logitf (\(\operatorname{logit} f\)), delta
(\(\delta\)), and the overdispersions. logM, logitf, and delta are
unbounded, so their linear predictors need no link. The overdispersions
must be positive (see Priors). mfd_to_dpars()
computes the native parameters from the same identities.
Sets of coordinates. The set of coordinate formulae supplied determines
the dispersion structure. logM, logitf, and delta are always
required. The three valid sets are:
logM,logitf,delta,kappas,kappaxone, andkappaxtwo: a separate overdispersion for the shared component and for each exclusive component, forbinegbin()andbinegbin_partialobs().logM,logitf,delta,kappas, andkappax: one overdispersion,kappax, for both exclusive components, so thatshapexoneequalsshapextwo, forbinegbin()andbinegbin_partialobs().logM,logitf, anddelta: no overdispersion, forbipois()andbipois_partialobs().
Any other set stops with an error. The family passed to brms::brm() must
match the set: a set with overdispersions written for a bipois model
declares dpars that the family does not have.
The generated formula. For the second set with a site effect on logM,
returns the same formula as
bf(y1 | vint(y2) ~ 1, nl = TRUE) +
nlf(mu ~ logM + log_inv_logit(logitf)) +
nlf(lambdaone ~ log(2) + logM + log1m_inv_logit(logitf) + log_inv_logit(2 * delta)) +
nlf(lambdatwo ~ log(2) + logM + log1m_inv_logit(logitf) + log_inv_logit(-2 * delta)) +
nlf(shapes ~ -2 * log(kappas)) +
nlf(shapexone ~ -2 * log(kappax)) +
nlf(shapextwo ~ -2 * log(kappax)) +
lf(logM ~ 0 + site, logitf ~ 1, delta ~ 1, kappas ~ 1, kappax ~ 1)The first set replaces the two kappax lines with
shapexone ~ -2 * log(kappaxone) and shapextwo ~ -2 * log(kappaxtwo);
the third set omits all three dispersion lines.
Priors. Every coordinate is a non-linear parameter, to which brms gives
a flat, improper prior unless one is set. We recommend a prior on each,
written with class = "b" and nlpar set to the name of the coordinate.
The expression \(-2 \log \kappa\) is undefined for
\(\kappa \le 0\), so a prior on an overdispersion with an intercept-only
formula needs lb = 0, as in
prior(normal(0, 1), class = "b", nlpar = "kappas", lb = 0). The worked
example in vignette("bicountbrms") gives priors
for every coordinate.
bf_mfd() adds no family, Stan function, or post-processing method. The
fitted model is a bipois or binegbin fit whose native parameters are
non-linear functions of the coordinates, and posterior_epred(),
posterior_predict(), and log_lik() dispatch to the family methods as for
any other fit.
Examples
# A site effect on the midpoint alone, with one overdispersion for both
# exclusive components
bf_mfd(
y1 | vint(y2),
logM ~ 0 + site,
logitf ~ 1,
delta ~ 1,
kappas ~ 1,
kappax ~ 1
)
#> y1 | vint(y2) ~ 1
#> mu ~ logM + log_inv_logit(logitf)
#> lambdaone ~ log(2) + logM + log1m_inv_logit(logitf) + log_inv_logit(2 * delta)
#> lambdatwo ~ log(2) + logM + log1m_inv_logit(logitf) + log_inv_logit(-2 * delta)
#> shapes ~ -2 * log(kappas)
#> shapexone ~ -2 * log(kappax)
#> shapextwo ~ -2 * log(kappax)
#> logM ~ 0 + site
#> logitf ~ 1
#> delta ~ 1
#> kappas ~ 1
#> kappax ~ 1
# A partially paired design with Poisson components
bf_mfd(
y1 | vint(y2, y1_obs),
logM ~ 0 + site,
logitf ~ 1,
delta ~ 1
)
#> y1 | vint(y2, y1_obs) ~ 1
#> mu ~ logM + log_inv_logit(logitf)
#> lambdaone ~ log(2) + logM + log1m_inv_logit(logitf) + log_inv_logit(2 * delta)
#> lambdatwo ~ log(2) + logM + log1m_inv_logit(logitf) + log_inv_logit(-2 * delta)
#> logM ~ 0 + site
#> logitf ~ 1
#> delta ~ 1