R: Special Family Functions for 'brms' Models

brmsfamily {brms} | R Documentation

## Special Family Functions for brms Models

### Description

Family objects provide a convenient way to specify the details of the models used by many model fitting functions. The family functions presented here are for use with brms only and will **not** work with other model fitting functions such as `glm` or `glmer`. However, the standard family functions as described in `family` will work with brms. You can also specify custom families for use in brms with the `custom_family` function.

### Usage

    brmsfamily(family, link = NULL, link_sigma = "log",
      link_shape = "log", link_nu = "logm1", link_phi = "log",
      link_kappa = "log", link_beta = "log", link_zi = "logit",
      link_hu = "logit", link_zoi = "logit", link_coi = "logit",
      link_disc = "log", link_bs = "log", link_ndt = "log",
      link_bias = "logit", link_xi = "log1p", link_alpha = "identity",
      link_quantile = "logit", threshold = c("flexible", "equidistant"))

    student(link = "identity", link_sigma = "log", link_nu = "logm1")

    bernoulli(link = "logit")

    negbinomial(link = "log", link_shape = "log")

    geometric(link = "log")

    lognormal(link = "identity", link_sigma = "log")

    shifted_lognormal(link = "identity", link_sigma = "log",
      link_ndt = "log")

    skew_normal(link = "identity", link_sigma = "log",
      link_alpha = "identity")

    exponential(link = "log")

    weibull(link = "log", link_shape = "log")

    frechet(link = "log", link_nu = "logm1")

    gen_extreme_value(link = "identity", link_sigma = "log",
      link_xi = "log1p")

    exgaussian(link = "identity", link_sigma = "log", link_beta = "log")

    wiener(link = "identity", link_bs = "log", link_ndt = "log",
      link_bias = "logit")

    Beta(link = "logit", link_phi = "log")

    von_mises(link = "tan_half", link_kappa = "log")

    asym_laplace(link = "identity", link_sigma = "log",
      link_quantile = "logit")

    hurdle_poisson(link = "log")

    hurdle_negbinomial(link = "log", link_shape = "log",
      link_hu = "logit")

    hurdle_gamma(link = "log", link_shape = "log", link_hu = "logit")

    hurdle_lognormal(link = "identity", link_sigma = "log",
      link_hu = "logit")

    zero_inflated_beta(link = "logit", link_phi = "log",
      link_zi = "logit")

    zero_one_inflated_beta(link = "logit", link_phi = "log",
      link_zoi = "logit", link_coi = "logit")

    zero_inflated_poisson(link = "log", link_zi = "logit")

    zero_inflated_negbinomial(link = "log", link_shape = "log",
      link_zi = "logit")

    zero_inflated_binomial(link = "logit", link_zi = "logit")

    categorical(link = "logit")

    cumulative(link = "logit", link_disc = "log",
      threshold = c("flexible", "equidistant"))

    sratio(link = "logit", link_disc = "log", threshold = c("flexible",
      "equidistant"))

    cratio(link = "logit", link_disc = "log", threshold = c("flexible",
      "equidistant"))

    acat(link = "logit", link_disc = "log", threshold = c("flexible",
      "equidistant"))

### Arguments

`family` | A character string naming the distribution of the response variable be used in the model. Currently, the following families are supported: `gaussian`, `student`, `binomial`, `bernoulli`, `poisson`, `negbinomial`, `geometric`, `Gamma`, `skew_normal`, `lognormal`, `shifted_lognormal`, `exgaussian`, `wiener`, `inverse.gaussian`, `exponential`, `weibull`, `frechet`, `Beta`, `von_mises`, `asym_laplace`, `gen_extreme_value`, `categorical`, `cumulative`, `cratio`, `sratio`, `acat`, `hurdle_poisson`, `hurdle_negbinomial`, `hurdle_gamma`, `hurdle_lognormal`, `zero_inflated_binomial`, `zero_inflated_beta`, `zero_inflated_negbinomial`, `zero_inflated_poisson`, and `zero_one_inflated_beta`.
`link` | A specification for the model link function. This can be a name/expression or character string. See the 'Details' section for more information on link functions supported by each family.
`link_sigma` | Link of auxiliary parameter `sigma` if being predicted.
`link_shape` | Link of auxiliary parameter `shape` if being predicted.
`link_nu` | Link of auxiliary parameter `nu` if being predicted.
`link_phi` | Link of auxiliary parameter `phi` if being predicted.
`link_kappa` | Link of auxiliary parameter `kappa` if being predicted.
`link_beta` | Link of auxiliary parameter `beta` if being predicted.
`link_zi` | Link of auxiliary parameter `zi` if being predicted.
`link_hu` | Link of auxiliary parameter `hu` if being predicted.
`link_zoi` | Link of auxiliary parameter `zoi` if being predicted.
`link_coi` | Link of auxiliary parameter `coi` if being predicted.
`link_disc` | Link of auxiliary parameter `disc` if being predicted.
`link_bs` | Link of auxiliary parameter `bs` if being predicted.
`link_ndt` | Link of auxiliary parameter `ndt` if being predicted.
`link_bias` | Link of auxiliary parameter `bias` if being predicted.
`link_xi` | Link of auxiliary parameter `xi` if being predicted.
`link_alpha` | Link of auxiliary parameter `alpha` if being predicted.
`link_quantile` | Link of auxiliary parameter `quantile` if being predicted.
`threshold` | A character string indicating the type of thresholds (i.e. intercepts) used in an ordinal model. `"flexible"` provides the standard unstructured thresholds and `"equidistant"` restricts the distance between consecutive thresholds to the same value.

### Details

Family `gaussian` with `identity` link leads to linear regression. Family `student` with `identity` link leads to robust linear regression that is less influenced by outliers. Family `skew_normal` can handle skewed responses in linear regression. Families `poisson`, `negbinomial`, and `geometric` with `log` link lead to regression models for count data. Families `binomial` and `bernoulli` with `logit` link leads to logistic regression and family `categorical` to multi-logistic regression when there are more than two possible outcomes. Families `cumulative`, `cratio` ('continuation ratio'), `sratio` ('stopping ratio'), and `acat` ('adjacent category') leads to ordinal regression. Families `Gamma`, `weibull`, `exponential`, `lognormal`, `frechet`, and `inverse.gaussian` can be used (among others) for survival regression. Families `weibull`, `frechet`, and `gen_extreme_value` ('generalized extreme value') allow for modeling extremes. Family `asym_laplace` allows for quantile regression when fixing the auxiliary `quantile` parameter to the quantile of interest. Family `exgaussian` ('exponentially modified Gaussian') and `shifted_lognormal` are especially suited to model reaction times. The `wiener` family provides an implementation of the Wiener diffusion model. For this family, the main formula predicts the drift parameter 'delta' and all other parameters are modeled as auxiliary parameters (see `brmsformula` for details). Families `hurdle_poisson`, `hurdle_negbinomial`, `hurdle_gamma`, `hurdle_lognormal`, `zero_inflated_poisson`, `zero_inflated_negbinomial`, `zero_inflated_binomial`, `zero_inflated_beta`, and `zero_one_inflated_beta` allow to estimate zero-inflated and hurdle models. These models can be very helpful when there are many zeros in the data (or ones in case of one-inflated models) that cannot be explained by the primary distribution of the response. Families `hurdle_lognormal` and `hurdle_gamma` are especially useful, as traditional `lognormal` or `Gamma` models cannot be reasonably fitted for data containing zeros in the response.

In the following, we list all possible links for each family. The families `gaussian`, `student`, `skew_normal`, `exgaussian`, `asym_laplace`, and `gen_extreme_value` accept the links (as names) `identity`, `log`, and `inverse`; families `poisson`, `negbinomial`, `geometric`, `zero_inflated_poisson`, `zero_inflated_negbinomial`, `hurdle_poisson`, and `hurdle_negbinomial` the links `log`, `identity`, and `sqrt`; families `binomial`, `bernoulli`, `Beta`, `zero_inflated_binomial`, `zero_inflated_beta`, and `zero_one_inflated_beta` the links `logit`, `probit`, `probit_approx`, `cloglog`, `cauchit`, and `identity`; families `cumulative`, `cratio`, `sratio`, and `acat` the links `logit`, `probit`, `probit_approx`, `cloglog`, and `cauchit`; family `categorical` the link `logit`; families `Gamma`, `weibull`, `exponential`, `frechet`, and `hurdle_gamma` the links `log`, `identity`, and `inverse`; families `lognormal` and `hurdle_lognormal` the links `identity` and `inverse`; family `inverse.gaussian` the links `1/mu^2`, `inverse`, `identity` and `log`; family `von_mises` the link `tan_half`; family `wiener` the link `identity`. The first link mentioned for each family is the default.

Please note that when calling the `Gamma` family function, the default link will be `inverse` not `log`. Also, the `probit_approx` link cannot be used when calling the `binomial` family function.

The current implementation of `inverse.gaussian` models has some convergence problems and requires carefully chosen prior distributions to work efficiently. For this reason, we currently do not recommend to use the `inverse.gaussian` family, unless you really feel that your data requires exactly this type of model.

### See Also

`brm`, `family`, `customfamily`

### Examples

     # create a family object
     (fam1 <- student("log"))
     # alternatively use the brmsfamily function
     (fam2 <- brmsfamily("student", "log"))
     # both leads to the same object
     identical(fam1, fam2)

[Package brms version 2.6.0 Index]