Proposal for methods for accessing posterior draws and sampler diagnostics

[jgabry]

After discussing with @mitzimorris, here is a proposal for user-facing methods for accessing the parameter (and generated quantities) draws and the sampler diagnostics:

Suppose for example that we run 4 chains each with 1000 warmup and 1000 post-warmup iterations. For simplicity also assume the model has just 2 parameters.

# get post-warmup draws of the two parameters as 3-D array
fit$draws(inc_warmup=FALSE) # dim 1000 x 4 x 2

# get warmup and post-warmup draws together as 3-D array
fit$draws(inc_warmup=TRUE)  # dim 2000 x 4 x 2

# get post-warmup sampler diagnostics (accept_stat__, stepsize__, treedepth__, n_leapfrog__, divergent__, energy__) as 3-D array 
fit$sampler_diagnostics(inc_warmup=FALSE) # dim 1000 x 4 x 6

# get warmup and post-warmup sampler diagnostics together as 3-D array 
fit$sampler_diagnostics(inc_warmup=TRUE) # dim 2000 x 4 x 6

For R users these objects will be draws_array objects from the posterior package and then can easily be transformed to other formats using the functionality of posterior.

Questions

• where does lp__ belong? Should it be a column in the output from $draws() or from sampler_diagnostics()?

• what do you think of the names for the methods?

• other thoughts?

[jgabry]

Also, we need to merge #95 before adding these methods but we’re close to merging it.