emmeans: mcmc-support – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

mcmc-support

Support for MCMC-based estimation

Description

When a model is fitted using Markov chain Monte Carlo (MCMC) methods, its reference grid contains a post.beta slot. These functions transform those posterior samples to posterior samples of EMMs or related contrasts. They can then be summarized or plotted using, e.g., functions in the coda package.

Usage

## S3 method for class 'emmGrid'
as.mcmc(x, names = TRUE, sep.chains = TRUE, likelihood,
  NE.include = FALSE, ...)

## S3 method for class 'emmGrid'
as.mcmc.list(x, names = TRUE, ...)

Arguments

`x`	An object of class `emmGrid`
`names`	Logical scalar or vector specifying whether variable names are appended to levels in the column labels for the `as.mcmc` or `as.mcmc.list` result – e.g., column names of `treat A` and `treat B` versus just `A` and `B`. When there is more than one variable involved, the elements of `names` are used cyclically.
`sep.chains`	Logical value. If `TRUE`, and there is more than one MCMC chain available, an `mcmc.list` object is returned by `as.mcmc`, with separate EMMs posteriors in each chain.
`likelihood`	Character value or function. If given, simulations are made from the corresponding posterior predictive distribution. If not given, we obtain the posterior distribution of the parameters in `object`. See Prediction section below.
`NE.include`	Logical value. If `TRUE`, non-estimable columns are kept but returned as columns of `NA` values (this may create errors or warnings in subsequent analyses using, say, coda). If `FALSE`, non-estimable columns are dropped, and a warning is issued. (If all are non-estimable, an error is thrown.)
`...`	arguments passed to other methods

Value

An object of class mcmc or mcmc.list.

Details

When the object's post.beta slot is non-trivial, as.mcmc will return an mcmc or mcmc.list object that can be summarized or plotted using methods in the coda package. In these functions, post.beta is transformed by post-multiplying it by t(linfct), creating a sample from the posterior distribution of LS means. In as.mcmc, if sep.chains is TRUE and there is in fact more than one chain, an mcmc.list is returned with each chain's results. The as.mcmc.list method is guaranteed to return an mcmc.list, even if it comprises just one chain.

Prediction

When likelihood is specified, it is used to simulate values from the posterior predictive distribution corresponding to the given likelihood and the posterior distribution of parameter values. Denote the likelihood function as f(y|θ,φ), where y is a response, θ is the parameter estimated in object, and φ comprises zero or more additional parameters to be specified. If likelihood is a function, that function should take as its first argument a vector of θ values (each corresponding to one row of object@grid). Any φ values should be specified as additional named function arguments, and passed to likelihood via .... This function should simulate values of y.

A few standard likelihoods are available by specifying likelihood as a character value. They are:

"normal": The normal distribution with mean θ and standard deviation specified by additional argument sigma
"binomial": The binomial distribution with success probability theta, and number of trials specified by trials
"poisson": The Poisson distribution with mean theta (no additional parameters)
"gamma": The gamma distribution with scale parameter θ and shape parameter specified by shape

Examples

if(requireNamespace("coda")) {
  ### A saved reference grid for a mixed logistic model (see lme4::cbpp)
  cbpp.rg <- do.call(emmobj, 
    readRDS(system.file("extdata", "cbpplist", package = "emmeans")))
  # Predictive distribution for herds of size 20
  # (perhaps a bias adjustment should be applied; see "sophisticated" vignette)
  pred.incidence <- coda::as.mcmc(regrid(cbpp.rg), likelihood = "binomial", trials = 20)
}

emmeans

Estimated Marginal Means, aka Least-Squares Means

v1.6.0

GPL-2 | GPL-3

Authors

Russell V. Lenth [aut, cre, cph], Paul Buerkner [ctb], Maxime Herve [ctb], Jonathon Love [ctb], Hannes Riebl [ctb], Henrik Singmann [ctb]

Initial release

2021-04-25