Build a family by name, with a link for any of its parameters

brmsfamily() is brms's generic family constructor. It names the family with a string, takes the link for the mean as the second argument, and takes a link_<dpar> argument for each of the family's other distributional parameters.

Usage

brmsfamily(family, link = NULL, ...)

Arguments

family: Family name, as a single string.
link: The link for the mean, quoted or not. NULL gives the family's default. See frmtmb-links for the set each family takes.
...: Any link_<dpar> argument the named family takes, and its other constructor arguments. Every one has to be named.

Value

A frmtmb_family object, ready for frm().

Details

The family constructors take the same arguments, so student(link_sigma = "softplus") does not need it. They exist for the families frmtmb has no constructor of its own for. gaussian(), poisson(), binomial() and Gamma() come from 'stats', which knows nothing of a link_sigma and refuses several links brms allows for the mean. frmtmb does NOT shadow them: a gaussian() that answered a frmtmb_family would break every glm() call in an attached session.

The name follows brms's spelling rules: case does not matter, "normal" is "gaussian", "com_poisson" is "compois", and the prefixes "zi_" and "hu_" stand for "zero_inflated_" and "hurdle_". The link may be unquoted, as in brmsfamily("gaussian", inverse).

The family and its link as one character vector, c("weibull", "log"), is the form brms accepts for family = in a model call, and frm() accepts it there. brmsfamily() refuses it, as brms does.

Differences from brms

An argument the family does not have is refused by name. brms ignores it, so brmsfamily("poisson", link_sigma = "log") builds a poisson family there. threshold is an argument of the ordinal families alone, and refcat of "categorical", "multinomial", "dirichlet" and "logistic_normal".

brmsfamily("com_poisson") gives compois(), whose mu is the MEAN of the count. brms 2.23.0 does not use the mean. Its Stan program fits mu as the rate lambda of the Conway-Maxwell-Poisson density, which is proportional to lambda^y / (y!)^nu, and its log_lik() and posterior_predict() read mu as lambda^(1 / nu). So the coefficients of a brms com_poisson() fit and of an frmtmb fit are on different scales. They agree only at nu = 1 (brms's shape), where all three are the Poisson mean.

Examples

# sigma on a softplus: gaussian() from 'stats' has no link_sigma
brmsfamily("gaussian", link_sigma = "softplus")
#> 
#> Family: gaussian 
#> Link function: identity 
#> Parameters: mu (identity), sigma (softplus)
#> 

# a mean link stats::poisson() refuses, and brms's short names
brmsfamily("poisson", softplus)$link
#> [1] "softplus"
brmsfamily("zi_poisson")$link_zi
#> [1] "logit"

set.seed(2)
d <- data.frame(x = rnorm(60))
d$y <- rnorm(60, 1 + d$x, exp(0.3 * d$x))
frm(bf(y ~ x, sigma ~ x),
    family = brmsfamily("gaussian", link_sigma = "softplus"), data = d)
#>  Family: gaussian 
#>  Links: mu = identity; sigma = softplus
#> 
#> Formula: y ~ x 
#>    Data: d (Number of observations: 60) 
#>  Method: ML   logLik: -92.517   AIC: 193.034   BIC: 201.411 
#> 
#> Regression Coefficients:
#>                 Estimate Est.Error l-95% CI u-95% CI z value Pr(>|z|)
#> Intercept           0.94      0.15     0.64     1.25    6.15  7.8e-10
#> sigma_Intercept     0.74      0.16     0.43     1.04    4.73  2.2e-06
#> x                   0.93      0.12     0.70     1.16    7.77  8.0e-15
#> sigma_x             0.48      0.13     0.22     0.74    3.56  0.00037