Spatial panel models: a walkthrough

By the end of this lesson you will have built a balanced panel, fitted the fixed-effects and random-effects families to it, compared them, and used the panel specification tests to choose the spatial terms the data support.

It assumes you have been through the cross-sectional walkthrough; the models here are its panel counterparts. Work through the cells in order.

A panel stacks the same units across periods, which adds two things the cross-sectional models did not have: unit effects \(a_i\) and time effects \(\tau_t\). The effects argument controls which are included.

The equations for each class are in Supported Models.

import arviz as az
import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
from libpysal.graph import Graph

from neighbayes import dgp
from neighbayes.models import OLS, SAR, SDEM, SDM, SEM

az.style.use("arviz-variat")

Build the panel

For pedagogy, we generate synthetic panel data from the neighbayes.dgp module on a regular polygon grid and then assemble a formula-ready DataFrame.

# Generate base geometry via cross-sectional DGP, then simulate panel data via panel DGP.
rng = np.random.default_rng(2026)
xcols = ["poverty", "rev_rating", "num_spots", "crowded"]
ycol = "price_pp"

base_gdf = dgp.simulate_sar(
    n_side=20, seed=2026, create_gdf=True, geometry_type="polygon"
)
W = Graph.build_contiguity(base_gdf, rook=False).transform("r")
N = len(base_gdf)
T = 4
beta = np.array([1.5, -0.8, 0.6, 0.4, -0.5], dtype=float)

panel_sim = dgp.simulate_sar(
    N=N,
    T=T,
    rho=0.35,
    beta=beta,
    sigma=1.0,
    rng=rng,
    W=W,
    unit_effects="fixed",
    unit_effect_sd=0.5,
)

panel = pd.DataFrame(
    {
        "unit": panel_sim["unit"],
        "time": panel_sim["time"],
        ycol: panel_sim["y"],
    }
)
for j, name in enumerate(xcols, start=1):
    panel[name] = panel_sim["X"][:, j]
/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

A helper to keep the fits short

def fit_panel_model(
    model_cls, formula, data, W, draws=2000, tune=1000, chains=2, seed=42, **design
):
    """Fit a panel model and return (model, summary, effects_df).

    Uses minimal MCMC settings for pedagogical demonstration.
    Increase draws/tune for real analyses.
    """
    m = model_cls(
        formula=formula,
        data=data,
        W=W,
        unit_col="unit",
        time_col="time",
        **design,
    )
    m.fit(
        draws=draws,
        tune=tune,
        chains=chains,
        random_seed=seed,
        progressbar=True,
    )
    summary = m.summary(round_to=3)
    effects_df = pd.DataFrame(m.impacts())
    return m, summary, effects_df


def diagnostics_table(idata, var_names):
    """Show key MCMC diagnostics for the given parameters."""
    cols = ["mean", "sd", "ess_bulk", "ess_tail", "r_hat"]
    return az.summary(idata, var_names=var_names, round_to=3)[cols]


def show_trace(idata, var_names, title):
    """Plot trace plots for the given parameters."""
    az.plot_trace_dist(idata, var_names=var_names)
    plt.suptitle(title, y=1.02)
    plt.tight_layout()
    plt.show()

Start without any spatial term

formula = "price_pp ~ poverty + rev_rating + num_spots + crowded"
ols_panel, summary_ols, effects_ols = fit_panel_model(
    OLS, formula, panel, W, unit_effects="fixed", time_effects=True
)
display(summary_ols)
display(effects_ols)
display(diagnostics_table(ols_panel.inference_data, ["beta", "sigma"]))
show_trace(ols_panel.inference_data, ["sigma"], "OLS, two-way fixed effects: trace")
Initializing NUTS using jitter+adapt_diag...
Multiprocess sampling (2 chains in 2 jobs)
NUTS: [beta, sigma2]
Sampling 2 chains for 1_000 tune and 2_000 draw iterations (2_000 + 4_000 draws total) took 3 seconds.
We recommend running at least 4 chains for robust computation of convergence diagnostics
/tmp/ipykernel_9091/4084804720.py:39: UserWarning: The figure layout has changed to tight
  plt.tight_layout()
/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
poverty -0.753 0.029 -0.799 -0.706 5146.424 3241.347 1.000 0.000 0.000
rev_rating 0.596 0.030 0.548 0.644 5144.201 3061.237 1.000 0.000 0.000
num_spots 0.453 0.030 0.405 0.502 4937.642 3021.793 1.000 0.000 0.000
crowded -0.538 0.029 -0.584 -0.493 5460.414 3128.393 1.000 0.000 0.000
sigma2 1.054 0.044 0.986 1.125 4319.773 2998.505 1.001 0.001 0.001
sigma 1.026 0.021 0.993 1.061 4319.773 2998.505 1.001 0.000 0.000
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
poverty -0.752649 -0.808878 -0.695722 0.0 0.0 0.0 0.0 0.0 -0.752649 -0.808878 -0.695722 0.0
rev_rating 0.596407 0.537113 0.653747 0.0 0.0 0.0 0.0 0.0 0.596407 0.537113 0.653747 0.0
num_spots 0.453416 0.393250 0.513407 0.0 0.0 0.0 0.0 0.0 0.453416 0.393250 0.513407 0.0
crowded -0.538292 -0.593885 -0.482205 0.0 0.0 0.0 0.0 0.0 -0.538292 -0.593885 -0.482205 0.0
mean sd ess_bulk ess_tail r_hat
beta[poverty] -0.753 0.029 5146.424 3241.347 1.000
beta[rev_rating] 0.596 0.030 5144.201 3061.237 1.000
beta[num_spots] 0.453 0.030 4937.642 3021.793 1.000
beta[crowded] -0.538 0.029 5460.414 3128.393 1.000
sigma 1.026 0.021 4319.773 2998.505 1.001
../_images/ff0e7eda80b4fbb991b79d917d8b8afbdbc76c3a6c0013be7dbaf1ab6292a390.png

Add a spatial lag on the outcome

sar_panel, summary_sar, effects_sar = fit_panel_model(
    SAR, formula, panel, W, unit_effects="fixed", time_effects=True
)
display(summary_sar)
display(effects_sar)
display(diagnostics_table(sar_panel.inference_data, ["rho", "beta", "sigma"]))
show_trace(
    sar_panel.inference_data, ["rho", "sigma"], "SAR, two-way fixed effects: trace"
)
Gibbs sampling (sar): 2 chains for 1,000 tune and 2,000 draw iterations (2 x 3,000 = 6,000 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 (3,208 draws/s)
mean sd eti89_lb eti89_ub ess_bulk ess_tail r_hat mcse_mean mcse_sd
rho 0.303 0.037 0.244 0.362 4128.046 2941.614 1.000 0.001 0.001
sigma 0.992 0.020 0.960 1.026 3530.036 3616.713 1.000 0.000 0.000
sigma2 0.985 0.041 0.921 1.052 3530.036 3616.713 1.000 0.001 0.000
poverty -0.753 0.029 -0.799 -0.706 4045.926 3877.529 1.001 0.000 0.000
rev_rating 0.583 0.029 0.537 0.629 4114.031 3967.458 1.000 0.000 0.000
num_spots 0.449 0.030 0.402 0.496 3919.654 3741.270 1.000 0.000 0.000
crowded -0.526 0.028 -0.569 -0.480 4104.054 3875.785 1.000 0.000 0.000
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
poverty -0.763838 -0.821304 -0.705877 0.0 -0.318541 -0.434341 -0.213726 0.0 -1.082379 -1.228900 -0.949123 0.0
rev_rating 0.591966 0.536176 0.648355 0.0 0.246746 0.166032 0.335478 0.0 0.838711 0.727284 0.959190 0.0
num_spots 0.455488 0.396960 0.515855 0.0 0.189872 0.127004 0.262877 0.0 0.645360 0.544333 0.754890 0.0
crowded -0.533414 -0.587766 -0.478410 0.0 -0.222288 -0.303142 -0.150861 0.0 -0.755702 -0.867996 -0.652710 0.0
mean sd ess_bulk ess_tail r_hat
rho 0.303 0.037 4128.046 2941.614 1.000
beta[poverty] -0.753 0.029 4045.926 3877.529 1.001
beta[rev_rating] 0.583 0.029 4114.031 3967.458 1.000
beta[num_spots] 0.449 0.030 3919.654 3741.270 1.000
beta[crowded] -0.526 0.028 4104.054 3875.785 1.000
sigma 0.992 0.020 3530.036 3616.713 1.000
/tmp/ipykernel_9091/4084804720.py:39: UserWarning: The figure layout has changed to tight
  plt.tight_layout()
../_images/3d660c61daf9196ff57cd98c2960da5071e6bc816d4cf0e6709509677a7a7b3f.png

Try spatial structure in the errors instead

sem_panel, summary_sem, effects_sem = fit_panel_model(
    SEM, formula, panel, W, unit_effects="fixed", time_effects=True
)
display(summary_sem)
display(effects_sem)
display(diagnostics_table(sem_panel.inference_data, ["lam", "beta", "sigma"]))
show_trace(
    sem_panel.inference_data, ["lam", "sigma"], "SEM, two-way fixed effects: trace"
)
Gibbs sampling (sem): 2 chains for 1,000 tune and 2,000 draw iterations (2 x 3,000 = 6,000 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 (3,090 draws/s)
mean sd eti89_lb eti89_ub ess_bulk ess_tail r_hat mcse_mean mcse_sd
lam 0.345 0.047 0.270 0.420 3895.287 2628.273 1.0 0.001 0.001
sigma 0.996 0.020 0.963 1.029 3445.294 3650.738 1.0 0.000 0.000
sigma2 0.992 0.041 0.928 1.059 3445.294 3650.738 1.0 0.001 0.000
poverty -0.745 0.029 -0.790 -0.699 4049.175 3710.660 1.0 0.000 0.000
rev_rating 0.576 0.029 0.530 0.622 4081.620 3988.041 1.0 0.000 0.000
num_spots 0.443 0.029 0.396 0.489 3919.668 3667.374 1.0 0.000 0.000
crowded -0.519 0.028 -0.562 -0.474 4092.137 3914.557 1.0 0.000 0.000
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
poverty -0.744559 -0.800803 -0.689103 0.0 0.0 0.0 0.0 0.0 -0.744559 -0.800803 -0.689103 0.0
rev_rating 0.575939 0.520599 0.632185 0.0 0.0 0.0 0.0 0.0 0.575939 0.520599 0.632185 0.0
num_spots 0.443124 0.386502 0.502108 0.0 0.0 0.0 0.0 0.0 0.443124 0.386502 0.502108 0.0
crowded -0.518565 -0.572012 -0.464581 0.0 0.0 0.0 0.0 0.0 -0.518565 -0.572012 -0.464581 0.0
mean sd ess_bulk ess_tail r_hat
lam 0.345 0.047 3895.287 2628.273 1.0
beta[poverty] -0.745 0.029 4049.175 3710.660 1.0
beta[rev_rating] 0.576 0.029 4081.620 3988.041 1.0
beta[num_spots] 0.443 0.029 3919.668 3667.374 1.0
beta[crowded] -0.519 0.028 4092.137 3914.557 1.0
sigma 0.996 0.020 3445.294 3650.738 1.0
/tmp/ipykernel_9091/4084804720.py:39: UserWarning: The figure layout has changed to tight
  plt.tight_layout()
../_images/c053b209c77e3e8ccedef2cb022d20deb8aba956e8d37c43dc00ad2490c6571c.png

Combine both channels

sdm_panel, summary_sdm, effects_sdm = fit_panel_model(
    SDM, formula, panel, W, unit_effects="fixed", time_effects=True
)
display(summary_sdm)
display(effects_sdm)
display(diagnostics_table(sdm_panel.inference_data, ["rho", "beta", "sigma"]))
show_trace(
    sdm_panel.inference_data, ["rho", "sigma"], "SDM, two-way fixed effects: trace"
)
Gibbs sampling (sdm): 2 chains for 1,000 tune and 2,000 draw iterations (2 x 3,000 = 6,000 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 (3,516 draws/s)
mean sd eti89_lb eti89_ub ess_bulk ess_tail r_hat mcse_mean mcse_sd
rho 0.328 0.048 0.249 0.402 3816.393 2426.803 1.000 0.001 0.001
sigma 0.992 0.020 0.960 1.025 3478.192 3583.421 1.000 0.000 0.000
sigma2 0.984 0.041 0.921 1.051 3478.192 3583.421 1.000 0.001 0.000
poverty -0.751 0.029 -0.797 -0.705 4036.534 3774.100 1.000 0.000 0.000
rev_rating 0.583 0.029 0.537 0.629 4058.639 4013.994 1.000 0.000 0.000
num_spots 0.447 0.030 0.400 0.494 3876.568 3782.999 1.000 0.000 0.000
crowded -0.524 0.028 -0.568 -0.479 4087.255 4022.301 1.000 0.000 0.000
W*poverty 0.122 0.085 -0.017 0.257 4170.718 3850.074 1.000 0.001 0.001
W*rev_rating 0.006 0.085 -0.129 0.144 3878.824 3871.117 1.000 0.001 0.001
W*num_spots -0.067 0.083 -0.202 0.065 3937.851 3882.432 1.001 0.001 0.001
W*crowded -0.001 0.077 -0.125 0.119 4018.013 3797.017 1.000 0.001 0.001
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
poverty -0.757681 -0.815142 -0.699400 0.0 -0.178760 -0.397406 0.042636 0.1030 -0.936441 -1.179873 -0.693781 0.0
rev_rating 0.593194 0.535665 0.650864 0.0 0.284146 0.054713 0.515726 0.0165 0.877339 0.621938 1.125549 0.0
num_spots 0.451037 0.392042 0.513830 0.0 0.114394 -0.122135 0.338179 0.3095 0.565431 0.303530 0.820773 0.0
crowded -0.533645 -0.588956 -0.477566 0.0 -0.248304 -0.455261 -0.050543 0.0145 -0.781949 -1.013597 -0.563729 0.0
mean sd ess_bulk ess_tail r_hat
rho 0.328 0.048 3816.393 2426.803 1.000
beta[poverty] -0.751 0.029 4036.534 3774.100 1.000
beta[rev_rating] 0.583 0.029 4058.639 4013.994 1.000
beta[num_spots] 0.447 0.030 3876.568 3782.999 1.000
beta[crowded] -0.524 0.028 4087.255 4022.301 1.000
beta[W*poverty] 0.122 0.085 4170.718 3850.074 1.000
beta[W*rev_rating] 0.006 0.085 3878.824 3871.117 1.000
beta[W*num_spots] -0.067 0.083 3937.851 3882.432 1.001
beta[W*crowded] -0.001 0.077 4018.013 3797.017 1.000
sigma 0.992 0.020 3478.192 3583.421 1.000
/tmp/ipykernel_9091/4084804720.py:39: UserWarning: The figure layout has changed to tight
  plt.tight_layout()
../_images/0380fcb6ee844c287bc1c272d224850bdf5e49edf1b46069bcb61b883e625ff2.png

The error-side combination

sdem_panel, summary_sdem, effects_sdem = fit_panel_model(
    SDEM, formula, panel, W, unit_effects="fixed", time_effects=True
)
display(summary_sdem)
display(effects_sdem)
display(diagnostics_table(sdem_panel.inference_data, ["lam", "beta", "sigma"]))
show_trace(
    sdem_panel.inference_data, ["lam", "sigma"], "SDEM, two-way fixed effects: trace"
)
Gibbs sampling (sdem): 2 chains for 1,000 tune and 2,000 draw iterations (2 x 3,000 = 6,000 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 (2,812 draws/s)
mean sd eti89_lb eti89_ub ess_bulk ess_tail r_hat mcse_mean mcse_sd
lam 0.337 0.047 0.261 0.411 3907.902 2766.580 1.001 0.001 0.001
sigma 0.991 0.020 0.959 1.024 3489.943 3567.745 1.000 0.000 0.000
sigma2 0.982 0.041 0.919 1.049 3489.943 3567.745 1.000 0.001 0.000
poverty -0.758 0.030 -0.806 -0.711 3968.129 3859.696 1.000 0.000 0.000
rev_rating 0.593 0.029 0.546 0.640 4031.515 3971.097 1.000 0.000 0.000
num_spots 0.449 0.031 0.401 0.499 3860.441 3803.152 1.000 0.000 0.000
crowded -0.534 0.029 -0.580 -0.489 4110.969 4003.074 1.000 0.000 0.000
W*poverty -0.155 0.087 -0.294 -0.015 4154.836 3822.265 1.002 0.001 0.001
W*rev_rating 0.235 0.092 0.089 0.380 3888.949 3682.768 1.000 0.001 0.001
W*num_spots 0.073 0.092 -0.076 0.220 3974.408 3933.013 1.001 0.001 0.001
W*crowded -0.210 0.084 -0.344 -0.078 4002.621 3781.014 1.000 0.001 0.001
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
poverty -0.757950 -0.815718 -0.699951 0.0 -0.154850 -0.325206 0.017886 0.0745 -0.912800 -1.110067 -0.715273 0.0
rev_rating 0.592842 0.535133 0.649795 0.0 0.234925 0.049938 0.413909 0.0120 0.827767 0.619166 1.027433 0.0
num_spots 0.449289 0.390449 0.511144 0.0 0.072909 -0.113211 0.247810 0.4175 0.522198 0.312261 0.727066 0.0
crowded -0.534346 -0.590447 -0.478324 0.0 -0.210196 -0.377282 -0.049640 0.0130 -0.744542 -0.937623 -0.560528 0.0
mean sd ess_bulk ess_tail r_hat
lam 0.337 0.047 3907.902 2766.580 1.001
beta[poverty] -0.758 0.030 3968.129 3859.696 1.000
beta[rev_rating] 0.593 0.029 4031.515 3971.097 1.000
beta[num_spots] 0.449 0.031 3860.441 3803.152 1.000
beta[crowded] -0.534 0.029 4110.969 4003.074 1.000
beta[W*poverty] -0.155 0.087 4154.836 3822.265 1.002
beta[W*rev_rating] 0.235 0.092 3888.949 3682.768 1.000
beta[W*num_spots] 0.073 0.092 3974.408 3933.013 1.001
beta[W*crowded] -0.210 0.084 4002.621 3781.014 1.000
sigma 0.991 0.020 3489.943 3567.745 1.000
/tmp/ipykernel_9091/4084804720.py:39: UserWarning: The figure layout has changed to tight
  plt.tight_layout()
../_images/d4b0c3a31e3ab9b633a6b7fa23661b24d6a1e2cea243f650c78d72c8709a461a.png

Check the chains before comparing anything

Panel SAR/SDEM models inherit the slow-mixing behavior of \(\rho\) (or \(\lambda\)) documented by Wolf, Anselin & Arribas-Bel (2018) [Wolf et al., 2018]. The spatial_mcmc_diagnostic helper checks ESS, sampler yield, \(\hat{R}\), and HPDI stability for the spatial scalar.

from neighbayes.diagnostics import spatial_mcmc_diagnostic

spatial_mcmc_diagnostic(sdm_panel, emit_warnings=False).to_frame()
ess_bulk ess_tail r_hat mcse_mean yield_pct hpdi_drift_pct adequate
parameter
rho 3816.393072 2426.803366 1.00026 0.000775 95.409827 5.200287 False

Swap fixed effects for random effects

The random-effects models replace deterministic unit fixed effects with latent unit intercepts \(\alpha_i \sim N(0, \sigma_\alpha^2)\). That lets the notebook estimate the variance of unit heterogeneity directly and compare FE and RE behavior on the same synthetic balanced panel.

The non-spatial random-effects baseline

ols_panel_re, summary_ols_re, effects_ols_re = fit_panel_model(
    OLS, formula, panel, W, unit_effects="random"
)
display(summary_ols_re)
display(effects_ols_re)
display(
    diagnostics_table(ols_panel_re.inference_data, ["beta", "sigma", "unit_effect_sd"])
)
show_trace(
    ols_panel_re.inference_data,
    ["sigma", "unit_effect_sd"],
    "OLS, random effects: trace",
)
Initializing NUTS using jitter+adapt_diag...
Multiprocess sampling (2 chains in 2 jobs)
NUTS: [beta, sigma2, unit_effect_sd, unit_effect_raw]
Sampling 2 chains for 1_000 tune and 2_000 draw iterations (2_000 + 4_000 draws total) took 6 seconds.
We recommend running at least 4 chains for robust computation of convergence diagnostics
/tmp/ipykernel_9091/4084804720.py:39: UserWarning: The figure layout has changed to tight
  plt.tight_layout()
/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
Intercept 2.363 0.040 2.299 2.427 1927.829 2251.520 1.001 0.001 0.001
poverty -0.776 0.028 -0.821 -0.732 5092.639 3145.635 1.000 0.000 0.000
rev_rating 0.604 0.027 0.562 0.648 4901.934 3406.514 1.000 0.000 0.000
num_spots 0.433 0.029 0.387 0.479 4891.079 3121.919 1.000 0.000 0.000
crowded -0.554 0.027 -0.596 -0.510 4758.572 3142.473 1.002 0.000 0.000
... ... ... ... ... ... ... ... ... ...
unit_effect[395] 0.252 0.390 -0.388 0.884 6527.016 2859.236 1.001 0.005 0.007
unit_effect[396] -0.653 0.391 -1.264 -0.031 4294.110 2961.119 1.001 0.006 0.006
unit_effect[397] 0.224 0.404 -0.416 0.857 7278.722 3093.999 1.002 0.005 0.007
unit_effect[398] 0.645 0.404 0.003 1.302 6414.412 3074.071 1.002 0.005 0.007
unit_effect[399] -0.342 0.394 -0.971 0.286 5600.040 2772.529 1.003 0.005 0.006

808 rows × 9 columns

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
poverty -0.776341 -0.831376 -0.722828 0.0 0.0 0.0 0.0 0.0 -0.776341 -0.831376 -0.722828 0.0
rev_rating 0.604488 0.552675 0.657959 0.0 0.0 0.0 0.0 0.0 0.604488 0.552675 0.657959 0.0
num_spots 0.432636 0.374315 0.489631 0.0 0.0 0.0 0.0 0.0 0.432636 0.374315 0.489631 0.0
crowded -0.553761 -0.606045 -0.502086 0.0 0.0 0.0 0.0 0.0 -0.553761 -0.606045 -0.502086 0.0
mean sd ess_bulk ess_tail r_hat
beta[Intercept] 2.363 0.040 1927.829 2251.520 1.001
beta[poverty] -0.776 0.028 5092.639 3145.635 1.000
beta[rev_rating] 0.604 0.027 4901.934 3406.514 1.000
beta[num_spots] 0.433 0.029 4891.079 3121.919 1.000
beta[crowded] -0.554 0.027 4758.572 3142.473 1.002
sigma 1.027 0.021 3031.845 2880.417 1.001
unit_effect_sd 0.604 0.038 1361.261 1966.401 1.001
../_images/215710f56df38aee210dc4fd92247710ecf458e204ca45040d20307a41fa9b73.png

Random effects with a spatial lag

sar_panel_re, summary_sar_re, effects_sar_re = fit_panel_model(
    SAR, formula, panel, W, unit_effects="random"
)
display(summary_sar_re)
display(effects_sar_re)
display(
    diagnostics_table(
        sar_panel_re.inference_data, ["rho", "beta", "sigma", "unit_effect_sd"]
    )
)
show_trace(
    sar_panel_re.inference_data,
    ["rho", "sigma", "unit_effect_sd"],
    "SAR, random effects: trace",
)
Gibbs sampling (re_sar): 2 chains for 1,000 tune and 2,000 draw iterations (2 x 3,000 = 6,000 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 (3,400 draws/s)
mean sd eti89_lb eti89_ub ess_bulk ess_tail r_hat mcse_mean mcse_sd
rho 0.314 0.032 0.260 0.365 200.413 346.241 1.009 0.002 0.001
sigma 0.993 0.020 0.962 1.026 2138.832 3027.420 1.001 0.000 0.000
unit_effect_sd 0.576 0.036 0.518 0.635 1910.728 2557.352 1.003 0.001 0.000
Intercept 1.617 0.087 1.480 1.763 178.954 332.591 1.010 0.006 0.003
poverty -0.773 0.026 -0.814 -0.732 2534.099 3131.858 1.000 0.001 0.000
... ... ... ... ... ... ... ... ... ...
unit_effect[395] 0.270 0.374 -0.332 0.875 3782.867 3916.299 1.000 0.006 0.004
unit_effect[396] -0.669 0.377 -1.281 -0.059 4015.743 4190.504 1.000 0.006 0.004
unit_effect[397] 0.179 0.384 -0.442 0.777 3722.386 3720.754 1.000 0.006 0.004
unit_effect[398] 0.686 0.389 0.056 1.311 3905.632 3151.826 1.000 0.006 0.005
unit_effect[399] -0.502 0.372 -1.097 0.099 4032.282 3895.630 1.000 0.006 0.004

408 rows × 9 columns

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
poverty -0.784985 -0.836969 -0.733842 0.0 -0.343581 -0.450899 -0.246403 0.0 -1.128566 -1.262838 -1.006681 0.0
rev_rating 0.598589 0.544083 0.653381 0.0 0.261874 0.187071 0.341621 0.0 0.860464 0.757643 0.970875 0.0
num_spots 0.432085 0.376952 0.487480 0.0 0.189098 0.133217 0.251703 0.0 0.621183 0.526731 0.722215 0.0
crowded -0.551668 -0.603241 -0.499921 0.0 -0.241391 -0.316339 -0.170914 0.0 -0.793059 -0.899461 -0.694007 0.0
mean sd ess_bulk ess_tail r_hat
rho 0.314 0.032 200.413 346.241 1.009
beta[Intercept] 1.617 0.087 178.954 332.591 1.010
beta[poverty] -0.773 0.026 2534.099 3131.858 1.000
beta[rev_rating] 0.589 0.027 2737.863 3053.990 1.000
beta[num_spots] 0.425 0.028 2892.627 3212.416 1.000
beta[crowded] -0.543 0.026 3066.786 3417.202 1.001
sigma 0.993 0.020 2138.832 3027.420 1.001
unit_effect_sd 0.576 0.036 1910.728 2557.352 1.003
/tmp/ipykernel_9091/4084804720.py:39: UserWarning: The figure layout has changed to tight
  plt.tight_layout()
../_images/97b05374940aa45af585a0169775d7121fbf213975c1415e32d7c1128be5b878.png

Random effects with spatial errors

sem_panel_re, summary_sem_re, effects_sem_re = fit_panel_model(
    SEM, formula, panel, W, unit_effects="random"
)
display(summary_sem_re)
display(effects_sem_re)
display(
    diagnostics_table(
        sem_panel_re.inference_data, ["lam", "beta", "sigma", "unit_effect_sd"]
    )
)
show_trace(
    sem_panel_re.inference_data,
    ["lam", "sigma", "unit_effect_sd"],
    "SEM, random effects: trace",
)
Gibbs sampling (re_sem): 2 chains for 1,000 tune and 2,000 draw iterations (2 x 3,000 = 6,000 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 17s (346 draws/s)
mean sd eti89_lb eti89_ub ess_bulk ess_tail r_hat mcse_mean mcse_sd
lam 0.375 0.043 0.307 0.444 3666.683 3175.478 1.002 0.001 0.001
sigma 0.999 0.021 0.966 1.033 1947.701 2663.574 1.001 0.000 0.000
unit_effect_sd 0.574 0.039 0.512 0.638 1583.203 2047.355 1.001 0.001 0.001
Intercept 2.365 0.050 2.284 2.446 2091.980 2815.732 1.000 0.001 0.001
poverty -0.765 0.027 -0.809 -0.723 2501.696 3079.949 1.001 0.001 0.000
... ... ... ... ... ... ... ... ... ...
unit_effect[395] 0.244 0.377 -0.359 0.855 3998.064 3751.711 1.000 0.006 0.004
unit_effect[396] -0.723 0.381 -1.325 -0.113 4002.272 3765.360 1.000 0.006 0.004
unit_effect[397] 0.173 0.382 -0.432 0.787 3929.339 3683.848 1.000 0.006 0.004
unit_effect[398] 0.656 0.388 0.039 1.276 3885.017 3870.476 1.001 0.006 0.005
unit_effect[399] -0.398 0.383 -1.013 0.210 4030.113 3872.713 1.000 0.006 0.004

408 rows × 9 columns

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
poverty -0.765314 -0.819180 -0.712121 0.0 0.0 0.0 0.0 0.0 -0.765314 -0.819180 -0.712121 0.0
rev_rating 0.581759 0.530346 0.634204 0.0 0.0 0.0 0.0 0.0 0.581759 0.530346 0.634204 0.0
num_spots 0.419700 0.365175 0.474444 0.0 0.0 0.0 0.0 0.0 0.419700 0.365175 0.474444 0.0
crowded -0.535229 -0.583658 -0.486370 0.0 0.0 0.0 0.0 0.0 -0.535229 -0.583658 -0.486370 0.0
mean sd ess_bulk ess_tail r_hat
lam 0.375 0.043 3666.683 3175.478 1.002
beta[Intercept] 2.365 0.050 2091.980 2815.732 1.000
beta[poverty] -0.765 0.027 2501.696 3079.949 1.001
beta[rev_rating] 0.582 0.027 2803.223 3233.560 1.000
beta[num_spots] 0.420 0.028 2869.612 3412.580 1.000
beta[crowded] -0.535 0.026 2819.541 3107.645 1.000
sigma 0.999 0.021 1947.701 2663.574 1.001
unit_effect_sd 0.574 0.039 1583.203 2047.355 1.001
/tmp/ipykernel_9091/4084804720.py:39: UserWarning: The figure layout has changed to tight
  plt.tight_layout()
../_images/2c923338064681baafbf676eab076a6ffc083c2ea77f8b16649ec5be1c7cee69.png

Compare what you have fitted

Models with the same unit effects describe the same outcomes, so bridge sampling can give each a marginal likelihood. Each entry below is the log Bayes factor for the row’s model over the column’s, so positive values favor the row.

from neighbayes.diagnostics import bayes_factor_compare_models

fixed = {
    "OLS": ols_panel,
    "SAR": sar_panel,
    "SEM": sem_panel,
    "SDM": sdm_panel,
    "SDEM": sdem_panel,
}
random = {"OLS": ols_panel_re, "SAR": sar_panel_re, "SEM": sem_panel_re}

for label, models in {"Fixed effects": fixed, "Random effects": random}.items():
    print(label)
    display(
        bayes_factor_compare_models(
            models, method="bridge", log=True, random_state=0
        ).round(1)
    )
Fixed effects
Random effects
/tmp/ipykernel_9091/1402646083.py:15: UserWarning: Bridge sampling with 4000 posterior samples for 'OLS' may yield imprecise marginal-likelihood estimates. A conservative rule of thumb is 40,000+ samples (Gronau, Singmann, & Wagenmakers, 2017).
  bayes_factor_compare_models(
/tmp/ipykernel_9091/1402646083.py:15: UserWarning: Bridge sampling with 4000 posterior samples for 'OLS' may yield imprecise marginal-likelihood estimates. A conservative rule of thumb is 40,000+ samples (Gronau, Singmann, & Wagenmakers, 2017).
  bayes_factor_compare_models(
OLS SAR SEM SDM SDEM
OLS 0.0 -29.4 -22.7 -11.2 -12.2
SAR 29.4 0.0 6.6 18.2 17.1
SEM 22.7 -6.6 0.0 11.5 10.5
SDM 11.2 -18.2 -11.5 0.0 -1.0
SDEM 12.2 -17.1 -10.5 1.0 0.0
OLS SAR SEM
OLS 0.0 -42.6 -29.4
SAR 42.6 0.0 13.2
SEM 29.4 -13.2 0.0

Fixed and random effects cannot be compared this way. A fixed-effects likelihood is the random-effects likelihood under a flat prior on the effects, which is improper, so it has no marginal likelihood. az.loo can compare them, because each model stores every observation’s density given all the others, but it measures prediction: random effects gain from pooling whether or not their assumptions hold, so a better score does not show that their estimates are right.

Compare the estimates instead, which is the logic of a Hausman test. Unit effects related to the covariates move both \(\beta\) and \(\rho\) under random effects; a spatial pattern in the effects that the covariates do not explain moves \(\rho\) and leaves \(\beta\) alone.

fe_estimates = sar_panel.summary()
re_estimates = sar_panel_re.summary(var_names=["~unit_effect"])
shared = ["rho", *xcols]

contrast = pd.DataFrame(
    {
        "fixed": fe_estimates.loc[shared, "mean"],
        "random": re_estimates.loc[shared, "mean"],
    }
)
contrast["gap in fixed-effects SDs"] = (
    contrast["random"] - contrast["fixed"]
) / fe_estimates.loc[shared, "sd"]
display(contrast.round(3))
print(
    "largest gap: "
    f"{contrast['gap in fixed-effects SDs'].abs().max():.2f} fixed-effects SDs"
)
fixed random gap in fixed-effects SDs
rho 0.303 0.314 0.307
poverty -0.753 -0.773 -0.691
rev_rating 0.583 0.589 0.204
num_spots 0.449 0.425 -0.792
crowded -0.526 -0.543 -0.624
largest gap: 0.79 fixed-effects SDs

Gaps under about one posterior standard deviation give no reason to doubt the random effects. Larger ones, in \(\beta\) especially, point to unit effects that move with the covariates, which only the fixed effects absorb.

Let the tests pick the specification

The panel models run the cross-section’s Lagrange-multiplier tests, written for the panel and named with a Panel- prefix. Under fixed effects they score the transformed likelihood the demeaned data give (Lee & Yu 2010); under random effects the unit effects enter as coefficients carrying their prior. spatial_diagnostics() runs the tests that apply to a fitted model, and spatial_diagnostics_decision() reads them by the rule of the cross-sectional walkthrough: a lone plain rejection adds its term, and the robust pair only settles a double rejection. Fit the recommended model and ask again until the tests stop rejecting.

The panel was simulated from a SAR with no \(WX\) term, so the walk should end at the SAR.

def read_tests(model, alpha=0.05):
    """Show a fitted model's LM tests and say which reject."""
    diag = model.spatial_diagnostics()
    rejecting = diag.index[diag["p_value"] < alpha].tolist()
    name = type(model).__name__
    print(f"{name}: tests rejecting at {alpha}: {', '.join(rejecting) or 'none'}")
    print(
        f"{name}: recommended model: "
        f"{model.spatial_diagnostics_decision(alpha=alpha, format='model')}"
    )
    return diag[["statistic", "df", "p_value", "ci_lower", "ci_upper"]].round(3)

Start from the fixed-effects OLS panel

The OLS panel’s tests ask whether the outcome, the errors or the neighbors’ covariates carry spatial dependence once the unit and period effects are removed.

read_tests(ols_panel)
OLS: tests rejecting at 0.05: Panel-LM-Lag, Panel-LM-Error, Panel-LM-WX, Panel-LM-SDM-Joint, Panel-LM-SLX-Error-Joint, Panel-Robust-LM-Lag
OLS: recommended model: SAR
statistic df p_value ci_lower ci_upper
test
Panel-LM-Lag 72.916 1 0.000 61.790 85.980
Panel-LM-Error 56.481 1 0.000 46.815 68.072
Panel-LM-WX 20.576 4 0.000 17.504 24.222
Panel-LM-SDM-Joint 77.057 5 0.000 65.224 90.947
Panel-LM-SLX-Error-Joint 77.057 5 0.000 64.567 92.117
Panel-Robust-LM-Lag 18.663 1 0.000 15.284 22.522
Panel-Robust-LM-Error 2.228 1 0.136 1.195 3.645
Panel-Robust-LM-WX 4.141 4 0.387 3.460 4.958
ols_panel.spatial_diagnostics_decision()
../_images/768e11d9bf7e5053281ec5f5caf6a7fac6cd8175d84cf8f736e50446b4454ca0.svg

Refit, and ask again

The OLS panel’s tree names the model to fit next, and that model tests the terms it still leaves out; at the SAR panel, the neighbors’ covariates (towards the SDM) and the error process (towards SARAR, which neighbayes does not fit). The cell below follows the recommendations through the fixed-effects models fitted above until a model’s tests stop rejecting.

def walk(start, fitted, alpha=0.05, show=True):
    """Follow the recommendations from ``start`` through the fitted models."""
    model, path = start, [type(start).__name__]
    while True:
        nxt = model.spatial_diagnostics_decision(alpha=alpha, format="model")
        if nxt == path[-1]:
            break
        if nxt not in fitted:
            path.append(f"{nxt} (not fitted here)")
            break
        model = fitted[nxt]
        path.append(nxt)
        if show:
            print(f"--- at the {nxt} fit ---")
            display(read_tests(model, alpha))
            display(model.spatial_diagnostics_decision(alpha=alpha))
    if show:
        print(" → ".join(path))
    return path


fitted = {"SAR": sar_panel, "SEM": sem_panel, "SDM": sdm_panel, "SDEM": sdem_panel}
path = walk(ols_panel, fitted)
--- at the SAR fit ---
SAR: tests rejecting at 0.05: none
SAR: recommended model: SAR
OLS → SAR
statistic df p_value ci_lower ci_upper
test
Panel-LM-Error 1.360 1 0.243 1.079 2.198
Panel-LM-WX 2.679 4 0.613 2.215 3.109
Panel-Robust-LM-WX 1.916 4 0.751 1.657 4.561
Panel-Robust-LM-Error 0.598 1 0.439 0.298 4.005
../_images/23191a096102f81e57a0dd1f16ce71a88671feb84aad801513909699ae27743b.svg

A random-effects fit runs the same tests through the same tree.

read_tests(sar_panel_re)
SAR: tests rejecting at 0.05: none
SAR: recommended model: SAR
statistic df p_value ci_lower ci_upper
test
Panel-LM-Error 0.124 1 0.724 0.002 4.331
Panel-LM-WX 2.960 4 0.565 1.977 3.025
Panel-Robust-LM-WX 4.929 4 0.295 1.747 9.868
Panel-Robust-LM-Error 2.094 1 0.148 0.002 10.848

Where to go next

This lesson used small draw counts so it runs quickly. For real work raise draws and tune, and if you see divergences or tree-depth warnings raise target_accept to 0.95–0.99. It is also worth checking that your conclusions survive a change of fixed-effects specification (effects=0/1/2/3) and of priors.