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:

  1. \(\omega \mid \rho, \beta\) — Pólya–Gamma augmentation at \(\eta = (I - \rho W)^{-1}X\beta\)

  2. \(\rho \mid \omega\) — a collapsed one-dimensional slice, with \(\beta\) integrated out

  3. \(\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

slice_width

initial slice interval for ρ

init_jitter

scale of the random perturbation applied to chain starts

krylov_degree, krylov_dmax, krylov_reuse

shift-invert Krylov basis for the ρ conditional — degree, trust radius, and whether the basis is reused across draws

timeout

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