Getting Started with neighbayes¶
This notebook walks through a complete spatial econometric workflow:
Simulate spatial data from a known DGP
Fit a baseline OLS model
Run Bayesian LM diagnostics to test for spatial dependence
Use the decision tree to select a better model
Fit the recommended SAR model
Compute direct, indirect, and total impacts
Peek at the underlying PyMC model for customization
import libpysal
from neighbayes.dgp import simulate_sar
gdf = simulate_sar(n_side=20, beta=[1, 0.4, 2.5], rho=0.6, create_gdf=True)
/home/runner/micromamba/envs/test/lib/python3.14/site-packages/tqdm/auto.py:21: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html
from .autonotebook import tqdm as notebook_tqdm
gdf
| y | X_0 | X_1 | X_2 | geometry | |
|---|---|---|---|---|---|
| 0 | 5.845585 | 1.0 | 1.102571 | 1.115944 | POLYGON ((1 0, 1 1, 0 1, 0 0, 1 0)) |
| 1 | 3.973883 | 1.0 | -0.090329 | -0.003309 | POLYGON ((2 0, 2 1, 1 1, 1 0, 2 0)) |
| 2 | 4.391186 | 1.0 | -0.673907 | 0.001611 | POLYGON ((3 0, 3 1, 2 1, 2 0, 3 0)) |
| 3 | 2.794342 | 1.0 | -0.303613 | 0.543797 | POLYGON ((4 0, 4 1, 3 1, 3 0, 4 0)) |
| 4 | -1.093209 | 1.0 | -0.757628 | -1.384579 | POLYGON ((5 0, 5 1, 4 1, 4 0, 5 0)) |
| ... | ... | ... | ... | ... | ... |
| 395 | 3.389852 | 1.0 | 0.432607 | -0.425744 | POLYGON ((16 19, 16 20, 15 20, 15 19, 16 19)) |
| 396 | 2.667012 | 1.0 | 1.660793 | -0.709531 | POLYGON ((17 19, 17 20, 16 20, 16 19, 17 19)) |
| 397 | 4.676155 | 1.0 | 0.036140 | 1.038467 | POLYGON ((18 19, 18 20, 17 20, 17 19, 18 19)) |
| 398 | 3.683431 | 1.0 | -1.294221 | 0.800315 | POLYGON ((19 19, 19 20, 18 20, 18 19, 19 19)) |
| 399 | 4.960455 | 1.0 | -0.395254 | 0.276895 | POLYGON ((20 19, 20 20, 19 20, 19 19, 20 19)) |
400 rows × 5 columns
gdf.plot("X_1").set_title("X1")
Text(0.5, 1.0, 'X1')
gdf.plot("y").set_title("y")
Text(0.5, 1.0, 'y')
1. Create a Spatial Weights Matrix¶
Spatial econometric models require a spatial weights matrix \(W\) that encodes the spatial relationships between observations. Here we use Rook contiguity (regions that share a boundary or vertex are neighbors).
G = libpysal.graph.Graph.build_contiguity(gdf, rook=False).transform("r")
2. Fit a Baseline OLS Model¶
We start with a non-spatial OLS regression to establish a baseline.
# remove the intercept since we have one (-1)
form = "y ~ -1 + X_0 + X_1 + X_2"
from neighbayes.models import OLS
ols = OLS(formula=form, W=G, data=gdf)
ols.fit(draws=1000, tune=500, chains=2, random_seed=42)
ols.summary()
Initializing NUTS using jitter+adapt_diag...
Multiprocess sampling (2 chains in 2 jobs)
NUTS: [beta, sigma2]
Sampling 2 chains for 500 tune and 1_000 draw iterations (1_000 + 2_000 draws total) took 3 seconds.
We recommend running at least 4 chains for robust computation of convergence diagnostics
/home/runner/micromamba/envs/test/lib/python3.14/site-packages/rich/live.py:260: UserWarning: install "ipywidgets"
for Jupyter support
warnings.warn('install "ipywidgets" for Jupyter support')
| mean | sd | eti89_lb | eti89_ub | ess_bulk | ess_tail | r_hat | mcse_mean | mcse_sd | |
|---|---|---|---|---|---|---|---|---|---|
| X_0 | 2.759926 | 0.073447 | 2.641197 | 2.881985 | 1952.085961 | 1478.549578 | 0.999306 | 0.001663 | 0.001636 |
| X_1 | 0.357214 | 0.073749 | 0.240488 | 0.474003 | 1776.151695 | 1503.497224 | 0.999942 | 0.001757 | 0.001549 |
| X_2 | 2.760595 | 0.070051 | 2.650544 | 2.876937 | 2497.827643 | 1355.987108 | 0.999725 | 0.0014 | 0.001436 |
| sigma2 | 2.229 | 0.165 | 2 | 2.5 | 1685 | 1203 | 1.00 | 0.004 | 0.0046 |
| sigma | 1.492 | 0.055 | 1.4 | 1.6 | 1685 | 1203 | 1.00 | 0.0013 | 0.0015 |
Notice all the estimated beta parameters are biased upward.
Use arviz to inspect fit¶
the fit method attaches an inference_data object to each model that can be used directly with arviz functions
import arviz as az
az.plot_forest(ols.inference_data)
<arviz_plots.plot_collection.PlotCollection at 0x7c87a23a6510>
az.plot_trace_dist(ols.inference_data)
<arviz_plots.plot_collection.PlotCollection at 0x7c87a22c7610>
3. Run Bayesian LM Diagnostics¶
The spatial_diagnostics() method runs a battery of Bayesian LM tests (Doğan, Taşpınar & Bera 2021) that check whether spatial dependence is present in the residuals.
LM-Lag: Tests \(H_0: \rho = 0\) (no spatial lag on \(y\))
LM-Error: Tests \(H_0: \lambda = 0\) (no spatial error correlation)
LM-WX: Tests \(H_0: \gamma = 0\) (no spatially lagged covariates)
LM-SDM-Joint: Joint test for \(\rho = 0\) and \(\gamma = 0\)
Robust-LM-Lag / Robust-LM-Error: each robust to the other term
diag = ols.spatial_diagnostics()
diag
| statistic | median | df | p_value | ci_lower | ci_upper | |
|---|---|---|---|---|---|---|
| test | ||||||
| LM-Lag | 321.695600 | 323.304623 | 1 | 0.000000 | 239.594549 | 431.674086 |
| LM-Error | 175.666160 | 179.079759 | 1 | 0.000000 | 120.703090 | 256.275995 |
| LM-WX | 153.519052 | 154.715711 | 2 | 0.000000 | 114.471471 | 204.823934 |
| LM-SDM-Joint | 329.185212 | 330.501979 | 3 | 0.000000 | 244.347945 | 442.180625 |
| LM-SLX-Error-Joint | 329.185212 | 333.256130 | 3 | 0.000000 | 241.948720 | 456.254129 |
| Robust-LM-Lag | 153.344345 | 152.547507 | 1 | 0.000000 | 109.621901 | 207.592525 |
| Robust-LM-Error | 7.314906 | 8.011666 | 1 | 0.006838 | 1.043090 | 20.521482 |
| Robust-LM-WX | 7.489613 | 7.495988 | 2 | 0.023640 | 4.036442 | 12.264105 |
4. Model Selection Decision Tree¶
The spatial_diagnostics_decision() method reads the tests above by the rule of Anselin et al. (1996) and recommends the next model to fit: no plain rejection keeps OLS, a lone plain rejection adds its term, and when both plain tests reject the robust pair picks the term.
decision = ols.spatial_diagnostics_decision(alpha=0.05, format="ascii")
print(decision)
LM-Lag * (p=0.0000, alpha=0.05)
├── <sig> LM-Error * (p=0.0000, alpha=0.05)
│ ├── <sig> Robust-LM-Lag * (p=0.0000, alpha=0.05)
│ │ ├── <sig> Robust-LM-Error * (p=0.0068, alpha=0.05)
│ │ │ ├── <sig> Robust-LM-Lag p <= Robust-LM-Error p *
│ │ │ │ ├── <true> [SAR] * ← SELECTED
│ │ │ │ └── <false> [SEM]
│ │ │ └── <not sig> [SAR]
│ │ └── <not sig> Robust-LM-Error
│ │ ├── <sig> [SEM]
│ │ └── <not sig> Robust-LM-Lag p <= Robust-LM-Error p
│ │ ├── <true> [SAR]
│ │ └── <false> [SEM]
│ └── <not sig> LM-WX
│ ├── <sig> Robust-LM-WX
│ │ ├── <sig> [SLX]
│ │ └── <not sig> LM-Error (the lag robust to WX) p <= Robust-LM-WX p
│ │ ├── <true> [SAR]
│ │ └── <false> [SLX]
│ └── <not sig> [SAR]
└── <not sig> LM-Error
├── <sig> LM-WX
│ ├── <sig> LM-Error p <= LM-WX p
│ │ ├── <true> [SEM]
│ │ └── <false> [SLX]
│ └── <not sig> [SEM]
└── <not sig> LM-WX
├── <sig> [SLX]
└── <not sig> [OLS]
ols.spatial_diagnostics_decision(alpha=0.05)
5. Fit the Recommended SAR Model¶
If the diagnostics suggest spatial dependence, we fit a Spatial Autoregressive (SAR) model:
The likelihood includes the Jacobian \(\log|I - \rho W|\) so that posterior inference on \(\rho\) is exact.
from neighbayes.models import SAR
sar = SAR(formula=form, W=G, data=gdf)
sar.fit(draws=2000, tune=100, chains=4, random_seed=42)
sar.summary()
Gibbs sampling (sar): 4 chains for 100 tune and 2,000 draw iterations (4 x 2,100 = 8,400 draws total)
/home/runner/micromamba/envs/test/lib/python3.14/site-packages/rich/live.py:260: UserWarning: install "ipywidgets"
for Jupyter support
warnings.warn('install "ipywidgets" for Jupyter support')
Sampling took 2s (4,305 draws/s)
| mean | sd | eti89_lb | eti89_ub | ess_bulk | ess_tail | r_hat | mcse_mean | mcse_sd | |
|---|---|---|---|---|---|---|---|---|---|
| rho | 0.5988 | 0.0308 | 0.55 | 0.65 | 8061 | 5972 | 1.00 | 0.00034 | 0.00036 |
| sigma | 1.0634 | 0.0378 | 1 | 1.1 | 7291 | 7656 | 1.00 | 0.00044 | 0.00031 |
| sigma2 | 1.132 | 0.081 | 1 | 1.3 | 7291 | 7656 | 1.00 | 0.00094 | 0.00067 |
| X_0 | 1.023243 | 0.105391 | 0.855979 | 1.195526 | 8285.763052 | 7030.659814 | 1.000228 | 0.001157 | 0.001045 |
| X_1 | 0.334576 | 0.053416 | 0.248458 | 0.41976 | 7837.565545 | 7879.254834 | 1.000275 | 0.000603 | 0.000405 |
| X_2 | 2.571054 | 0.053729 | 2.485979 | 2.656299 | 7845.967487 | 7542.239006 | 0.999874 | 0.000607 | 0.000423 |
az.plot_trace_dist(sar.inference_data)
<arviz_plots.plot_collection.PlotCollection at 0x7c878032ead0>
6. Compute Spatial Effects¶
For the SAR model, a change in \(X\) propagates through the spatial multiplier \((I - \rho W)^{-1}\). The effects decompose into:
Direct: Effect of \(X_i\) on \(y_i\) (own-region)
Indirect: Effect of \(X_j\) on \(y_i\) for \(j \neq i\) (spillover)
Total: Direct + Indirect
effects = sar.impacts()
effects
| direct | direct_ci_lower | direct_ci_upper | direct_pvalue | indirect | indirect_ci_lower | indirect_ci_upper | indirect_pvalue | total | total_ci_lower | total_ci_upper | total_pvalue | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| variable | ||||||||||||
| X_1 | 0.360048 | 0.249210 | 0.470344 | 0.0 | 0.478625 | 0.306323 | 0.681864 | 0.0 | 0.838673 | 0.564927 | 1.134893 | 0.0 |
| X_2 | 2.766835 | 2.652677 | 2.884306 | 0.0 | 3.678728 | 2.852002 | 4.693141 | 0.0 | 6.445564 | 5.559798 | 7.530447 | 0.0 |