fit-method-draws: Extract posterior draws
In stan-dev/cmdstanr: R Interface to 'CmdStan'

fit-method-draws

R Documentation

Extract posterior draws

Description

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.

Usage

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

Arguments

variables

(character vector) Optionally, the names of the variables (parameters, transformed parameters, and generated quantities) to read in.

If NULL (the default) then all variables are included.
If an empty string (variables="") then none are included.
For non-scalar variables all elements or specific elements can be selected:
- variables = "theta" selects all elements of theta;
- variables = c("theta[1]", "theta[3]") selects only the 1st and 3rd elements.

inc_warmup

(logical) Should warmup draws be included? Defaults to FALSE. Ignored except when used with CmdStanMCMC objects.

format

(string) The format of the returned draws or point estimates. Must be a valid format from the posterior package. The defaults are the following.

For sampling and generated quantities the default is "draws_array". This format keeps the chains separate. To combine the chains use any of the other formats (e.g. "draws_matrix").
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 of the format from the posterior package (e.g. format = "draws_df") or omitting the "draws_" prefix (e.g. format = "df").

Changing the default format: To change the default format for an entire R session use options(cmdstanr_draws_format = format), where format is the name (in quotes) of a valid format from the posterior package. For example options(cmdstanr_draws_format = "draws_df") will change the default to a data frame.

Note about efficiency: 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) because there are no chains. 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.

Examples

## Not run: 
# logistic regression with intercept alpha and coefficients beta
fit <- cmdstanr_example("logistic", method = "sample")

# returned as 3-D array (see ?posterior::draws_array)
draws <- fit$draws()
dim(draws)
str(draws)

# can easily convert to other formats (data frame, matrix, list)
# using the posterior package
head(posterior::as_draws_matrix(draws))

# or can specify 'format' argument to avoid manual conversion
# matrix format combines all chains
draws <- fit$draws(format = "matrix")
head(draws)

# can select specific parameters
fit$draws("alpha")
fit$draws("beta")  # selects entire vector beta
fit$draws(c("alpha", "beta[2]"))

# can be passed directly to bayesplot plotting functions
bayesplot::color_scheme_set("brightblue")
bayesplot::mcmc_dens(fit$draws(c("alpha", "beta")))
bayesplot::mcmc_scatter(fit$draws(c("beta[1]", "beta[2]")), alpha = 0.3)


# example using variational inference
fit <- cmdstanr_example("logistic", method = "variational")
head(fit$draws("beta")) # a matrix by default
head(fit$draws("beta", format = "df"))

## End(Not run)

stan-dev/cmdstanr documentation built on April 21, 2024, 5:38 a.m.