Merge pull request #955 from stan-dev/document-structured-draws-via-draws_of

Document the `draws_of` trick to emulate `rstan::extract()`

Author: andrjohns

vignettes/cmdstanr.Rmd

@@ -258,6 +258,11 @@ In general, converting to a different draws format in this way will be slower
 than just setting the appropriate format initially in the call to the `$draws()`
 method, but in most cases the speed difference will be minor.
 
+The vignette 
+[Working with Posteriors](https://mc-stan.org/cmdstanr/articles/posterior.html) 
+has more details on posterior draws, including how to reproduce the structured
+output RStan users are accustomed to getting from `rstan::extract()`.
+
 #### Plotting draws
 
 Plotting posterior distributions is as easy as passing the object returned by

vignettes/posterior.Rmd

@@ -121,6 +121,30 @@ To convert an existing draws object to a different format use the
 `posterior::as_draws_*()` functions.
 
 To manipulate the `draws` objects use the various methods described in the
-posterior package [vignettes](https://mc-stan.org/posterior/articles/index.html)
+**posterior** package [vignettes](https://mc-stan.org/posterior/articles/index.html)
 and [documentation](https://mc-stan.org/posterior/reference/index.html).
 
+### Structured draws similar to `rstan::extract()`
+
+The **posterior** package's `rvar` format provides a multidimensional,
+sample-based representation of random variables. See
+https://mc-stan.org/posterior/articles/rvar.html for details. 
+In addition to being useful in its own right, this format also allows CmdStanR
+users to obtain draws in a similar format to `rstan::extract()`.
+
+Suppose we have a parameter `matrix[2,3] x`. The `rvar` format lets you 
+interact with `x` as if it's a `2 x 3` matrix and automatically applies operations
+over the many posterior draws of `x`. To instead directly access the draws of `x`
+while maintaining the structure of the matrix use `posterior::draws_of()`. 
+For example: 
+
+```{r structured-draws, eval = FALSE}
+draws <- posterior::as_draws_rvars(fit$draws())
+x_rvar <- draws$x
+x_array <- posterior::draws_of(draws$x)
+```
+
+The object `x_rvar` will be an `rvar` that can be used like a `2 x 3` matrix,
+with the draws handled behind the scenes. The object `x_array` will be a 
+`4000 x 2 x 3` array (assuming `4000` posterior draws), which is the same as it
+would be after being extracted from the list returned by `rstan::extract()`.