R: Check HMC diagnostics after sampling

check_hmc_diagnostics {rstan} | R Documentation

## Check HMC diagnostics after sampling

### Description

These functions print summaries of important HMC diagnostics or extract those diagnostics from a `stanfit` object. See the Details section, below.

### Usage

    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)

### Arguments

`object` | A stanfit object.

### Details

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.

### References

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.

### Examples

    ## Not run:
    schools <- stan_demo("eight_schools")
    check_hmc_diagnostics(schools)
    check_divergences(schools)
    check_treedepth(schools)
    check_energy(schools)

    ## End(Not run)

[Package rstan version 2.21.2 Index]