Extract posterior draws after MCMC or approximate posterior draws after variational approximation using formats provided by the posterior package.

The variables include the parameters, transformed parameters, and generated quantities from the Stan program as well as lp__, the total log probability (target) accumulated in the model block.

draws(
variables = NULL,
inc_warmup = FALSE,
format = getOption("cmdstanr_draws_format", "draws_matrix")
)

## Arguments

variables (character vector) The variables to read in. If NULL (the default) then all variables are included. (logical) Should warmup draws be included? Defaults to FALSE. Ignored except when used with CmdStanMCMC objects. (string) The format of the returned draws or point estimates. Must be a valid format from the posterior package. The default can be set using the option "cmdstanr_draws_format", otherwise the defaults are the following. For sampling and generated quantities the default is "draws_array". For point estimates from optimization and approximate draws from variational inference the default is "draws_matrix". To use a different format it can be specified as the full name (e.g. "draws_df") or omitting the "draws_" prefix (e.g. "df"). For models with a large number of parameters (20k+) we recommend using the draws_list format, which is the most efficient and RAM friendly when combining draws from multiple chains. If speed or memory is not a constraint we recommend selecting the format that most suits the coding style of the post processing phase.

## Value

Depends on the value of format. The defaults are:

• For MCMC, a 3-D draws_array object (iteration x chain x variable).

• For standalone generated quantities, a 3-D draws_array object (iteration x chain x variable).

• For variational inference, a 2-D draws_matrix object (draw x variable). An additional variable lp_approx__ is also included, which is the log density of the variational approximation to the posterior evaluated at each of the draws.

• For optimization, a 1-row draws_matrix with one column per variable. These are not actually draws, just point estimates stored in the draws_matrix format. See $mle() to extract them as a numeric vector. ## See also CmdStanMCMC, CmdStanMLE, CmdStanVB, CmdStanGQ ## Examples # \dontrun{ library(posterior) library(bayesplot) color_scheme_set("brightblue") # logistic regression with intercept alpha and coefficients beta fit <- cmdstanr_example("logistic")#> Model executable is up to date! # returned as 3-D array (see ?posterior::draws_array) draws <- fit$draws()
dim(draws)#> [1] 1000    4  105str(draws)#>  'draws_array' num [1:1000, 1:4, 1:105] -65.5 -67.3 -65.1 -65.5 -65 ...
#>  - attr(*, "dimnames")=List of 3
#>   ..$iteration: chr [1:1000] "1" "2" "3" "4" ... #> ..$ chain    : chr [1:4] "1" "2" "3" "4"
#>   ..$variable : chr [1:105] "lp__" "alpha" "beta[1]" "beta[2]" ... # can easily convert to other formats (data frame, matrix, list) as_draws_df(draws) # see also as_draws_matrix, as_draws_list#> # A draws_df: 1000 iterations, 4 chains, and 105 variables #> lp__ alpha beta[1] beta[2] beta[3] log_lik[1] log_lik[2] log_lik[3] #> 1 -66 0.016 -0.76 -0.27 0.554 -0.64 -0.31 -0.60 #> 2 -67 0.831 -0.66 -0.51 1.054 -0.39 -0.41 -0.42 #> 3 -65 0.302 -0.35 -0.45 0.767 -0.61 -0.41 -0.74 #> 4 -66 0.535 -0.93 -0.13 0.414 -0.39 -0.48 -0.30 #> 5 -65 0.257 -0.42 -0.34 0.896 -0.62 -0.31 -0.59 #> 6 -67 0.306 -0.53 -0.21 0.039 -0.51 -0.74 -0.58 #> 7 -67 0.676 -1.01 -0.55 0.966 -0.40 -0.34 -0.44 #> 8 -66 0.201 -0.91 0.03 0.572 -0.51 -0.29 -0.28 #> 9 -66 0.112 -0.86 -0.10 0.336 -0.55 -0.38 -0.43 #> 10 -66 0.667 -0.42 -0.24 0.796 -0.43 -0.46 -0.38 #> # ... with 3990 more draws, and 97 more variables #> # ... hidden reserved variables {'.chain', '.iteration', '.draw'} # or can specify 'format' argument to avoid manual conversion draws <- fit$draws(format = "df")

# can select specific parameters
fit$draws("alpha")#> # A draws_array: 1000 iterations, 4 chains, and 1 variables #> , , variable = alpha #> #> chain #> iteration 1 2 3 4 #> 1 0.016 0.57 0.27 0.25 #> 2 0.831 0.38 0.61 0.42 #> 3 0.302 0.42 0.27 0.38 #> 4 0.535 0.68 0.16 0.55 #> 5 0.257 0.37 0.23 0.26 #> #> # ... with 995 more iterationsfit$draws("beta")  # selects entire vector beta#> # A draws_array: 1000 iterations, 4 chains, and 3 variables
#> , , variable = beta[1]
#>
#>          chain
#> iteration     1     2      3     4
#>         1 -0.76 -1.03 -0.836 -0.49
#>         2 -0.66 -1.18 -1.239 -0.69
#>         3 -0.35 -0.48 -0.086 -0.90
#>         4 -0.93 -0.98 -0.188 -0.91
#>         5 -0.42 -0.29 -0.792 -0.42
#>
#> , , variable = beta[2]
#>
#>          chain
#> iteration     1      2      3     4
#>         1 -0.27 -0.538  0.092 -0.58
#>         2 -0.51  0.087 -0.079 -0.23
#>         3 -0.45 -0.540 -0.435 -0.33
#>         4 -0.13 -0.623 -0.534 -0.17
#>         5 -0.34 -0.191  0.028 -0.34
#>
#> , , variable = beta[3]
#>
#>          chain
#> iteration    1    2    3    4
#>         1 0.55 1.27 0.93 0.43
#>         2 1.05 0.85 0.47 0.38
#>         3 0.77 0.92 0.98 1.21
#>         4 0.41 1.10 0.97 0.27
#>         5 0.90 0.88 0.32 0.95
#>
#> # ... with 995 more iterationsfit$draws(c("alpha", "beta[2]"))#> # A draws_array: 1000 iterations, 4 chains, and 2 variables #> , , variable = alpha #> #> chain #> iteration 1 2 3 4 #> 1 0.016 0.57 0.27 0.25 #> 2 0.831 0.38 0.61 0.42 #> 3 0.302 0.42 0.27 0.38 #> 4 0.535 0.68 0.16 0.55 #> 5 0.257 0.37 0.23 0.26 #> #> , , variable = beta[2] #> #> chain #> iteration 1 2 3 4 #> 1 -0.27 -0.538 0.092 -0.58 #> 2 -0.51 0.087 -0.079 -0.23 #> 3 -0.45 -0.540 -0.435 -0.33 #> 4 -0.13 -0.623 -0.534 -0.17 #> 5 -0.34 -0.191 0.028 -0.34 #> #> # ... with 995 more iterations # can be passed directly to bayesplot plotting functions mcmc_dens(fit$draws(c("alpha", "beta")))mcmc_scatter(fit\$draws(c("beta[1]", "beta[2]")), alpha = 0.3)# }