bayespecon.diagnostics.spatial_mcmc_diagnostic¶

bayespecon.diagnostics.spatial_mcmc_diagnostic(model, *, min_ess=1000.0, min_yield_pct=5.0, max_hpdi_drift_pct=5.0, max_r_hat=1.01, extra_params=None, emit_warnings=True)[source]¶

Run MCMC adequacy checks on a fitted Bayesian spatial model.

Implements the practical recommendations of Wolf et al. [2018]: report effective sample size and yield for the spatial dependence parameter, and check that the posterior credible-interval width has stabilised. When any threshold is violated, a UserWarning is emitted (unless emit_warnings=False) describing the failure and pointing to the actionable fix (longer chains or thinning).

Parameters:¶

model : bayespecon model¶

Fitted spatial model exposing inference_data with a posterior group containing rho and/or lam.

min_ess : float, optional¶

Minimum acceptable bulk ESS for monitored parameters. The default of 1000 matches the target effective sample size used in the Wolf et al. (2018) illustrations.

min_yield_pct : float, optional¶

Minimum acceptable yield (ESS / nominal × 100). The default of 5 % is the lower end of the “well-behaved” range reported in Wolf et al. (2018), Table 1.

max_hpdi_drift_pct : float, optional¶

Maximum tolerated relative change in the 95 % HPDI width between the last third and the full post-warmup chain. Large drift indicates the chain has not yet stabilised and terminating now would understate uncertainty (Wolf et al., 2018, §”Impacts of small effective size and trace autocorrelation”).

max_r_hat : float, optional¶

Maximum tolerated \(\hat{R}\). Default 1.01 follows the modern ArviZ recommendation.

extra_params : list of str, optional¶

Additional posterior variables to include in the report (for example, ["beta", "sigma"]). These are reported but do not count toward the adequate flag, which tracks only the spatial dependence parameter(s).

emit_warnings : bool, optional¶

If True (default), each failed check emits a UserWarning. Set to False to inspect the report silently.

Returns:¶

Dataclass with per-parameter ESS, yield, HPDI-drift, and \(\hat{R}\) statistics, plus a list of warnings triggered and an adequate flag.

Return type:¶

SpatialMCMCReport

Raises:¶

• RuntimeError – If model has not been fit yet (inference_data is None).

• ValueError – If the posterior contains neither rho nor lam and no extra_params were requested.

Notes

The diagnostic deliberately monitors only rho / lam by default. Wolf et al. (2018) demonstrate that \(\beta\) typically mixes well in spatial-lag specifications; the spatial dependence parameter is the bottleneck. Spatial impact summaries (direct / indirect / total) inherit rho’s autocorrelation through \((I-\rho W)^{-1}\), so checking rho is a sufficient screen for them as well.

The HPDI-drift check is a lightweight alternative to running multiple long chains and comparing their long-run widths: a converged sampler should produce a stable interval width across the second half of the chain. When drift exceeds max_hpdi_drift_pct, the warning text suggests doubling the number of post-warmup draws.

Examples

>>> from bayespecon import SAR
>>> from bayespecon.diagnostics import spatial_mcmc_diagnostic
>>> model = SAR(y, X, W=W).fit(draws=2000, tune=1000)
>>> report = spatial_mcmc_diagnostic(model)
>>> report.adequate
True

References

[WAArribasBel18]

Levi John Wolf, Luc Anselin, and Daniel Arribas-Bel. Stochastic Efficiency of Bayesian Markov Chain Monte Carlo in Spatial Econometric Models: An Empirical Comparison of Exact Sampling Methods. Geographical Analysis, 50(1):97–119, 2018. URL: https://onlinelibrary.wiley.com/doi/abs/10.1111/gean.12135 (visited on 2026-04-20), doi:10.1111/gean.12135.