custom_family.Rmd

custom_family Custom Families in brms Models
#### Description 
Define custom families (i.e. response distribution) for use in brms models. It allows users to benefit
from the modeling flexibility of brms, while applying their self-defined likelihood functions. All
of the post-processing methods for brmsfit objects can be made compatible with custom families.
See vignette("brms_customfamilies") for more details. For a list of built-in families see
brmsfamily.
#### Usage
<pre><code>
custom_family(name, dpars = "mu", links = "identity",
type = c("real", "int"), lb = NA, ub = NA, vars = NULL,
specials = NULL, log_lik = NULL, predict = NULL, fitted = NULL,
env = parent.frame())
</code></pre>

#### Arguments
* name Name of the custom family.
* dpars Names of the distributional parameters of the family. One parameter must be named "mu" and the main formula of the model will correspond to that parameter.
* links Names of the link functions of the distributional parameters.
* type Indicates if the response distribution is continuous ("real") or discrete ("int").
* lb Vector of lower bounds of the distributional parameters. Defaults to NA that is no lower bound.
* ub Vector of upper bounds of the distributional parameters. Defaults to NA that is no upper bound.
* vars Names of variables, which are part of the likelihood function without being distributional parameters. That is, vars can be used to pass data to the likelihood. See stanvar for details about adding self-defined data to the generated Stan
model.
* specials A character vector of special options to enable for this custom family. Currently for internal use only.
* log_lik Optional function to compute log-likelihood #### Values of the model in R. This is only relevant if one wants to ensure compatibility with method log_lik.
* predict Optional function to compute predicted #### Values of the model in R. This is only relevant if one wants to ensure compatibility with method predict.
* fitted Optional function to compute fitted #### Values of the model in R. This is only relevant if one wants to ensure compatibility with method fitted.
* env An environment in which certain post-processing functions related to the custom family can be found, if there were not directly passed to custom_family. This is only relevant if one wants to ensure compatibility with the methods
predict, fitted, or log_lik. By default, env is the enviroment from which custom_family is called.
#### Details
The corresponding probability density or mass Stan functions need to have the same name as the
custom family. That is if a family is called myfamily, then the Stan functions should be called
myfamily_lpdf or myfamily_lpmf depending on whether it defines a continuous or discrete distribution.
#### Value
An object of class customfamily inheriting from class brmsfamily.
See Also
brmsfamily, stanvar

#### Examples
```{r}
## Not run:
## demonstrate how to fit a beta-binomial model
## generate some fake data
phi <- 0.7
n <- 300
z <- rnorm(n, sd = 0.2)
ntrials <- sample(1:10, n, replace = TRUE)
eta <- 1 + z
mu <- exp(eta) / (1 + exp(eta))
a <- mu * phi
b <- (1 - mu) * phi
p <- rbeta(n, a, b)
y <- rbinom(n, ntrials, p)
dat <- data.frame(y, z, ntrials)
```
```{r}
# define a custom family
beta_binomial2 <- custom_family(
"beta_binomial2", dpars = c("mu", "phi"),
links = c("logit", "log"), lb = c(NA, 0),
density_ratio 55
type = "int", vars = "trials[n]"
)
```
```{r}
# define the corresponding Stan density function
stan_funs <- "
real beta_binomial2_lpmf(int y, real mu, real phi, int N) {
return beta_binomial_lpmf(y | N, mu * phi, (1 - mu) * phi);
}
"
```
```{r}
# fit the model
fit <- brm(y | trials(ntrials) ~ z, data = dat,
family = beta_binomial2, stan_funs = stan_funs)
summary(fit)
## End(Not run)
```