Computes convergence diagnostics for a mids object

Takes an object of class mids, computes the autocorrelation and/or potential scale reduction factor, and returns a data.frame with the specified diagnostic(s) per iteration.

Usage

convergence(data, diagnostic = "all", parameter = "mean", ...)

Arguments

data: An object of class mids as created by the function mice().
diagnostic: A keyword. One of the following keywords: "ac", "all", "gr" and "psrf". See the Details section for the interpretation. The default is diagnostic = "all" which returns both the autocorrelation and potential scale reduction factor per iteration.
parameter: A keyword. One of the following keywords: "mean" or "sd" to evaluate chain means or chain standard deviations, respectively.
...: Additional arguments. Not used.

Value

A data.frame with the autocorrelation and/or potential scale reduction factor per iteration of the MICE algorithm.

Details

The argument diagnostic can be length-1 character, which is matched to one of the following keywords:

"all": computes both the lag-1 autocorrelation as well as the potential scale reduction factor (cf. Vehtari et al., 2021) per iteration of the MICE algorithm;
"ac": computes only the autocorrelation per iteration;
"psrf": computes only the potential scale reduction factor per iteration;
"gr": same as psrf, the potential scale reduction factor is colloquially called the Gelman-Rubin diagnostic.

In the unlikely event of perfect convergence, the autocorrelation equals zero and the potential scale reduction factor equals one. To interpret the convergence diagnostic(s) in the output of the function, it is recommended to plot the diagnostics (ac and/or psrf) against the iteration number (.it) per imputed variable (vrb). A persistently decreasing trend across iterations indicates potential non-convergence.

References

Vehtari, A., Gelman, A., Simpson, D., Carpenter, B., & Burkner, P.-C. (2021). Rank-Normalization, Folding, and Localization: An Improved R for Assessing Convergence of MCMC. Bayesian Analysis, 1(1), 1-38. https://doi.org/10.1214/20-BA1221

Examples

if (FALSE) {
# obtain imputed data set
imp <- mice(nhanes2, print = FALSE)
# compute convergence diagnostics
convergence(imp)
}

Computes convergence diagnostics for a `mids` object