How to fit a spatial logit model¶
Binary outcomes with spatial dependence. The unmarked SARLogit is the latent
SAR, which propagates the logit’s own disturbance (below);
SARLogit(latent=False) is the reduced-form SAR, whose spatial multiplier acts
on the mean of the log-odds only. This guide fits the reduced form first, then
the latent models. The reduced form samples by Pólya–Gamma Gibbs and has no
NUTS path — fit(sampler="nuts") raises. The equations and constructor
arguments are in Supported Models.
There is no spatial logit with random effects. In a cross-section the effects’ sd trades off against \(\beta\) and against the spatial parameter, and binary outcomes barely constrain the trade, so their posteriors are mostly prior.
import arviz as az
import numpy as np
import pandas as pd
from neighbayes.dgp import simulate_sar_logit
from neighbayes.models import SARLogit
/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
Simulate a known process¶
simulate_sar_logit builds a square grid of side n, so n=35 gives
\(35^2 = 1225\) observations. That matters: binary outcomes carry far less
information per observation than continuous ones, and \(\rho\) in a spatial logit
is weakly identified below roughly a thousand units. Fitting one of these to
\(n = 100\) and concluding the sampler is broken is a common mistake.
RHO_TRUE, BETA_TRUE = 0.5, np.array([-0.3, 0.5])
data_sar = simulate_sar_logit(
n_side=35, rho=RHO_TRUE, beta=BETA_TRUE, seed=42, latent=False
)
y_sar, X_sar, W_sar = data_sar["y"], data_sar["X"], data_sar["W_graph"]
print(f"observations : {len(y_sar)} (35 x 35 queen grid)")
print(f"covariates : {X_sar.shape[1]}")
print(f"outcome : {int(y_sar.sum())} ones, {int(len(y_sar) - y_sar.sum())} zeros")
observations : 1225 (35 x 35 queen grid)
covariates : 2
outcome : 451 ones, 774 zeros
Fit the reduced-form model (latent=False)¶
The sweep has three blocks, only one of which is non-conjugate:
\(\omega \mid \rho, \beta\) — Pólya–Gamma augmentation at \(\eta = (I - \rho W)^{-1}X\beta\)
\(\rho \mid \omega\) — a collapsed one-dimensional slice, with \(\beta\) integrated out
\(\beta \mid \omega, \rho\) — conjugate normal
Collapsing block 2 is what makes this mix: \(\rho\) and \(\beta\) trade off in the mean, and a \(\rho\) update conditioned on the current \(\beta\) crawls.
model_sar = SARLogit(y=y_sar, X=X_sar, W=W_sar, latent=False)
idata_sar = model_sar.fit(
draws=1500, tune=800, chains=4, random_seed=42, progressbar=False
)
az.summary(idata_sar, var_names=["rho", "beta"]).round(3)
| mean | sd | eti89_lb | eti89_ub | ess_bulk | ess_tail | r_hat | mcse_mean | mcse_sd | |
|---|---|---|---|---|---|---|---|---|---|
| rho | 0.671 | 0.097 | 0.5 | 0.81 | 4468 | 3751 | 1.00 | 0.0015 | 0.0014 |
| beta[x0] | -0.18 | 0.06 | -0.29 | -0.099 | 4709 | 3875 | 1.00 | 0.00091 | 0.00089 |
| beta[x1] | 0.442 | 0.065 | 0.34 | 0.55 | 4317 | 4476 | 1.00 | 0.00099 | 0.00066 |
print(f"rho : {float(idata_sar.posterior['rho'].mean()):.3f} (true {RHO_TRUE})")
print(
f"beta : {idata_sar.posterior['beta'].mean(dim=['chain', 'draw']).values.round(3)}"
f" (true {BETA_TRUE})"
)
rho : 0.671 (true 0.5)
beta : [-0.18 0.442] (true [-0.3 0.5])
\(\rho\) comes back with a wide credible interval even at \(n = 1225\). That is
the model, not the sampler — check ess_bulk and r_hat above to confirm the
chain is healthy, then read the width as what the data support.
Read the spillovers¶
In a linear SAR model \(\beta\) is a marginal effect. Here it is not. The
link is nonlinear, so a change in \(x_i\) moves \(y_j\) through both the spatial
multiplier \((I - \rho W)^{-1}\) and the logistic derivative, which varies with
\(\eta_i\). impacts() does the averaging and returns the
LeSage–Pace decomposition — direct, indirect, total — on the probability scale.
model_sar.impacts().round(4)
| 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 | ||||||||||||
| x1 | 0.5169 | 0.3951 | 0.6388 | 0.0 | 0.9082 | 0.3692 | 1.6341 | 0.0 | 1.425 | 0.8622 | 2.1582 | 0.0 |
Report these, not the raw coefficients, whenever the question is
“how much does \(x\) change the outcome”. The gap between direct and the
coefficient is the part of the effect that the spatial multiplier feeds back
onto the unit itself.
Configure the sampler¶
backend behaves as it does everywhere in the package: "auto"
(the default — JAX when installed, else NumPy), "jax", or "numpy".
Beyond the shared fit() arguments, SARLogit accepts the options below.
Anything else raises TypeError rather than being silently ignored.
Option |
Meaning |
|---|---|
|
initial slice interval for ρ |
|
scale of the random perturbation applied to chain starts |
|
shift-invert Krylov basis for the ρ conditional — degree, trust radius, and whether the basis is reused across draws |
|
abort a run that exceeds this many seconds |
idata_tuned = SARLogit(y=y_sar, X=X_sar, W=W_sar, latent=False).fit(
draws=800,
tune=500,
chains=2,
random_seed=7,
progressbar=False,
backend="numpy",
slice_width=0.4,
krylov_reuse=True,
)
print(
f"rho = {float(idata_tuned.posterior['rho'].mean()):.3f}, "
f"ess = {float(az.ess(idata_tuned, var_names=['rho'])['rho']):.0f}"
)
rho = 0.678, ess = 1212
Fitted probabilities¶
fitted_probabilities() returns \(P(y_i = 1)\) at the posterior mean,
\(\hat\eta = (I - \hat\rho W)^{-1} X\hat\beta\): the multiplier is in the mean.
probs_sar = model_sar.fitted_probabilities()
pd.Series(
{"mean": probs_sar.mean(), "min": probs_sar.min(), "max": probs_sar.max()},
name="SARLogit",
).round(3)
mean 0.367
min 0.075
max 0.770
Name: SARLogit, dtype: float64
Fit the latent SAR and SEM¶
The reduced form lets the multiplier carry only the covariates. The latent
SAR carries the logit’s own disturbance too, \(y = \mathbf 1\{y^* > 0\}\) with
\((I - \rho W)y^* = X\beta + \varepsilon\) and \(\varepsilon\) standard logistic, so
neighbours share their unobservables as well as their covariates; it is the
unmarked SARLogit (latent=True below only makes that explicit). Its
error-only sibling, \(y^* = X\beta +
(I - \lambda W)^{-1}\varepsilon\), is SEMLogit. At \(\rho = 0\) or \(\lambda = 0\)
both are the plain logit, and neither has a variance parameter to trade off
against \(\rho\).
Both sample by an exact Gibbs sweep over the latent utilities and the
Kolmogorov scales that make the logistic a normal scale mixture (this needs
augax). They have no NUTS path; idata_kwargs={"log_likelihood": True}
stores each observation’s likelihood with its utility integrated out, for
LOO.
from neighbayes.dgp import simulate_sem_logit
from neighbayes.models import SEMLogit
data_lat = simulate_sar_logit(n_side=30, rho=0.4, beta=BETA_TRUE, seed=3, latent=True)
latent = SARLogit(y=data_lat["y"], X=data_lat["X"], W=data_lat["W_graph"], latent=True)
idata_lat = latent.fit(draws=1000, tune=500, chains=2, random_seed=3, progressbar=False)
az.summary(idata_lat, var_names=["rho", "beta"]).round(3)
| mean | sd | eti89_lb | eti89_ub | ess_bulk | ess_tail | r_hat | mcse_mean | mcse_sd | |
|---|---|---|---|---|---|---|---|---|---|
| rho | 0.324 | 0.061 | 0.22 | 0.42 | 422 | 653 | 1.00 | 0.003 | 0.0015 |
| beta[x0] | -0.257 | 0.065 | -0.36 | -0.15 | 899 | 1330 | 1.00 | 0.0022 | 0.0012 |
| beta[x1] | 0.449 | 0.075 | 0.33 | 0.57 | 497 | 901 | 1.00 | 0.0034 | 0.0017 |
data_sem = simulate_sem_logit(n_side=30, lam=0.4, beta=BETA_TRUE, seed=4)
sem = SEMLogit(y=data_sem["y"], X=data_sem["X"], W=data_sem["W_graph"])
idata_sem = sem.fit(draws=1000, tune=500, chains=2, random_seed=4, progressbar=False)
az.summary(idata_sem, var_names=["lam", "beta"]).round(3)
| mean | sd | eti89_lb | eti89_ub | ess_bulk | ess_tail | r_hat | mcse_mean | mcse_sd | |
|---|---|---|---|---|---|---|---|---|---|
| lam | 0.295 | 0.069 | 0.18 | 0.4 | 366 | 563 | 1.00 | 0.0036 | 0.0019 |
| beta[x0] | -0.393 | 0.093 | -0.54 | -0.24 | 815 | 1196 | 1.00 | 0.0033 | 0.0017 |
| beta[x1] | 0.478 | 0.073 | 0.36 | 0.59 | 706 | 941 | 1.00 | 0.0028 | 0.0014 |
The latent models’ impacts are on the latent index by default, and
scale="probability" gives them on \(P(y_i = 1)\); fitted_probabilities()
simulates the utilities: the
multiplier mixes the disturbances, so their marginals are no longer logistic.
The GLM suite’s LM tests on a Logit fit are the score tests of exactly these
two models, LM-Lag of the latent SAR and LM-Error of the latent SEM; see
Supported Models.
Let the tests choose the form¶
spatial_diagnostics_decision() on a fitted Logit reads the spillover and
error tests as a pair. A latent SAR moves both, in the proportion its one \(\rho\)
implies; when they move out of that proportion, Robust-LM-Error is significant
and the tree names SDEMLogit, \(y^* = X\beta + WX\theta + (I - \lambda
W)^{-1}\varepsilon\), which gives the spillover and the clustered disturbance a
parameter each. Here the covariate’s spillover opposes its direct effect, which
no single \(\rho\) can produce.
from neighbayes.dgp import simulate_sdem_logit
from neighbayes.models import Logit, SDEMLogit
data_sdem = simulate_sdem_logit(
n_side=30, lam=0.6, beta=BETA_TRUE, theta=np.array([-1.0]), seed=0
)
logit = Logit(y=data_sdem["y"], X=data_sdem["X"], W=data_sdem["W_graph"])
logit.fit(draws=1000, tune=500, chains=2, random_seed=0, progressbar=False)
print(logit.spatial_diagnostics_decision(format="model"))
logit.spatial_diagnostics().loc[
["Robust-LM-Lag", "LM-Error", "Robust-LM-Error"], ["statistic", "p_value"]
].round(3)
SDEMLogit
Initializing NUTS using jitter+adapt_diag...
Multiprocess sampling (2 chains in 2 jobs)
NUTS: [beta]
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
| statistic | p_value | |
|---|---|---|
| test | ||
| Robust-LM-Lag | 38.352 | 0.0 |
| LM-Error | 106.267 | 0.0 |
| Robust-LM-Error | 58.949 | 0.0 |
sdem = SDEMLogit(y=data_sdem["y"], X=data_sdem["X"], W=data_sdem["W_graph"])
idata_sdem = sdem.fit(draws=1000, tune=500, chains=2, random_seed=0, progressbar=False)
az.summary(idata_sdem, var_names=["lam", "beta"]).round(3)
| mean | sd | eti89_lb | eti89_ub | ess_bulk | ess_tail | r_hat | mcse_mean | mcse_sd | |
|---|---|---|---|---|---|---|---|---|---|
| lam | 0.621 | 0.048 | 0.54 | 0.7 | 382 | 681 | 1.00 | 0.0025 | 0.0013 |
| beta[x0] | -0.37 | 0.161 | -0.61 | -0.11 | 983 | 1083 | 1.00 | 0.0051 | 0.0031 |
| beta[x1] | 0.401 | 0.091 | 0.26 | 0.54 | 662 | 1003 | 1.00 | 0.0035 | 0.002 |
| beta[W*x1] | -1.04 | 0.177 | -1.3 | -0.77 | 521 | 815 | 1.00 | 0.0077 | 0.0039 |
What to check before trusting the output¶
print("groups:", list(idata_sar.children))
az.summary(idata_sar, var_names=["rho"]).round(3)
groups: ['posterior', 'observed_data']
| mean | sd | eti89_lb | eti89_ub | ess_bulk | ess_tail | r_hat | mcse_mean | mcse_sd | |
|---|---|---|---|---|---|---|---|---|---|
| rho | 0.671 | 0.097 | 0.5 | 0.81 | 4468 | 3751 | 1.00 | 0.0015 | 0.0014 |
Caution
az.loo and az.waic run on this output and should not be used to choose
between a lag and an error specification. Pointwise leave-one-out assumes
observations are exchangeable given the parameters; under a spatial lag they are
not, because removing \(y_i\) changes the implied mean of its neighbours through
\((I - \rho W)^{-1}\). Use the
Bayesian LM specification tests or
spatial block cross-validation instead.
See also¶
How to run Bayesian LM specification tests — deciding between lag and error before you fit
How to set priors —
SARLogitPriorsHow to estimate spatial negative binomial models — the same Pólya–Gamma machinery for counts