How to predict at new locations¶
You have fitted a spatial model and want the outcome at units you did not
observe: new tracts, a region withheld for validation, or places where the
survey missed. model.predict returns the posterior predictive distribution
of those outcomes given every observed one. For each posterior draw it uses
the exact conditional Gaussian, the best predictor (BP) of
Goulard et al. [2017], so the result carries parameter
uncertainty instead of plugging in point estimates.
It also returns the trend predictor (TC), the model’s mean at the new units
with no correction from observed neighbors. TC is the floor BP has to beat.
This page shows how to call predict, and how to check what the spatial
correction is worth on your data.
predict covers OLS, SLX, SAR, SDM, SEM and SDEM with Gaussian errors.
Models with robust=True raise, because the Gaussian conditional does not
hold for Student-t errors.
Fit on the observed units¶
We simulate a SAR on a 20 × 20 rook grid, hold out four 4 × 4 blocks, and fit on the rest. The training weights are the contiguity graph of the observed units, row-standardized.
import numpy as np
import pandas as pd
import scipy.sparse as sp
from libpysal.graph import Graph
from neighbayes.dgp import simulate_sar
from neighbayes.models import SAR
GRID = 20
def held_out_blocks(n_side, rng, n_blocks=4, size=4):
"""Mask of ``n_blocks`` non-overlapping ``size`` x ``size`` blocks."""
row, col = np.divmod(np.arange(n_side * n_side), n_side)
slots = [
(r, c)
for r in range(0, n_side - size + 1, 5)
for c in range(0, n_side - size + 1, 5)
]
held = np.zeros(n_side * n_side, dtype=bool)
for k in rng.choice(len(slots), n_blocks, replace=False):
r0, c0 = slots[k]
held |= (row >= r0) & (row < r0 + size) & (col >= c0) & (col < c0 + size)
return held
gdf = simulate_sar(
n_side=GRID,
rho=0.6,
beta=np.array([1.0, 2.0]),
sigma=1.0,
seed=0,
create_gdf=True,
geometry_type="polygon",
contiguity="rook",
)
held = held_out_blocks(GRID, np.random.default_rng(0))
train = gdf[~held]
new = gdf[held]
model = SAR(
formula="y ~ X_1",
data=train,
W=Graph.build_contiguity(train, rook=True).transform("r"),
)
model.fit(draws=500, tune=500, chains=2, random_seed=0, progressbar=False)
model.summary()
/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
| mean | sd | eti89_lb | eti89_ub | ess_bulk | ess_tail | r_hat | mcse_mean | mcse_sd | |
|---|---|---|---|---|---|---|---|---|---|
| rho | 0.535 | 0.032 | 0.48 | 0.59 | 839 | 574 | 1.00 | 0.0011 | 0.00088 |
| sigma | 1.065 | 0.042 | 1 | 1.1 | 938 | 870 | 1.00 | 0.0014 | 0.001 |
| sigma2 | 1.136 | 0.091 | 1 | 1.3 | 938 | 870 | 1.00 | 0.003 | 0.0022 |
| Intercept | 1.117393 | 0.097595 | 0.955297 | 1.269568 | 724.995771 | 806.324662 | 0.999748 | 0.003603 | 0.002433 |
| X_1 | 2.140645 | 0.060728 | 2.046112 | 2.235844 | 880.91071 | 830.565354 | 1.004345 | 0.002023 | 0.0014 |
Predict¶
predict needs the covariates of the new units and a weights matrix over
all units, observed and new. By default the new units come last in that
matrix. Here they sit among the observed ones, so oos gives their positions.
For a formula-built model, pass the new covariates as a DataFrame; the
formula’s transforms are replayed on it.
W_all = Graph.build_contiguity(gdf, rook=True).transform("r")
oos = np.flatnonzero(held)
pred = model.predict(new, W_all, oos=oos, random_seed=0)
pred
<xarray.DataTree>
Group: /
├── Group: /predictions
│ Dimensions: (chain: 2, draw: 500, obs_new: 64)
│ Coordinates:
│ * chain (chain) int64 16B 0 1
│ * draw (draw) int64 4kB 0 1 2 3 4 5 6 7 ... 493 494 495 496 497 498 499
│ * obs_new (obs_new) int64 512B 100 101 102 103 115 ... 263 275 276 277 278
│ Data variables:
│ y (chain, draw, obs_new) float64 512kB 5.958 6.032 ... 2.623 0.1546
│ y_bp (chain, draw, obs_new) float64 512kB 5.199 5.679 ... 0.3889 -0.8048
│ y_tc (chain, draw, obs_new) float64 512kB 4.634 4.998 ... -0.9451
│ Attributes:
│ created_at: 2026-11-09T15:58:16.001093+00:00
│ creation_library: ArviZ
│ creation_library_version: 1.3.1
│ creation_library_language: Python
│ sample_dims: ['chain', 'draw']
└── Group: /predictions_constant_data
Dimensions: (obs_new: 64, coefficient: 2)
Coordinates:
* obs_new (obs_new) int64 512B 100 101 102 103 115 ... 275 276 277 278
* coefficient (coefficient) <U9 72B 'Intercept' 'X_1'
Data variables:
X_new (obs_new, coefficient) float64 1kB 1.0 0.5027 ... 1.0 -1.287
Attributes:
created_at: 2026-11-09T15:58:16.002593+00:00
creation_library: ArviZ
creation_library_version: 1.3.1
creation_library_language: Python
sample_dims: []The predictions group holds three variables over (chain, draw, obs_new):
y, draws from the posterior predictive, for intervals;y_bp, the conditional mean at each draw, whose average over draws is the posterior predictive mean;y_tc, the trend at each draw, ignoring observed neighbors.
The coordinate obs_new carries the index of new.
import arviz as az
p = pred.predictions
table = pd.DataFrame(
{
"observed": new["y"],
"bp": p["y_bp"].mean(("chain", "draw")).values,
"tc": p["y_tc"].mean(("chain", "draw")).values,
},
index=p["obs_new"].values,
)
hdi = az.hdi(p["y"], prob=0.9).transpose("obs_new", ...).values
table["lo90"], table["hi90"] = hdi[:, 0], hdi[:, 1]
table.head()
| observed | bp | tc | lo90 | hi90 | |
|---|---|---|---|---|---|
| 100 | 6.298116 | 5.000411 | 4.477441 | 2.892733 | 6.779004 |
| 101 | 5.471063 | 5.536332 | 4.906450 | 3.711894 | 7.508204 |
| 102 | -0.065245 | 1.874002 | 1.831561 | -0.000438 | 3.678448 |
| 103 | -1.581416 | -0.476253 | -0.836302 | -2.427346 | 1.342954 |
| 115 | 1.792536 | 2.154230 | 2.206624 | 0.111600 | 3.931489 |
For models with lagged covariates (SLX, SDM, SDEM), predict
recomputes \(WX\) for every unit on the full graph: an observed unit that
gains a new neighbor gets a new lagged covariate.
Check what the correction is worth¶
BP improves on TC only through observed neighbors. A new unit deep inside a held-out block has none, and its prediction falls back almost entirely to the trend. Goulard et al. [2017] found TC within 94–97% of BP’s efficiency on sparse weights, and closer still as more neighbors are missing. So before relying on BP, compare the two on held-out data, stratified by how many of each unit’s neighbors were observed. We repeat the exercise over eight simulated maps and report each stratum’s gain with its Monte Carlo standard error.
A = (sp.csr_matrix(W_all.sparse) != 0).astype(int)
rows = []
for rep in range(8):
rng = np.random.default_rng(rep)
g = simulate_sar(
n_side=GRID,
rho=0.6,
beta=np.array([1.0, 2.0]),
sigma=1.0,
seed=rep,
create_gdf=True,
geometry_type="polygon",
contiguity="rook",
)
h = held_out_blocks(GRID, rng)
tr = g[~h]
m = SAR(
formula="y ~ X_1",
data=tr,
W=Graph.build_contiguity(tr, rook=True).transform("r"),
)
m.fit(draws=500, tune=500, chains=2, random_seed=rep, progressbar=False)
o = np.flatnonzero(h)
pp = m.predict(g[h], W_all, oos=o, random_seed=rep).predictions
y = g["y"].to_numpy()[o]
rows.append(
pd.DataFrame(
{
"observed_neighbors": np.asarray(A[o][:, ~h].sum(axis=1)).ravel(),
"se_bp": (y - pp["y_bp"].mean(("chain", "draw")).values) ** 2,
"se_tc": (y - pp["y_tc"].mean(("chain", "draw")).values) ** 2,
}
)
)
errors = pd.concat(rows, ignore_index=True)
errors["gain"] = errors["se_tc"] - errors["se_bp"]
errors.groupby("observed_neighbors").agg(
n=("gain", "size"),
mse_bp=("se_bp", "mean"),
mse_tc=("se_tc", "mean"),
gain=("gain", "mean"),
gain_se=("gain", "sem"),
).round(3)
| n | mse_bp | mse_tc | gain | gain_se | |
|---|---|---|---|---|---|
| observed_neighbors | |||||
| 0 | 159 | 1.256 | 1.298 | 0.042 | 0.028 |
| 1 | 254 | 1.296 | 1.460 | 0.164 | 0.063 |
| 2 | 99 | 1.089 | 1.614 | 0.525 | 0.106 |
Read gain against gain_se. For units with no observed neighbor the gain
is within two standard errors of zero; BP still draws on neighbors of
neighbors, but not enough to matter. The gain grows with each observed
neighbor. If your held-out units are mostly surrounded by other
missing units, the cheap trend predictor is as good as the correction; if
they are scattered among observed ones, the correction pays.
When the conditional is not what you want¶
predict_in_sample()gives each fitted unit’s leave-one-out conditional, the in-sample BP of Goulard et al. [2017]. It conditions on a posterior fitted to all the data, so it smooths rather than validates.To score held-out predictive accuracy across models, use spatial block cross-validation, which refits on each fold and evaluates this same conditional density.
The parameters come from the observed units’ own weights, row-standardized after the new units are removed, and the prediction uses the full weights: the feasible practice of Goulard et al. [2017]. When the missing units are scattered, many observed units lose neighbors and the fit drifts. On a 10 × 10 grid with 12% of units missing in a checkerboard, the posterior mean of ρ fell from 0.57 to 0.42, and 90% intervals covered 95–96% of held-out values instead of 90%. Compact missing regions cost far less.