`R/gather_emmeans_draws.R`

`gather_emmeans_draws.Rd`

Extract draws from the result of a call to `emmeans::emmeans()`

(formerly `lsmeans`

)
or `emmeans::ref_grid()`

applied to a Bayesian model.

```
gather_emmeans_draws(object, value = ".value", ...)
# S3 method for default
gather_emmeans_draws(object, value = ".value", ...)
# S3 method for emm_list
gather_emmeans_draws(object, value = ".value", grid = ".grid", ...)
```

- object
An

`emmGrid`

object such as returned by`emmeans::ref_grid()`

or`emmeans::emmeans()`

.- value
The name of the output column to use to contain the values of draws. Defaults to

`".value"`

.- ...
Additional arguments passed to the underlying method for the type of object given.

- grid
If

`object`

is an`emmeans::emm_list()`

, the name of the output column to use to contain the name of the reference grid that a given row corresponds to. Defaults to`".grid"`

.

A tidy data frame of draws. The columns of the reference grid are returned as-is, with an
additional column called `.value`

(by default) containing marginal draws. The resulting data
frame is grouped by the columns from the reference grid to make use of summary functions like
`point_interval()`

straightforward.

If `object`

is an `emmeans::emm_list()`

, which contains estimates from different reference grids,
an additional column with the default name of `".grid"`

is added to indicate the reference grid for each row in the output.
The name of this column is controlled by the `grid`

argument.

`emmeans::emmeans()`

provides a convenient syntax for generating draws from "estimated marginal means" from a model,
and can be applied to various Bayesian models, like rstanarm::stanreg-objects and
`MCMCglmm::MCMCglmm()`

. Given a `emmeans::ref_grid()`

object as returned by functions like
`emmeans::ref_grid()`

or `emmeans::emmeans()`

applied to a Bayesian model,
`gather_emmeans_draws`

returns a tidy format data frame of draws from
the marginal posterior distributions generated by `emmeans::emmeans()`

.

```
# \donttest{
library(dplyr)
library(magrittr)
library(brms)
library(emmeans)
# Here's an example dataset with a categorical predictor (`condition`) with several levels:
set.seed(5)
n = 10
n_condition = 5
ABC = tibble(
condition = rep(c("A","B","C","D","E"), n),
response = rnorm(n * 5, c(0,1,2,1,-1), 0.5)
)
m = brm(response ~ condition, data = ABC,
# 1 chain / few iterations just so example runs quickly
# do not use in practice
chains = 1, iter = 500)
#> Compiling Stan program...
#> Start sampling
#>
#> SAMPLING FOR MODEL 'a3fabd9798f2736e2d0070f1c2a98a29' NOW (CHAIN 1).
#> Chain 1:
#> Chain 1: Gradient evaluation took 7e-06 seconds
#> Chain 1: 1000 transitions using 10 leapfrog steps per transition would take 0.07 seconds.
#> Chain 1: Adjust your expectations accordingly!
#> Chain 1:
#> Chain 1:
#> Chain 1: Iteration: 1 / 500 [ 0%] (Warmup)
#> Chain 1: Iteration: 50 / 500 [ 10%] (Warmup)
#> Chain 1: Iteration: 100 / 500 [ 20%] (Warmup)
#> Chain 1: Iteration: 150 / 500 [ 30%] (Warmup)
#> Chain 1: Iteration: 200 / 500 [ 40%] (Warmup)
#> Chain 1: Iteration: 250 / 500 [ 50%] (Warmup)
#> Chain 1: Iteration: 251 / 500 [ 50%] (Sampling)
#> Chain 1: Iteration: 300 / 500 [ 60%] (Sampling)
#> Chain 1: Iteration: 350 / 500 [ 70%] (Sampling)
#> Chain 1: Iteration: 400 / 500 [ 80%] (Sampling)
#> Chain 1: Iteration: 450 / 500 [ 90%] (Sampling)
#> Chain 1: Iteration: 500 / 500 [100%] (Sampling)
#> Chain 1:
#> Chain 1: Elapsed Time: 0.006653 seconds (Warm-up)
#> Chain 1: 0.004527 seconds (Sampling)
#> Chain 1: 0.01118 seconds (Total)
#> Chain 1:
#> Warning: The largest R-hat is 1.06, indicating chains have not mixed.
#> Running the chains for more iterations may help. See
#> https://mc-stan.org/misc/warnings.html#r-hat
#> Warning: Bulk Effective Samples Size (ESS) is too low, indicating posterior means and medians may be unreliable.
#> Running the chains for more iterations may help. See
#> https://mc-stan.org/misc/warnings.html#bulk-ess
#> Warning: Tail Effective Samples Size (ESS) is too low, indicating posterior variances and tail quantiles may be unreliable.
#> Running the chains for more iterations may help. See
#> https://mc-stan.org/misc/warnings.html#tail-ess
# Once we've fit the model, we can use emmeans() (and functions
# from that package) to get whatever marginal distributions we want.
# For example, we can get marginal means by condition:
m %>%
emmeans(~ condition) %>%
gather_emmeans_draws() %>%
median_qi()
#> # A tibble: 5 × 7
#> condition .value .lower .upper .width .point .interval
#> <fct> <dbl> <dbl> <dbl> <dbl> <chr> <chr>
#> 1 A 0.184 -0.164 0.533 0.95 median qi
#> 2 B 1.00 0.717 1.30 0.95 median qi
#> 3 C 1.86 1.45 2.26 0.95 median qi
#> 4 D 1.05 0.671 1.37 0.95 median qi
#> 5 E -0.945 -1.30 -0.603 0.95 median qi
# or we could get pairwise differences:
m %>%
emmeans(~ condition) %>%
contrast(method = "pairwise") %>%
gather_emmeans_draws() %>%
median_qi()
#> # A tibble: 10 × 7
#> contrast .value .lower .upper .width .point .interval
#> <chr> <dbl> <dbl> <dbl> <dbl> <chr> <chr>
#> 1 A - B -0.846 -1.34 -0.311 0.95 median qi
#> 2 A - C -1.70 -2.23 -1.11 0.95 median qi
#> 3 A - D -0.872 -1.34 -0.291 0.95 median qi
#> 4 A - E 1.13 0.625 1.62 0.95 median qi
#> 5 B - C -0.863 -1.32 -0.386 0.95 median qi
#> 6 B - D -0.0521 -0.544 0.432 0.95 median qi
#> 7 B - E 1.96 1.42 2.40 0.95 median qi
#> 8 C - D 0.826 0.287 1.36 0.95 median qi
#> 9 C - E 2.80 2.22 3.40 0.95 median qi
#> 10 D - E 2.00 1.42 2.49 0.95 median qi
# see the documentation of emmeans() for more examples of types of
# contrasts supported by that packge.
# }
```