From 0dbe050f24a6ca93d2012ef9879ab4127bf41e20 Mon Sep 17 00:00:00 2001
From: jgabry <jgabry@gmail.com>
Date: Mon, 22 Apr 2024 15:22:15 -0600
Subject: [PATCH] Document the `draws_of` trick to emulate `rstan::extract()`

https://github.com/stan-dev/cmdstanr/issues/183

Closes #632 and closes #183
---
 vignettes/cmdstanr.Rmd  |  5 +++++
 vignettes/posterior.Rmd | 26 +++++++++++++++++++++++++-
 2 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/vignettes/cmdstanr.Rmd b/vignettes/cmdstanr.Rmd
index b9b2e341..d6ee023e 100644
--- a/vignettes/cmdstanr.Rmd
+++ b/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
diff --git a/vignettes/posterior.Rmd b/vignettes/posterior.Rmd
index 15da8e68..0039554d 100644
--- a/vignettes/posterior.Rmd
+++ b/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()`.