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_flownow 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 asdata["eta_vec"]). The Gaussian-likelihood flow models in this notebook (OLSFlow, andSARFlowunrestricted or separable) operate on the latent scale, so we fit onnp.log(data["y_vec"]). Passdistribution="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()
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()
# 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()
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()
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()
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\)):
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
SARFlowto 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
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 |
|
Nonnegative dependence expected |
|
Separability plausible, fast inference needed |
|
Count/non-negative flows |
|
Counts with no conditional overdispersion |
|
Aspatial count baseline |
|
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¶
Supported Models — equations, the full flow class list, and the
resolventlog-determinant defaultHow to estimate Poisson origin–destination flow models — flow counts without a dispersion parameter
How to estimate panel flow models — the same models over repeated periods
How to set priors — including
nonnegative_dependence