(calibration_markov_chain_diagnostics_ESS)=
# Thinning the chains with ESS

Once convergence of the chains has been assessed using the trace plot (see [](#calibration_markov_chain_diagnostics_draw_trace)), 
the acceptance ratio plot (see [](#calibration_markov_chain_diagnostics_draw_ratio)), and 
the Gelman–Rubin diagnostic (see [](#calibration_markov_chain_diagnostics_gelman_rubin)), 
the next step is to evaluate the autocorrelation of the samples. If samples are highly 
correlated, the posterior distribution may not be properly explored (e.g., chains could 
remain trapped in a mode). 

A common way to assess this is to compute the Effective Sample Size (ESS), which estimates 
how many samples can effectively be considered as independent among the available ones. ESS 
thus indirectly indicates the appropriate lag (the number of iterations to skip to obtain 
approximately uncorrelated samples). More details are provided in {{metho}}.

The method `diagESS` has the following prototype:

````{only} cpp
```cpp
std::unordered_map<string, vector<int>> diagESS();
```
````

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

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

````{only} cpp
```cpp
std::unordered_map<string, vector<int>> ESS_values = cal->diagESS();  
ESS_values["hl"][0]; // To extract the ESS statistic for parameter hl computed on the first chain
```
````

````{only} py
```python
ESS_values = cal.diagESS()
ESS_values["hl"][0] # To extract the ESS statistic for parameter hl computed on the first chain
```
````

The returned object `ESS_values` is an unordered map where each parameter name (e.g., `hl`) 
is associated with a vector of ESS values, one per chain. The results are also printed in the 
console (see [](#use_cases_macro_calibration_mcmc_console)).

In this example, the ESS diagnostic confirms that each parameter has several hundred (at least 200) 
effectively uncorrelated samples. It is therefore recommended to set the lag to 1 using `setLag` 
method (see [](#calibration_markov_chain_diagnostics)), which indicates that the samples are 
sufficiently uncorrelated.

If the ESS is too small, it may be necessary to run additional 
iterations (see [](#calibration_markov_chain_run)) or to adjust the initial standard deviation 
of the proposal distribution, which may be too small, causing the chain to move too slowly 
(see [](#calibration_markov_chain_mcmc_properties_init_process)).