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.

See also