Getting Started with neighbayes

This notebook walks through a complete spatial econometric workflow:

  1. Simulate spatial data from a known DGP

  2. Fit a baseline OLS model

  3. Run Bayesian LM diagnostics to test for spatial dependence

  4. Use the decision tree to select a better model

  5. Fit the recommended SAR model

  6. Compute direct, indirect, and total impacts

  7. 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')
../_images/2ed08a39b78bc743503466cfc1d26d6de39e54eae6d1bfa989cb43b4dff76577.png
gdf.plot("y").set_title("y")
Text(0.5, 1.0, 'y')
../_images/ec468e4fcf9fb751236453cba2ab557ae290735b7e503dbf24de3f660e657a15.png

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.

\[ y = X\beta + \varepsilon, \quad \varepsilon \sim \mathcal{N}(0, \sigma^2 I) \]
# 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>
../_images/b979c10157b959ff194bfcd6e585c011eec21a2e68563ae1a2efbae3e790530b.png
az.plot_trace_dist(ols.inference_data)
<arviz_plots.plot_collection.PlotCollection at 0x7c87a22c7610>
../_images/2ddbe7324e2bac63f4f250159e52bc329115b9e4bde458587c80168b556a0986.png

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)
../_images/60e93007e8c002ca6480d0fd4ffe547411ba929a8f6ca3a7a2ce6524e2e78eff.svg

If the diagnostics suggest spatial dependence, we fit a Spatial Autoregressive (SAR) model:

\[ y = \rho W y + X\beta + \varepsilon, \quad \varepsilon \sim \mathcal{N}(0, \sigma^2 I) \]

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>
../_images/faad30b0ce97b9c1eb0dceb000d1a7656ee26df75b66f32f6eeb84f8e2e6ac18.png

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