diff --git a/src/reference-manual/analysis.qmd b/src/reference-manual/analysis.qmd index 3de6e944e..8f0b1e2e3 100644 --- a/src/reference-manual/analysis.qmd +++ b/src/reference-manual/analysis.qmd @@ -327,6 +327,32 @@ making the sample of interest more Gaussian and hence the $\hat{R}$ statistic more accurate. +#### Sampler diagnostics {-} + +The convergence statements above are about functions of the +parameters. The sampler diagnostics `accept_stat__`, `treedepth__`, +`n_leapfrog__`, and `divergent__` also depend on the step size and the +metric. Each chain adapts its own step size and metric during warmup +and keeps them fixed during sampling, so their values can differ +between chains. For example, a smaller step size usually gives a +higher acceptance statistic, a larger tree depth, and more leapfrog +steps. The stationary distribution of these sampler diagnostics can +therefore differ between chains, whereas $\hat{R}$ and the multi-chain +effective sample size assume the same stationary distribution in all +chains. The column `stepsize__` gives the step size of each +iteration, which is constant in each chain unless step size jitter is +on. + +The step size and the metric change the proposals of the sampler but +not the target distribution. The parameters and `lp__`, a function of +the parameters, have the same stationary distribution in all chains. +The column `energy__` is the value of the Hamiltonian at the draw: the +negative of `lp__` plus the kinetic energy. Because Stan draws a new +momentum in each iteration, the kinetic energy has the same +distribution for any metric. The statistic $\hat{R}$ and the effective +sample size thus apply to the parameters, `lp__`, and `energy__`. + + #### Final words on convergence monitoring {-} "Convergence" is a global property and holds for all integrable