`check_hmc_diagnostics.Rd`

These functions print summaries of important HMC diagnostics or extract
those diagnostics from a `stanfit`

object. See the **Details**
section, below.

check_hmc_diagnostics(object) check_divergences(object) check_treedepth(object) check_energy(object) get_divergent_iterations(object) get_max_treedepth_iterations(object) get_num_leapfrog_per_iteration(object) get_num_divergent(object) get_num_max_treedepth(object) get_bfmi(object) get_low_bfmi_chains(object)

object | A stanfit object. |
---|

The `check_hmc_diagnostics`

function calls the other `check_*`

functions internally and prints an overall summary, but the other
functions can also be called directly:

`check_divergences`

prints the number (and percentage) of iterations that ended with a divergence,`check_treedepth`

prints the number (and percentage) of iterations that saturated the max treedepth,`check_energy`

prints E-BFMI values for each chain for which E-BFMI is less than 0.2.

The `get_*`

functions are for programmatic access to the diagnostics.

`get_divergent_iterations`

and`get_max_treedepth_iterations`

return a logical vector indicating problems for individual iterations,`get_num_divergences`

and`get_num_max_treedepth`

return the number of offending interations,`get_num_leapfrog_per_iteration`

returns an integer vector with the number of leapfrog evalutions for each iteration,`get_bfmi`

returns per-chain E-BFMI values and`get_low_bfmi_chains`

returns the indices of chains with low E-BFMI.

The following are several of many resources that provide more information on these diagnostics:

Brief explanations of some of the problems detected by these diagnostics can be found in the

*Brief Guide to Stan's Warnings*.Betancourt (2017) provides much more depth on these diagnostics as well as a conceptual introduction to Hamiltonian Monte Carlo in general.

Gabry et al. (2018) and the bayesplot package vignettes demonstrate various visualizations of these diagnostics that can be made in R.

The Stan Development Team
*Stan Modeling Language User's Guide and Reference Manual*.
http://mc-stan.org/.

Betancourt, M. (2017). A conceptual introduction to Hamiltonian Monte Carlo. https://arxiv.org/abs/1701.02434.

Gabry, J., Simpson, D., Vehtari, A., Betancourt, M., and Gelman, A. (2018).
Visualization in Bayesian workflow.
*Journal of the Royal Statistical Society Series A*, accepted for publication.
arXiv preprint: http://arxiv.org/abs/1709.01449.

if (FALSE) { schools <- stan_demo("eight_schools") check_hmc_diagnostics(schools) check_divergences(schools) check_treedepth(schools) check_energy(schools) }