# MCMC-diagnostics

##### General MCMC diagnostics

Plots of Rhat statistics, ratios of effective sample size to total sample
size, and autocorrelation of MCMC draws. See the **Plot Descriptions**
section, below, for details. For models fit using the No-U-Turn-Sampler, see
also MCMC-nuts for additional MCMC diagnostic plots.

##### Usage

`mcmc_rhat(rhat, ..., size = NULL)`mcmc_rhat_hist(rhat, ..., binwidth = NULL, breaks = NULL)

mcmc_rhat_data(rhat, ...)

mcmc_neff(ratio, ..., size = NULL)

mcmc_neff_hist(ratio, ..., binwidth = NULL, breaks = NULL)

mcmc_neff_data(ratio, ...)

mcmc_acf(x, pars = character(), regex_pars = character(),
facet_args = list(), ..., lags = 20, size = NULL)

mcmc_acf_bar(x, pars = character(), regex_pars = character(),
facet_args = list(), ..., lags = 20)

##### Arguments

- rhat
A vector of

`Rhat`

estimates.- ...
Currently ignored.

- size
An optional value to override

`geom_point`

's default size (for`mcmc_rhat`

,`mcmc_neff`

) or`geom_line`

's default size (for`mcmc_acf`

).- binwidth
Passed to

`geom_histogram`

to override the default binwidth.- breaks
Passed to

`geom_histogram`

as an alternative to`binwidth`

.- ratio
A vector of

*ratios*of effective sample size estimates to total sample size. See`neff_ratio`

.- x
A 3-D array, matrix, list of matrices, or data frame of MCMC draws. The MCMC-overview page provides details on how to specify each these allowed inputs.

- pars
An optional character vector of parameter names. If neither

`pars`

nor`regex_pars`

is specified then the default is to use*all*parameters.- regex_pars
An optional regular expression to use for parameter selection. Can be specified instead of

`pars`

or in addition to`pars`

.- facet_args
A named list of arguments (other than

`facets`

) passed to`facet_wrap`

or`facet_grid`

to control faceting.- lags
The number of lags to show in the autocorrelation plot.

##### Value

A ggplot object that can be further customized using the
ggplot2 package. The `_data`

functions return the data that
would have been drawn by the plotting function.

##### Plot Descriptions

`mcmc_rhat, mcmc_rhat_hist`

Rhat values as either points or a histogram. Values are colored using different shades (lighter is better). The chosen thresholds are somewhat arbitrary, but can be useful guidelines in practice.

*light*: below 1.05 (good)*mid*: between 1.05 and 1.1 (ok)*dark*: above 1.1 (too high)

`mcmc_neff, mcmc_neff_hist`

Ratios of effective sample size to total sample size as either points or a histogram. Values are colored using different shades (lighter is better). The chosen thresholds are somewhat arbitrary, but can be useful guidelines in practice.

*light*: between 0.5 and 1 (high)*mid*: between 0.1 and 0.5 (good)*dark*: below 0.1 (low)

`mcmc_acf`

Grid of autocorrelation plots by chain and parameter. The

`lags`

argument gives the maximum number of lags at which to calculate the autocorrelation function.`mcmc_acf`

is a line plot whereas`mcmc_acf_bar`

is a barplot.

##### References

Stan Development Team. (2016). *Stan Modeling Language Users
Guide and Reference Manual.* http://mc-stan.org/documentation/

Gelman, A. and Rubin, D. B. (1992). Inference from iterative
simulation using multiple sequences. *Statistical Science*. 7(4),
457--472.

##### See Also

The

*Visual MCMC Diagnostics*vignette.MCMC-nuts for additional MCMC diagnostic plots for models fit using the No-U-Turn-Sampler.

Other MCMC: `MCMC-combos`

,
`MCMC-distributions`

,
`MCMC-intervals`

, `MCMC-nuts`

,
`MCMC-overview`

, `MCMC-parcoord`

,
`MCMC-recover`

,
`MCMC-scatterplots`

,
`MCMC-traces`

##### Examples

```
# NOT RUN {
# autocorrelation
x <- example_mcmc_draws()
dim(x)
dimnames(x)
color_scheme_set("green")
mcmc_acf(x, pars = c("alpha", "beta[1]"))
# }
# NOT RUN {
color_scheme_set("pink")
(p <- mcmc_acf_bar(x, pars = c("alpha", "beta[1]")))
# add horiztonal dashed line at 0.5
p + hline_at(0.5, linetype = 2, size = 0.15, color = "gray")
# }
# NOT RUN {
# fake rhat values to use for demonstration
rhat <- c(runif(100, 1, 1.15))
mcmc_rhat_hist(rhat)
mcmc_rhat(rhat)
# lollipops
color_scheme_set("purple")
mcmc_rhat(rhat[1:10], size = 5)
color_scheme_set("blue")
mcmc_rhat(runif(1000, 1, 1.07))
mcmc_rhat(runif(1000, 1, 1.3)) + legend_move("top") # add legend above plot
# fake neff ratio values to use for demonstration
ratio <- c(runif(100, 0, 1))
mcmc_neff_hist(ratio)
mcmc_neff(ratio)
# }
# NOT RUN {
# Example using rstanarm model (requires rstanarm package)
library(rstanarm)
# intentionally use small 'iter' so there are some
# problems with rhat and neff for demonstration
fit <- stan_glm(mpg ~ ., data = mtcars, iter = 50)
rhats <- rhat(fit)
ratios <- neff_ratio(fit)
mcmc_rhat(rhats)
mcmc_neff(ratios, size = 3)
# there's a small enough number of parameters in the
# model that we can display their names on the y-axis
mcmc_neff(ratios) + yaxis_text(hjust = 1)
# can also look at autocorrelation
draws <- as.array(fit)
mcmc_acf(draws, pars = c("wt", "cyl"), lags = 10)
# increase number of iterations and plots look much better
fit2 <- update(fit, iter = 500)
mcmc_rhat(rhat(fit2))
mcmc_neff(neff_ratio(fit2))
mcmc_acf(as.array(fit2), pars = c("wt", "cyl"), lags = 10)
# }
# NOT RUN {
# }
```

*Documentation reproduced from package bayesplot, version 1.6.0, License: GPL (>= 3)*