Extract draws from a Bayesian model for one or more variables (possibly with named dimensions) into one of two types of long-format data frames.

gather_draws(model, ..., regex = FALSE, sep = "[, ]", n = NULL, seed = NULL)

spread_draws(model, ..., regex = FALSE, sep = "[, ]", n = NULL, seed = NULL)

## Arguments

model A supported Bayesian model fit. Tidybayes supports a variety of model objects; for a full list of supported models, see tidybayes-models. Expressions in the form of variable_name[dimension_1, dimension_2, ...] | wide_dimension. See Details. If TRUE, variable names are treated as regular expressions and all column matching the regular expression and number of dimensions are included in the output. Default FALSE. Separator used to separate dimensions in variable names, as a regular expression. The number of draws to return, or NULL to return all draws. A seed to use when subsampling draws (i.e. when n is not NULL).

A data frame.

## Details

Imagine a JAGS or Stan fit named fit. The model may contain a variable named b[i,v] (in the JAGS or Stan language) with dimension i in 1:100 and dimension v in 1:3. However, the default format for draws returned from JAGS or Stan in R will not reflect this indexing structure, instead they will have multiple columns with names like "b[1,1]", "b[2,1]", etc.

spread_draws and gather_draws provide a straightforward syntax to translate these columns back into properly-indexed variables in two different tidy data frame formats, optionally recovering dimension types (e.g. factor levels) as it does so.

spread_draws and gather_draws return data frames already grouped by all dimensions used on the variables you specify.

The difference between spread_draws is that names of variables in the model will be spread across the data frame as column names, whereas gather_draws will gather variables into a single column named ".variable" and place values of variables into a column named ".value". To use naming schemes from other packages (such as broom), consider passing results through functions like to_broom_names() or to_ggmcmc_names().

For example, spread_draws(fit, a[i], b[i,v]) might return a grouped data frame (grouped by i and v), with:

• column ".chain": the chain number. NA if not applicable to the model type; this is typically only applicable to MCMC algorithms.

• column ".iteration": the iteration number. Guaranteed to be unique within-chain only. NA if not applicable to the model type; this is typically only applicable to MCMC algorithms.

• column ".draw": a unique number for each draw from the posterior. Order is not guaranteed to be meaningful.

• column "i": value in 1:5

• column "v": value in 1:10

• column "a": value of "a[i]" for draw ".draw"

• column "b": value of "b[i,v]" for draw ".draw"

gather_draws(fit, a[i], b[i,v]) on the same fit would return a grouped data frame (grouped by i and v), with:

• column ".chain": the chain number

• column ".iteration": the iteration number

• column ".draw": the draw number

• column "i": value in 1:5

• column "v": value in 1:10, or NA if ".variable" is "a".

• column ".variable": value in c("a", "b").

• column ".value": value of "a[i]" (when ".variable" is "a") or "b[i,v]" (when ".variable" is "b") for draw ".draw"

spread_draws and gather_draws can use type information applied to the fit object by recover_types() to convert columns back into their original types. This is particularly helpful if some of the dimensions in your model were originally factors. For example, if the v dimension in the original data frame data was a factor with levels c("a","b","c"), then we could use recover_types before spread_draws:

fit %&gt;%
recover_types(data) <!-- %\&gt;\% -->


Which would return the same data frame as above, except the "v" column would be a value in c("a","b","c") instead of 1:3.

For variables that do not share the same subscripts (or share some but not all subscripts), we can supply their specifications separately. For example, if we have a variable d[i] with the same i subscript as b[i,v], and a variable x with no subscripts, we could do this:

spread_draws(fit, x, d[i], b[i,v])

Which is roughly equivalent to this:

spread_draws(fit, x) %&gt;%
group_by(i,v)

Similarly, this:

gather_draws(fit, x, d[i], b[i,v])

Is roughly equivalent to this:

bind_rows(
gather_draws(fit, x),
gather_draws(fit, d[i]),
gather_draws(fit, b[i,v])
)

The c and cbind functions can be used to combine multiple variable names that have the same dimensions. For example, if we have several variables with the same subscripts i and v, we could do either of these:

spread_draws(fit, c(w, x, y, z)[i,v])
spread_draws(fit, cbind(w, x, y, z)[i,v])  # equivalent

Each of which is roughly equivalent to this:

spread_draws(fit, w[i,v], x[i,v], y[i,v], z[i,v])

Besides being more compact, the c()-style syntax is currently also faster (though that may change).

Dimensions can be omitted from the resulting data frame by leaving their names blank; e.g. spread_draws(fit, b[,v]) will omit the first dimension of b from the output. This is useful if a dimension is known to contain all the same value in a given model.

The shorthand .. can be used to specify one column that should be put into a wide format and whose names will be the base variable name, plus a dot ("."), plus the value of the dimension at ... For example:

spread_draws(fit, b[i,..]) would return a grouped data frame (grouped by i), with:

• column ".chain": the chain number

• column ".iteration": the iteration number

• column ".draw": the draw number

• column "i": value in 1:20

• column "b.1": value of "b[i,1]" for draw ".draw"

• column "b.2": value of "b[i,2]" for draw ".draw"

• column "b.3": value of "b[i,3]" for draw ".draw"

An optional clause in the form | wide_dimension can also be used to put the data frame into a wide format based on wide_dimension. For example, this:

spread_draws(fit, b[i,v] | v)

is roughly equivalent to this:

spread_draws(fit, b[i,v]) %&gt;% spread(v,b)

The main difference between using the | syntax instead of the .. syntax is that the | syntax respects prototypes applied to dimensions with recover_types(), and thus can be used to get columns with nicer names. For example:

fit %&gt;% recover_types(data) %&gt;% spread_draws(b[i,v] | v)

would return a grouped data frame (grouped by i), with:

• column ".chain": the chain number

• column ".iteration": the iteration number

• column ".draw": the draw number

• column "i": value in 1:20

• column "a": value of "b[i,1]" for draw ".draw"

• column "b": value of "b[i,2]" for draw ".draw"

• column "c": value of "b[i,3]" for draw ".draw"

The shorthand . can be used to specify columns that should be nested into vectors, matrices, or n-dimensional arrays (depending on how many dimensions are specified with .).

For example, spread_draws(fit, a[.], b[.,.]) might return a data frame, with:

• column ".chain": the chain number.

• column ".iteration": the iteration number.

• column ".draw": a unique number for each draw from the posterior.

• column "a": a list column of vectors.

• column "b": a list column of matrices.

Ragged arrays are turned into non-ragged arrays with missing entries given the value NA.

Finally, variable names can be regular expressions by setting regex = TRUE; e.g.:

spread_draws(fit, b_.*[i], regex = TRUE)

Would return a tidy data frame with variables starting with b_ and having one dimension.

recover_types(), compose_data().

## Examples


library(dplyr)
library(ggplot2)

data(RankCorr, package = "ggdist")

RankCorr %>%
spread_draws(b[i, j])#> # A tibble: 12,000 x 6
#> # Groups:   i, j [12]
#>        i     j      b .chain .iteration .draw
#>    <int> <int>  <dbl>  <int>      <int> <int>
#>  1     1     1 -0.927      1          1     1
#>  2     1     1 -0.979      1          2     2
#>  3     1     1 -1.15       1          3     3
#>  4     1     1 -1.09       1          4     4
#>  5     1     1 -1.20       1          5     5
#>  6     1     1 -1.07       1          6     6
#>  7     1     1 -1.11       1          7     7
#>  8     1     1 -1.06       1          8     8
#>  9     1     1 -0.831      1          9     9
#> 10     1     1 -0.986      1         10    10
#> # ... with 11,990 more rows
RankCorr %>%
spread_draws(b[i, j], tau[i], u_tau[i])#> # A tibble: 12,000 x 8
#> # Groups:   i, j [12]
#>        i     j      b .chain .iteration .draw   tau u_tau
#>    <int> <int>  <dbl>  <int>      <int> <int> <dbl> <dbl>
#>  1     1     1 -0.927      1          1     1  5.79  5.87
#>  2     1     1 -0.979      1          2     2  6.26  4.91
#>  3     1     1 -1.15       1          3     3  7.38  3.34
#>  4     1     1 -1.09       1          4     4  5.97  6.96
#>  5     1     1 -1.20       1          5     5  6.01  5.30
#>  6     1     1 -1.07       1          6     6  7.03  5.34
#>  7     1     1 -1.11       1          7     7  7.39  5.53
#>  8     1     1 -1.06       1          8     8  5.98  6.79
#>  9     1     1 -0.831      1          9     9  6.75  5.40
#> 10     1     1 -0.986      1         10    10  6.76  6.63
#> # ... with 11,990 more rows

RankCorr %>%
gather_draws(b[i, j], tau[i], u_tau[i])#> # A tibble: 18,000 x 7
#> # Groups:   i, j, .variable [18]
#>        i     j .chain .iteration .draw .variable .value
#>    <int> <int>  <int>      <int> <int> <chr>      <dbl>
#>  1     1     1      1          1     1 b         -0.927
#>  2     1     1      1          2     2 b         -0.979
#>  3     1     1      1          3     3 b         -1.15
#>  4     1     1      1          4     4 b         -1.09
#>  5     1     1      1          5     5 b         -1.20
#>  6     1     1      1          6     6 b         -1.07
#>  7     1     1      1          7     7 b         -1.11
#>  8     1     1      1          8     8 b         -1.06
#>  9     1     1      1          9     9 b         -0.831
#> 10     1     1      1         10    10 b         -0.986
#> # ... with 17,990 more rows
RankCorr %>%
gather_draws(tau[i], typical_r) %>%
median_qi()#> # A tibble: 4 x 8
#> # Groups:   i [4]
#>       i .variable .value .lower .upper .width .point .interval
#>   <int> <chr>      <dbl>  <dbl>  <dbl>  <dbl> <chr>  <chr>
#> 1     1 tau        6.03   5.03   7.11    0.95 median qi
#> 2     2 tau        3.30   2.41   4.46    0.95 median qi
#> 3     3 tau        3.65   2.73   4.72    0.95 median qi
#> 4    NA typical_r  0.548  0.309  0.778   0.95 median qi