How to estimate origin–destination flow models

You have flows between places — trade, migration, commuting, foot traffic — and you want to know whether a flow into one destination depends on flows into its neighbours, on flows out of neighbouring origins, or both.

SARFlow estimates all three spatial parameters freely; SARFlow(separable=True) pins \(\rho_w = -\rho_d\rho_o\), which removes a weakly-identified ridge and is the better default. Both implement the LeSage–Fischer (2008) SAR flow framework. Equations, the full class list and the log-determinant options are in Supported Models.

Set up

import warnings

import arviz as az
import matplotlib.pyplot as plt
import numpy as np
import pandas as pd

from neighbayes.dgp import simulate_sar_flow
from neighbayes.graph import flow_design_matrix
from neighbayes.models import SARFlow

warnings.filterwarnings("ignore")
az.style.use("arviz-variat")
rng = np.random.default_rng(42)
/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

Build the flow data and design matrix

We simulate flow data on \(n = 12\) spatial units, giving \(N = 144\) O-D pairs. When neither G nor gdf is supplied, simulate_sar_flow synthesises a point grid, builds a row-standardised KNN graph (knn_k=4 by default) and computes the pairwise distance matrix used for the gravity-style log_distance regressor.

True parameters

Parameter

Value

ρ_d

0.35

ρ_o

0.25

ρ_w

0.10

β_d

[1.0, −0.5]

β_o

[0.5, 0.3]

σ

1.0

γ_dist (log_distance coef.)

−0.5 (default)

# True parameters (matching the table above)
RHO_D = 0.35
RHO_O = 0.25
RHO_W = 0.10
BETA_D = [1.0, -0.5]
BETA_O = [0.5, 0.3]
SIGMA = 1.0

# Generate synthetic flow data (auto-builds KNN graph + distance matrix)
data = simulate_sar_flow(
    n=20,
    rho_d=RHO_D,
    rho_o=RHO_O,
    rho_w=RHO_W,
    beta_d=BETA_D,
    beta_o=BETA_O,
    sigma=SIGMA,
    seed=42,
)

n = 20
N = n * n
G = data["G"]
gdf = data["gdf"]

print(f"Generated {N} O-D flows on {n} spatial units")
print(f"Design matrix: {data['X'].shape}, columns: {data['col_names']}")
print(f"Design: k_d={data['design'].k_d}, k_o={data['design'].k_o}")
Generated 400 O-D flows on 20 spatial units
Design matrix: (400, 9), columns: ['intercept', 'intra_indicator', 'dest_x0', 'dest_x1', 'orig_x0', 'orig_x1', 'intra_x0', 'intra_x1', 'log_distance']
Design: k_d=2, k_o=2
y_obs = data["y_vec"]  # observed (positive) flows
y_vec = np.log(y_obs)  # latent SAR scale (DGP default is lognormal)
X = data["X"]  # (N, p) design matrix (incl. log_distance column)
col_names = data["col_names"]
G = data["G"].transform("r")  # row-standardised KNN graph synthesised by the DGP
gdf = data["gdf"]  # synthetic point GeoDataFrame

print(f"Flow observations: N = {N}  ({n}×{n})")
print(f"Design matrix shape: {X.shape}")
print(f"Column names: {col_names}")
print(f"Last column ({col_names[-1]}) coefficient (gamma_dist) = {data['gamma_dist']}")
print(
    f"\ny (observed) summary:  min={y_obs.min():.2f}  mean={y_obs.mean():.2f}  max={y_obs.max():.2f}"
)
print(
    f"y (log scale) summary:  min={y_vec.min():.2f}  mean={y_vec.mean():.2f}  max={y_vec.max():.2f}"
)
Flow observations: N = 400  (20×20)
Design matrix shape: (400, 9)
Column names: ['intercept', 'intra_indicator', 'dest_x0', 'dest_x1', 'orig_x0', 'orig_x1', 'intra_x0', 'intra_x1', 'log_distance']
Last column (log_distance) coefficient (gamma_dist) = -0.5

y (observed) summary:  min=0.00  mean=2.91  max=134.95
y (log scale) summary:  min=-5.34  mean=-0.56  max=4.90

Note — lognormal default (since v0.2). simulate_sar_flow now returns strictly-positive flows by default, drawn from \(y = \exp(\eta)\) where \(\eta = A^{-1}(X\beta + \varepsilon)\) is the latent SAR-filtered linear predictor (also exposed as data["eta_vec"]). The Gaussian-likelihood flow models in this notebook (OLSFlow, and SARFlow unrestricted or separable) operate on the latent scale, so we fit on np.log(data["y_vec"]). Pass distribution="normal" to recover the legacy Gaussian-on-y behaviour.

# Visualise the flow matrix (observed scale) and the latent log-scale histogram
fig, axes = plt.subplots(1, 2, figsize=(10, 4))

im = axes[0].imshow(y_obs.reshape(n, n), cmap="YlOrRd")
axes[0].set_title("Simulated flow matrix $Y$ (origin × destination)")
axes[0].set_xlabel("Destination")
axes[0].set_ylabel("Origin")
plt.colorbar(im, ax=axes[0])

axes[1].hist(y_vec, bins=30, edgecolor="white")
axes[1].set_title(r"Distribution of $\log y_{ij}$ (latent SAR scale)")
axes[1].set_xlabel("log flow")
axes[1].set_ylabel("Count")

# plt.tight_layout()
plt.show()
../_images/f3bf205f0124700110aca1d1104b2475b27df616fc3de324bb741b1fc6deb203.png

Fit the unrestricted model

SARFlow places a Dirichlet prior on \((ρ_d, ρ_o, ρ_w)\) that enforces positivity and the stability constraint \(\rho_d + \rho_o + \rho_w \leq 1\) exactly, using the stick-breaking transformation for NUTS efficiency.

The log-determinant \(\log|A|\) is evaluated via the Barry–Pace trace-stochastic method, which requires only sparse matrix–vector products.

sar_flow = SARFlow(
    y_vec,
    X,
    G,
    col_names=col_names,
    nonnegative_dependence=True,  # Dirichlet stability prior,
)

idata_sar = sar_flow.fit(
    sampler="nuts",
    draws=1000,
    tune=1000,
    chains=4,
    target_accept=0.9,
    random_seed=42,
    progressbar=True,
)
Initializing NUTS using jitter+adapt_diag...
Multiprocess sampling (4 chains in 2 jobs)
NUTS: [rho_simplex, beta, sigma2]
/home/runner/micromamba/envs/test/lib/python3.14/site-packages/pytensor/link/numba/dispatch/basic.py:234: UserWarning: Numba will use object mode to run FlowLogdetOp{_op_id=0}'s perform method. Set `pytensor.config.compiler_verbose = True` to see more details.
  warnings.warn(
/home/runner/micromamba/envs/test/lib/python3.14/site-packages/pytensor/link/numba/dispatch/basic.py:234: UserWarning: Numba will use object mode to run FlowLogdetOp{_op_id=0}'s perform method. Set `pytensor.config.compiler_verbose = True` to see more details.
  warnings.warn(
/home/runner/micromamba/envs/test/lib/python3.14/site-packages/pytensor/link/numba/dispatch/basic.py:234: UserWarning: Numba will use object mode to run FlowLogdetOp{_op_id=0}'s perform method. Set `pytensor.config.compiler_verbose = True` to see more details.
  warnings.warn(
/home/runner/micromamba/envs/test/lib/python3.14/site-packages/pytensor/link/numba/dispatch/basic.py:234: UserWarning: Numba will use object mode to run FlowLogdetOp{_op_id=0}'s perform method. Set `pytensor.config.compiler_verbose = True` to see more details.
  warnings.warn(
Sampling 4 chains for 1_000 tune and 1_000 draw iterations (4_000 + 4_000 draws total) took 591 seconds.

# Posterior summary for the spatial autoregressive parameters
summary_rho = sar_flow.summary(var_names=["rho_d", "rho_o", "rho_w"])
print("=== SARFlow: spatial autoregressive parameters ===")
print(summary_rho.to_string())

# Compare to true values
print(f"\nTrue values:  rho_d={RHO_D}  rho_o={RHO_O}  rho_w={RHO_W}")
=== SARFlow: spatial autoregressive parameters ===
        mean     sd eti89_lb eti89_ub ess_bulk ess_tail r_hat mcse_mean  mcse_sd
rho_d  0.311  0.063     0.21     0.41     2759     2673  1.00    0.0012  0.00089
rho_o  0.149  0.063    0.045     0.25     1685     1744  1.00    0.0015    0.001
rho_w  0.163  0.083    0.038      0.3     1607     1554  1.00     0.002   0.0011

True values:  rho_d=0.35  rho_o=0.25  rho_w=0.1
# Full coefficient summary
summary_beta = sar_flow.summary(var_names=["beta", "sigma"])
print("=== SARFlow: regression coefficients ===")
print(summary_beta.to_string())
=== SARFlow: regression coefficients ===
                     mean        sd  eti89_lb  eti89_ub     ess_bulk     ess_tail     r_hat mcse_mean   mcse_sd
intercept        0.310617   0.21969 -0.039695  0.657802  2356.509305   2537.25192  1.002035  0.004525  0.003277
intra_indicator  0.243489  0.324955 -0.277826  0.750079  2924.199752  2817.414425  1.000483  0.006009  0.004737
dest_x0          1.112525  0.108831  0.937203  1.286071  1964.911192   2170.34189  1.002533  0.002452  0.001744
dest_x1         -0.628277  0.084888 -0.765488 -0.495728  2278.522536  2697.940676  1.000694   0.00178  0.001245
orig_x0          0.504619  0.086691  0.367252  0.640063  3276.498515  2849.325058  1.000144   0.00152   0.00144
orig_x1          0.331674  0.073988  0.215962  0.453418  4191.521951  2816.182609   1.00092  0.001143  0.001233
intra_x0         0.047831  0.302559 -0.421264  0.536679  3560.527686  3026.802226  1.001941  0.005073  0.005028
intra_x1         -0.14265  0.328562 -0.667358  0.387165   3652.64996  2987.351683  0.999742  0.005442  0.005293
log_distance    -0.879327  0.196805 -1.197542 -0.569466  2339.141506  2412.148493  1.001732  0.004074  0.003077
sigma               1.001     0.036      0.95       1.1         3764         3008      1.00    0.0006   0.00058
# Trace plots for the three ρ parameters
az.plot_trace_dist(
    idata_sar,
    var_names=["rho_d", "rho_o", "rho_w"],
    figure_kwargs={"figsize": (10, 6)},
)
plt.suptitle("SARFlow — posterior traces", y=1.01)
plt.tight_layout()
plt.show()
../_images/1eaae56c5042003c8223c1c6ffad235b05092f02bf83a1698d0dd1d1defad1bd.png
# Posterior densities with true-value markers
pc = az.plot_dist(
    idata_sar,
    var_names=["rho_d", "rho_o", "rho_w"],
    ci_prob=0.94,
    figure_kwargs={"figsize": (12, 3)},
)
az.add_lines(pc, {"rho_d": RHO_D, "rho_o": RHO_O, "rho_w": RHO_W})
plt.suptitle("SARFlow — posterior distributions (lines = true values)", y=1.02)
plt.show()
../_images/3f7fe9205281c4b0d8bd9cc80e5e1b268e66cf06312c68a9038d137654c5f49b.png

Fit the separable model

SARFlow(separable=True) imposes the constraint \(\rho_w = -\rho_d \rho_o\), yielding:

  • Exact log-det via eigenvalues of the small \(n \times n\) matrix \(W\) — no Monte Carlo traces needed.

  • Two free parameters (\(\rho_d\), \(\rho_o\)) instead of three.

  • Typically faster mixing because the posterior geometry is simpler.

We generate new data that satisfies the constraint (\(\rho_w = -\rho_d\rho_o = -0.12\)) to give the model the best chance at recovery.

# True parameters for the separable model (asymmetric for identifiability)
RHO_D_SEP = 0.40
RHO_O_SEP = 0.30
RHO_W_SEP = -RHO_D_SEP * RHO_O_SEP  # = -0.12 (constraint)

print(
    f"Separable true values:  rho_d={RHO_D_SEP}  rho_o={RHO_O_SEP}"
    f"  rho_w=-rho_d*rho_o={RHO_W_SEP:.4f}"
)

data_sep = simulate_sar_flow(
    n=n,
    G=G,
    rho_d=RHO_D_SEP,
    rho_o=RHO_O_SEP,
    beta_d=BETA_D,
    beta_o=BETA_O,
    sigma=SIGMA,
    seed=7,
    separable=True,
)

y_sep = np.log(data_sep["y_vec"])  # latent SAR scale (lognormal default)
X_sep = data_sep["X"]
cn_sep = data_sep["col_names"]

print(
    f"\ny_sep summary:  min={y_sep.min():.2f}  mean={y_sep.mean():.2f}  max={y_sep.max():.2f}"
)
Separable true values:  rho_d=0.4  rho_o=0.3  rho_w=-rho_d*rho_o=-0.1200

y_sep summary:  min=-9.82  mean=-3.48  max=1.70
sep_flow = SARFlow(
    y_sep,
    X_sep,
    G,
    separable=True,
    col_names=cn_sep,
    # logdet_method=None (auto) selects the separable Kronecker method
)

idata_sep = sep_flow.fit(
    draws=1000,
    tune=1000,
    chains=4,
    target_accept=0.9,
    random_seed=42,
    progressbar=True,
    # Stored only on request (as in PyMC); the LOO comparison below needs it.
    idata_kwargs={"log_likelihood": True},
)
Initializing NUTS using jitter+adapt_diag...
Multiprocess sampling (4 chains in 2 jobs)
NUTS: [rho_d, rho_o, beta, sigma2]
Sampling 4 chains for 1_000 tune and 1_000 draw iterations (4_000 + 4_000 draws total) took 10 seconds.

summary_sep = sep_flow.summary(var_names=["rho_d", "rho_o"])
print("=== SARFlow (separable): spatial autoregressive parameters ===")
print(summary_sep.to_string())
print(
    f"\nTrue values:  rho_d={RHO_D_SEP}  rho_o={RHO_O_SEP}"
    f"  (rho_w = -rho_d*rho_o = {RHO_W_SEP:.4f} is derived)"
)
=== SARFlow (separable): spatial autoregressive parameters ===
        mean     sd eti89_lb eti89_ub ess_bulk ess_tail r_hat mcse_mean  mcse_sd
rho_d  0.375  0.049      0.3     0.45     3367     3227  1.00   0.00085  0.00071
rho_o  0.239  0.066     0.13     0.35     2547     2647  1.00    0.0013  0.00099

True values:  rho_d=0.4  rho_o=0.3  (rho_w = -rho_d*rho_o = -0.1200 is derived)
az.plot_trace_dist(
    idata_sep,
    var_names=["rho_d", "rho_o"],
    figure_kwargs={"figsize": (10, 4)},
)
plt.suptitle("SARFlow (separable) — posterior traces", y=1.01)
plt.tight_layout()
plt.show()
../_images/c7c73cb945a577fe4fb2752734e5c8f51ec6bde15d099945322ba7506ac499da.png
pc = az.plot_dist(
    idata_sep,
    var_names=["rho_d", "rho_o"],
    ci_prob=0.94,
    figure_kwargs={"figsize": (8, 3)},
)
az.add_lines(pc, {"rho_d": RHO_D_SEP, "rho_o": RHO_O_SEP})
plt.suptitle(
    "SARFlow (separable) — posterior distributions (lines = true values)", y=1.02
)
plt.show()
../_images/c34d3bfea64079da1997b13771e13d578b718e601e965ab75da662794a3c3194.png

Understand what is in the design matrix

The flow_design_matrix helper builds the standard LeSage O-D design matrix with destination, origin, and intra-zonal coefficient blocks. Each column of the regional attribute matrix \(X\) (shape \(n \times k\)) produces three columns in the full design matrix: one for destination effects, one for origin effects, and one for intra-zonal effects.

Column group

Construction

Interpretation

intercept

\(\mathbf{1}_N\)

global mean flow

intra_indicator

\(\text{vec}(I_n)\)

intra-zonal dummy

dest_*

\(\iota_n \otimes X\)

destination characteristics

orig_*

\(X \otimes \iota_n\)

origin characteristics

intra_*

\(\text{diag}(I_n) \cdot (I_n \otimes X)\)

intra-zonal attr.

log_distance

\(\log(1 + d_{ij})\)

gravity distance decay

By default the DGP appends a log_distance column built from \(\log(1 + d_{ij})\) and assigns it the coefficient gamma_dist=-0.5 (set gamma_dist=0.0 to neutralise the effect). When you build a design matrix by hand via flow_design_matrix, pass dist=... together with log_distance=True to include the same column.

You can also pass a pre-built pd.DataFrame directly as X — column names are inferred automatically.

# Build a design matrix from scratch using regional attributes
X_regional = rng.standard_normal((n, 2))  # n × k attribute matrix
dm = flow_design_matrix(X_regional, col_names=["income", "pop"])

print(f"Regional attribute matrix: {X_regional.shape}  (n × k)")
print(f"Full O-D design matrix:    {dm.combined.shape}  (N × p)")
print(f"\nColumn names:\n  {dm.feature_names}")

pd.DataFrame(dm.combined[:6], columns=dm.feature_names).round(3)
Regional attribute matrix: (20, 2)  (n × k)
Full O-D design matrix:    (400, 8)  (N × p)

Column names:
  ['intercept', 'intra_indicator', 'dest_income', 'dest_pop', 'orig_income', 'orig_pop', 'intra_income', 'intra_pop']
intercept intra_indicator dest_income dest_pop orig_income orig_pop intra_income intra_pop
0 1.0 1.0 0.305 -1.040 0.305 -1.04 0.305 -1.04
1 1.0 0.0 0.750 0.941 0.305 -1.04 0.000 0.00
2 1.0 0.0 -1.951 -1.302 0.305 -1.04 -0.000 -0.00
3 1.0 0.0 0.128 -0.316 0.305 -1.04 0.000 -0.00
4 1.0 0.0 -0.017 -0.853 0.305 -1.04 -0.000 -0.00
5 1.0 0.0 0.879 0.778 0.305 -1.04 0.000 0.00

Read the spillovers

The flow SAR model has a rich effects decomposition due to :cite:t:thomas-agnan2014SpatialEconometric (chapter 83, §83.5). For each regional predictor \(p\), a unit shock to \(X_d^{(p)}\) (destination side) and a unit shock to \(X_o^{(p)}\) (origin side) propagate through the spatial filter \(A = I_N - \rho_d W_d - \rho_o W_o - \rho_w W_w\) to produce five scalar summaries (averaged across the \(n\) perturbed regions):

Effect

Symbol

Cells aggregated

Origin

OE

flows whose origin matches the perturbed region

Destination

DE

flows whose destination matches the perturbed region

Intra

IE

the diagonal \((j, j)\) flow of the perturbed region

Network

NE

all remaining flows

Total

TE

OE + DE + IE + NE

The high-level wrapper model.impacts() returns a tidy DataFrame. Three modes are supported:

  • mode="auto" (default) — combined (sum of dest+orig) when \(X_o = X_d\), otherwise separate.

  • mode="combined" — always sum dest and orig contributions.

  • mode="separate" — always report both sides (Thomas-Agnan §83.5.2).

When intra_* columns are present the destination shock also carries \(\beta_\text{intra}\) at the diagonal cell, since the design matrix sets X_intra = intra_indicator · X_dest.

# Combined effects (default for symmetric Xo == Xd designs).
effects_df = sar_flow.impacts(mode="combined")
effects_df.round(4)
mean ci_lower ci_upper bayes_pvalue
predictor side effect
x0 combined origin 0.8192 0.5935 1.0591 0.0000
x1 combined origin 0.4359 0.2330 0.6421 0.0000
x0 combined destination 1.3960 1.2013 1.6249 0.0000
x1 combined destination -0.7530 -0.9257 -0.5791 0.0000
x0 combined intraunit 0.1131 0.0824 0.1456 0.0000
x1 combined intraunit -0.0224 -0.0544 0.0097 0.1690
x0 combined network 2.1146 1.0664 4.0610 0.0000
x1 combined network -0.5004 -1.0773 -0.1122 0.0050
x0 combined total 4.4430 3.1209 6.7138 0.0000
x1 combined total -0.8400 -1.6594 -0.2075 0.0065
# Small sampler settings used for the demo fits below.
SAMPLE_KWARGS_DEMO = dict(
    draws=200, tune=200, chains=2, random_seed=0, progressbar=False
)

5.1 Asymmetric origin / destination attributes

When destination and origin attribute matrices have different numbers of columns (k_d ≠ k_o), pass beta_d and beta_o with different lengths to simulate_sar_flow. The design matrix layout becomes:

intercept | intra_indicator | dest_*(k_d) | orig_*(k_o) | intra_*(k_d) | dist

The model auto-detects k_d and k_o from column name prefixes (dest_* vs orig_*). impacts() reports destination and origin effects separately when k_d ≠ k_o, since the predictors are different variables.

from neighbayes.dgp import simulate_sar_flow

# Asymmetric: 2 destination attributes, 1 origin attribute
data_asym = simulate_sar_flow(
    n=5,
    rho_d=0.2,
    rho_o=0.15,
    rho_w=0.05,
    beta_d=[1.0, -0.5],  # k_d = 2
    beta_o=[0.5],  # k_o = 1
    sigma=0.5,
    seed=11,
)
G_asym = data_asym["G"]
print(f"k_d={data_asym['design'].k_d}, k_o={data_asym['design'].k_o}")
print(f"Columns: {data_asym['col_names']}")

model_asym = SARFlow(
    np.log(data_asym["y_vec"]),
    data_asym["X"],
    G_asym,
    col_names=data_asym["col_names"],
)
print("shared_od_covariates =", model_asym._shared_od_covariates)
model_asym.fit(**SAMPLE_KWARGS_DEMO)
model_asym.impacts().round(4)  # auto -> separate
k_d=2, k_o=1
Columns: ['intercept', 'intra_indicator', 'dest_x0', 'dest_x1', 'orig_y0', 'intra_x0', 'intra_x1', 'log_distance']
shared_od_covariates = False
mean ci_lower ci_upper bayes_pvalue
predictor side effect
x0 dest origin 0.4906 0.0576 1.8208 0.015
x1 dest origin -0.2532 -1.0131 -0.0264 0.005
x0 dest destination 1.2207 0.4027 2.5570 0.005
x1 dest destination -0.7569 -1.7492 -0.3368 0.000
x0 dest intraunit 0.3337 0.0622 0.7839 0.030
x1 dest intraunit -0.1338 -0.3590 0.0026 0.060
x0 dest network 1.9163 0.2335 7.1425 0.005
x1 dest network -1.1154 -4.2690 -0.1627 0.000
x0 dest total 3.9613 0.9284 11.9867 0.005
x1 dest total -2.2594 -7.2128 -0.6491 0.000
y0 orig origin 0.7214 -0.0052 1.6944 0.055
destination 0.1967 -0.0019 0.9148 0.055
intraunit 0.1803 -0.0013 0.4236 0.055
network 0.7870 -0.0077 3.6593 0.055
total 1.8854 -0.0166 7.2861 0.055
# You can also build asymmetric designs directly with flow_design_matrix_asymmetric
from neighbayes.graph import flow_design_matrix_asymmetric

rng_asym = np.random.default_rng(7)
n_demo = 5
Xd = rng_asym.standard_normal((n_demo, 2))  # 2 destination variables
Xo = rng_asym.standard_normal((n_demo, 1))  # 1 origin variable

dm = flow_design_matrix_asymmetric(Xd, Xo)
print(f"Design shape: {dm.combined.shape}")
print(f"k_d={dm.k_d}, k_o={dm.k_o}")
print(f"Feature names: {dm.feature_names}")
Design shape: (25, 7)
k_d=2, k_o=1
Feature names: ['intercept', 'intra_indicator', 'dest_x0', 'dest_x1', 'orig_y0', 'intra_x0', 'intra_x1']

5.2 Non-spatial OLS gravity baseline (OLSFlow)

OLSFlow is the conventional log-linear gravity model (Thomas-Agnan & LeSage 2014, eq. 83.2): no spatial-lag terms, just \(y = X \beta + \varepsilon\) with iid Gaussian errors. It uses the same impacts() API and reproduces the closed-form expressions in Table 83.1 (with \(A = I_N\)):

\[ \mathrm{TE} = \beta_d + \beta_o, \quad \mathrm{OE} = \tfrac{n-1}{n}\beta_o, \quad \mathrm{DE} = \tfrac{n-1}{n}\beta_d, \quad \mathrm{IE} = (\beta_d + \beta_o + \beta_\text{intra}) / n, \quad \mathrm{NE} = 0. \]
from neighbayes.models import OLSFlow

ols_flow = OLSFlow(y_vec, X, G, col_names=col_names)
ols_flow.fit(**SAMPLE_KWARGS_DEMO)
ols_flow.impacts(mode="combined").round(4)
Initializing NUTS using jitter+adapt_diag...
Multiprocess sampling (2 chains in 2 jobs)
NUTS: [beta, sigma2]
Sampling 2 chains for 200 tune and 200 draw iterations (400 + 400 draws total) took 2 seconds.
We recommend running at least 4 chains for robust computation of convergence diagnostics
The rhat statistic is larger than 1.01 for some parameters. This indicates problems during sampling. See https://arxiv.org/abs/1903.08008 for details
mean ci_lower ci_upper bayes_pvalue
predictor side effect
x0 combined origin 0.6476 0.5151 0.7645 0.000
x1 combined origin 0.4800 0.3290 0.6488 0.000
x0 combined destination 1.2117 1.0827 1.3393 0.000
x1 combined destination -0.6892 -0.8385 -0.5541 0.000
x0 combined intraunit 0.0969 0.0668 0.1265 0.000
x1 combined intraunit -0.0117 -0.0463 0.0214 0.505
x0 combined network 0.0000 0.0000 0.0000 0.000
x1 combined network 0.0000 0.0000 0.0000 0.000
x0 combined total 1.9562 1.7561 2.1254 0.000
x1 combined total -0.2209 -0.4513 -0.0082 0.040

What to check before trusting the output

Good practice after any Bayesian fit: check \(\hat{R}\) (should be \(< 1.01\)) and effective sample size (ESS > 400 per chain).

for label, idata in [("SARFlow", idata_sar), ("SARFlow (separable)", idata_sep)]:
    diag = az.summary(idata, var_names=["rho_d", "rho_o"], ci_kind="hdi", ci_prob=0.94)
    rhat_ok = (diag["r_hat"] < 1.01).all()
    ess_ok = (diag["ess_bulk"] > 400).all()
    print(f"{label:25s}  r_hat<1.01: {rhat_ok}   ess_bulk>400: {ess_ok}")
    print(diag[["mean", "sd", "hdi94_lb", "hdi94_ub", "ess_bulk", "r_hat"]].to_string())
    print()
SARFlow                    r_hat<1.01: True   ess_bulk>400: True
        mean     sd hdi94_lb hdi94_ub ess_bulk r_hat
rho_d  0.311  0.063      0.2     0.43     2759  1.00
rho_o  0.149  0.063    0.013     0.25     1685  1.00

SARFlow (separable)        r_hat<1.01: True   ess_bulk>400: True
        mean     sd hdi94_lb hdi94_ub ess_bulk r_hat
rho_d  0.375  0.049     0.28     0.47     3367  1.00
rho_o  0.239  0.066     0.12     0.36     2547  1.00

Spatial-parameter adequacy

Flow models have three spatial scalars (\(\rho_d\), \(\rho_o\), \(\rho_w\)), and each is prone to the slow-mixing behaviour discussed in Wolf, Anselin & Arribas-Bel (2018) [Wolf et al., 2018]. The spatial_mcmc_diagnostic helper auto-detects all three and reports ESS, sampler yield, \(\hat{R}\), and HPDI stability.

from neighbayes.diagnostics import spatial_mcmc_diagnostic

spatial_mcmc_diagnostic(sar_flow, emit_warnings=False).to_frame()
ess_bulk ess_tail r_hat mcse_mean yield_pct hpdi_drift_pct adequate
parameter
rho_d 2759.513478 2673.269207 1.000829 0.001191 68.987837 5.687419 False
rho_o 1685.912884 1744.260670 1.002967 0.001521 42.147822 2.998170 True
rho_w 1607.282214 1554.646630 1.002226 0.001976 40.182055 1.014808 True

Compare the two specifications

The WAIC / LOO-CV scores can be used to compare the unrestricted and the separable SARFlow when both are estimated on the same data. A lower ELPD (expected log pointwise predictive density) indicates a worse-fitting model.

Note: here we fit SARFlow to the separable data to make the comparison meaningful — the separable model is nested in the unrestricted one.

# Fit unrestricted SARFlow on the same separable data for a fair comparison
sar_flow_on_sep = SARFlow(
    y_sep,
    X_sep,
    G,
    col_names=cn_sep,
)
idata_sar_on_sep = sar_flow_on_sep.fit(
    draws=1000,
    tune=1000,
    chains=4,
    target_accept=0.9,
    random_seed=42,
    progressbar=True,
    idata_kwargs={"log_likelihood": True},
)
Gibbs sampling (flow): 4 chains for 1,000 tune and 1,000 draw iterations (4 x 2,000 = 8,000 draws total)

Sampling took 13s (631 draws/s)
# LOO-CV comparison (requires log-likelihood in idata)
try:
    loo_sar = az.loo(idata_sar_on_sep)
    loo_sep = az.loo(idata_sep)
    comparison = az.compare(
        {"SARFlow (3 ρ)": idata_sar_on_sep, "SARFlow (separable)": idata_sep}
    )
    print("LOO-CV model comparison:")
    print(comparison[["elpd", "p", "elpd_diff", "weight", "se", "dse"]].to_string())
except Exception as e:
    print(f"LOO not available (log-likelihood not stored): {e}")
    print('Tip: pass idata_kwargs={"log_likelihood": True} to fit() for LOO.')
LOO-CV model comparison:
                      elpd    p  elpd_diff  weight    se  dse
SARFlow (separable) -540.0  8.9        0.0     1.0  14.0  0.0
SARFlow (3 ρ)       -550.0  9.4       -3.0     0.0  14.0  2.0

Allow negative spillovers

By default SARFlow uses a Dirichlet prior that forces \(\rho_d, \rho_o, \rho_w \geq 0\) and \(\rho_d + \rho_o + \rho_w \leq 1\). Setting nonnegative_dependence=False allows negative spillovers via independent Uniform(-1, 1) priors plus a differentiable stability wall potential.

Use nonnegative_dependence=False when competitive effects (e.g. negative network parameter) are theoretically expected.

# Fit with nonnegative_dependence=False to allow negative rho values
sar_flow_neg = SARFlow(
    y_vec,
    X,
    G,
    col_names=col_names,
    nonnegative_dependence=False,  # Uniform(-1,1) priors + stability potential
)
idata_neg = sar_flow_neg.fit(
    draws=800,
    tune=1000,
    chains=4,
    target_accept=0.95,
    random_seed=42,
    progressbar=True,
)

summary_neg = sar_flow_neg.summary(ci_kind="hdi", ci_prob=0.94)
print("=== SARFlow (nonnegative_dependence=False) ===")
print(summary_neg[["mean", "sd", "hdi94_lb", "hdi94_ub", "r_hat"]].to_string())
Gibbs sampling (flow): 4 chains for 1,000 tune and 800 draw iterations (4 x 1,800 = 7,200 draws total)

Sampling took 26s (280 draws/s)
=== SARFlow (nonnegative_dependence=False) ===
                     mean        sd  hdi94_lb  hdi94_ub     r_hat
rho_d               0.313     0.065      0.19      0.43      1.00
rho_o               0.151     0.069     0.024      0.28      1.00
rho_w               0.153     0.092    -0.013      0.33      1.00
sigma               1.002    0.0361      0.94       1.1      1.00
intercept        0.323882  0.217598 -0.085505  0.731325  0.999572
intra_indicator  0.229508  0.332525 -0.399134  0.850958  1.000708
dest_x0          1.108096  0.114131  0.883777  1.308914  1.000285
dest_x1         -0.624999    0.0904 -0.787936  -0.44866  1.000453
orig_x0          0.497901    0.0862  0.334421   0.65772   1.00076
orig_x1          0.332503  0.075318  0.195852  0.478992   0.99994
intra_x0         0.061162   0.30397  -0.49742  0.635618   1.00051
intra_x1         -0.15145  0.324395 -0.749419  0.462525  1.000489
log_distance    -0.890899  0.198512 -1.259171 -0.515693  1.000037

Test whether the spatial terms are needed

The Bayesian Lagrange-multiplier tests ask whether an aspatial gravity model leaves spatial dependence in its residuals. Each is a score test of the lag-flow model

\[ y = \rho_d W_d y + \rho_o W_o y + \rho_w W_w y + X\beta + \varepsilon, \qquad W_d = I_n \otimes W,\; W_o = W \otimes I_n,\; W_w = W \otimes W, \]

at a fitted OLSFlow, where every \(\rho\) is zero. The score of direction \(k\) is \((W_k y)^\top e/\sigma^2 - \operatorname{tr} W_k\), made orthogonal to the coefficients and the variance the null estimates. Its information needs only traces of the \(n \times n\) matrix \(W\), so the \(n^2\) pairs never form a Kronecker product. The reported statistic is the test at the posterior-mean parameters (Doğan, Taşpınar & Bera 2021). A robust test also removes the other two directions (Bera & Yoon 1993): Robust-LM-Flow-Destination asks for a destination lag whether or not origin and network lags are present.

diagnostics = ols_flow.spatial_diagnostics()
print("Recommended:", ols_flow.spatial_diagnostics_decision(format="model"))
diagnostics.round(3)
Recommended: SARFlow
statistic median df p_value ci_lower ci_upper
test
LM-Flow-Destination 53.655 53.294 1 0.000 40.824 72.218
LM-Flow-Origin 32.335 32.127 1 0.000 24.679 43.929
LM-Flow-OD 48.035 47.980 1 0.000 36.202 65.093
LM-Flow-Joint 99.204 99.125 3 0.000 76.317 133.556
Robust-LM-Flow-Destination 34.591 34.352 1 0.000 26.164 47.084
Robust-LM-Flow-Origin 22.296 22.128 1 0.000 16.936 29.937
Robust-LM-Flow-OD 11.161 11.140 1 0.001 7.790 16.042

spatial_diagnostics_decision() reads the joint test: dependence in any direction recommends SARFlow, and its absence keeps OLSFlow.

The tests are defined at the Gaussian aspatial null only. A fitted SARFlow already estimates the lags they test, and the count flows (NegBinFlow and its spatial forms) have no flow tests yet, so spatial_diagnostics() raises for them.

Panel analogues

An OLSFlow panel (fitted with T) has the same suite under the bayesian_panel_lm_flow_* names (Panel-LM-Flow-* in its table). Its scores are those of the Lee and Yu (2010) transformed likelihood that the demeaned panel gives: pair effects cost one period of the Jacobian, and time effects remove each period’s common level from its lags.

Choosing between the flow models

Data characteristic

Recommended model

No prior on the sign of the dependence

SARFlow(nonnegative_dependence=False)

Nonnegative dependence expected

SARFlow(nonnegative_dependence=True)

Separability plausible, fast inference needed

SARFlow(separable=True)

Count/non-negative flows

SARNegBinFlow, unrestricted or separable=True

Counts with no conditional overdispersion

SARPoissonFlow(separable=True) — see How to estimate Poisson origin–destination flow models

Aspatial count baseline

NegBinFlow

The separable variants pin \(\rho_w = -\rho_d\rho_o\), which removes the weakly-identified three-\(\rho\) ridge; prefer them unless \(\rho_w\) is itself the object of interest. Full equations, constructor signatures and the log-determinant options are in Supported Models.

See also