R: Fit Bayesian Linear and Generalized Linear Mixed-Effects...

blme {blme} | R Documentation

## Fit Bayesian Linear and Generalized Linear Mixed-Effects Models

### Description

Maximum a posteriori estimation for linear and generalized linear mixed-effects models in a Bayesian setting. Built off of `lmer`.

### Usage

    blmer(formula, data, REML = TRUE,
          control = lmerControl(), start = NULL, verbose = 0L,
          subset, weights, na.action, offset, contrasts = NULL,
          devFunOnly = FALSE, cov.prior = wishart,
          fixef.prior = NULL, resid.prior = NULL, ...)
    bglmer(formula, data, family = gaussian,
           control = glmerControl(), start = NULL, verbose = 0L,
           maxit = 100L,
           nAGQ = 1L, subset, weights, na.action, offset,
           contrasts = NULL, mustart, etastart,
           devFunOnly = FALSE, cov.prior = wishart,
           fixef.prior = NULL, ...)

### Arguments

`cov.prior` | a BLME prior or list of priors with allowable distributions: `wishart`, `invwishart`, `gamma`, `invgamma`, or `NULL`. Imposes a prior over the covariance of the random effects/modeled coefficients. Default is `wishart`. The `NULL` argument imposes flat priors over all relevant parameters.
`fixef.prior` | a BLME prior of family `normal`, `t`, or `NULL`. Imposes a prior over the fixed effects/modeled coefficients. Default is `NULL`.
`resid.prior` | a BLME prior of family `gamma`, `invamma`, `point` or `NULL`. Imposes a prior over the noise/residual variance, also known as common scale parameter or the conditional variance given the random effects. Default is `NULL`.
`start` | like the `start` arguments for `lmer` and `glmer` a numeric vector or named list. Unlike the aforementioned, list members of `fixef` and `sigma` are applicable to linear mixed models provided that numeric optimization is required for these parameters.
`formula, data, REML, family, control, verbose, maxit, nAGQ, mustart, etastart, devFunOnly, ...` | model specification arguments as in `lmer` and `glmer`; see there for details.
`subset, weights, na.action, offset, contrasts` | further model specification arguments as in `lm`; see there for details.

### Details

The bulk of the usage for `blmer` and `bglmer` closely follows the functions `lmer` and `glmer`. Those help pages provide a good overview of fitting linear and generalized linear mixed models. The primary distinction is that `blmer` and `bglmer` allow the user to do Bayesian inference or penalized maximum likelihood, with priors imposed on the different model components. For the specifics of any distribution listed below, see the distributions page.

Covariance Prior

The `cov.prior` argument applies a prior over the covariance matrix of the random effects/modeled coefficients. As there is one covariance matrix for every named grouping factor - that is every element that appears to the right of a vertical bar ("|") in the model formula - it is possible to apply as many different priors as there are said factors.

The general formats of an argument to `blmer` or `bglmer` for such a prior are of the form:

- `cov.prior = factor.name ~ covariance.distribution(option1 = value1, ...)`

- `cov.prior = list(fc.nm ~ dist1, fc.nm ~ dist2, ..., default.distribution)`

If the “`factor.name ~`” construct is ommitted, the prior is interpretted as a default and applied to all factors that lack specific priors of their own. Options are not required, but permit fine-tuning of the model.

Supported distributions are `gamma`, `invgamma`, `wishart`, `invwishart`, `NULL`, and `custom`.

The `common.scale` option, a logical, determines whether or not the prior applies to in the absolute-real world sense (value = `FALSE`), or if the prior is applied to the random effect covariance divided by the estimated residual variance (`TRUE`). As a practical matter, when false computation can be slower as the profiled common scale may no longer have a closed-form solution. As such, the default for all cases is `TRUE`.

Other options are specified along with the specific distributions and defaults are explained in the blme distributions page.

Fixed Effects Prior

Priors on the fixed effects, or unmodeled coefficients, are specified in a fashion similar to that of covariance priors. The general format is

- `fixef.prior = multivariate.distribution(options1 = value1, ...)`

At present, the implemented multivariate distributions are `normal`, `t`, and `NULL`. `t` priors cannot be used when `REML` is `TRUE`, as that integral does not have a closed form solution.

Residual Variance Prior

The general format for a residual variance prior is the same as for a fixed effect prior. The supported distributions are `point`, `gamma`, `invgamma`.

### Value

An object of class `"bmerMod"`, for which many methods are available. See there for details.

### See Also

`lmer`, `glmer`, `merMod` class, and `lm`.

### Examples

    ##  covariance prior
    data("sleepstudy", package = "lme4")
    (fm1 <- blmer(Reaction ~ Days + (0 + Days|Subject), sleepstudy,
                  cov.prior = gamma))
    (fm2 <- blmer(Reaction ~ Days + (0 + Days|Subject), sleepstudy,
                  cov.prior = gamma(shape = 2, rate = 0.5, posterior.scale = 'sd')))
    (fm3 <- blmer(Reaction ~ Days + (1 + Days|Subject), sleepstudy,
                  cov.prior = wishart))
    (fm4 <- blmer(Reaction ~ Days + (1 + Days|Subject), sleepstudy,
                  cov.prior = invwishart(df = 5, scale = diag(0.5, 2))))

    ##  custom prior
    penaltyFn <- function(sigma)
      dcauchy(sigma, 0, 10, log = TRUE)
    (fm5 <- blmer(Reaction ~ Days + (0 + Days|Subject), sleepstudy,
                  cov.prior = custom(penaltyFn, chol = TRUE, scale = "log")))

    ##  fixed effect prior
    (fm6 <- blmer(Reaction ~ Days + (1 + Days|Subject), sleepstudy,
                  cov.prior = NULL,
                  fixef.prior = normal))
    (fm7 <- blmer(Reaction ~ Days + (1 + Days|Subject), sleepstudy,
                  cov.prior = NULL,
                  fixef.prior = normal(cov = diag(0.5, 2), common.scale = FALSE)))

    ##  residual variance prior
    ##  eight schools example
    y <- c(28, 8, -3, 7, -1, 1, 18, 12);
    sigma <- c(15, 10, 16, 11, 9, 11, 10, 18);
    g <- 1:8;

    (schools <- blmer(y ~ 1 + (1 | g), resid.prior = point,
                      cov.prior = NULL, REML = FALSE,
                      weights = 1 / sigma^2));

[Package blme version 1.0-4 Index]