(calibration_markov_chain_diagnostics_gelman_rubin)=
# Checking for convergence with the Gelman–Rubin diagnostic

Once the trace and acceptance ratio plots have been analysed, and an initial burn-in value has 
been chosen, the Gelman–Rubin diagnostic can be used to verify the convergence of the chains. 
This diagnostic compares the intra- and inter-chain variances (see {{metho}} for more details). 

The method `diagGelmanRubin` has the following prototype:

````{only} cpp
```cpp
std::unordered_map<string, double> diagGelmanRubin();
```
````

````{only} py
```python
diagGelmanRubin()
```
````

This method takes no arguments, as it is called directly from the `TCalibration` object. For example, in [](#use_cases_macro_calibration_mcmc), the Gelman–Rubin diagnostic is computed with:

````{only} cpp
```cpp
std::unordered_map<string, double> GelmanRubin_values = cal->diagGelmanRubin();
GelmanRubin_values["hl"]; // To extract the Gelman-Rubin statistic for parameter hl
```
````

````{only} py
```python
GelmanRubin_values = cal.diagGelmanRubin()
GelmanRubin_values["hl"] # To extract the Gelman-Rubin statistic for parameter hl
```
````

The returned object `GelmanRubin_values` is an unordered map where each parameter name (e.g., 
`hl`) is associated with its Gelman–Rubin statistic value. The results are also printed 
in the console (see [](#use_cases_macro_calibration_mcmc_console)), accompanied by a short 
generic commentary interpreting the statistic.

In this example, the Gelman–Rubin diagnostic confirms good convergence of the chains 
(and thus the suitability of the chosen burn-in value). In other cases, where the statistics 
indicate poorer convergence, it may be necessary to run additional iterations (see 
[](#calibration_markov_chain_run)) or to adjust the burn-in value (see 
[](#calibration_markov_chain_diagnostics)).