# convergence: Computes convergence diagnostics for a 'mids' object In mice: Multivariate Imputation by Chained Equations

 convergence R Documentation

## Computes convergence diagnostics for a `mids` object

### Description

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.

### 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.

### Value

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

### 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

`mice`, `mids`

### Examples

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

mice documentation built on Nov. 19, 2022, 5:06 p.m.