How to fit spatial tobit panel models¶
Censored outcomes observed for the same units over several periods.
A SARTobit panel puts the spatial lag on the latent outcome; a SEMTobit
panel puts the spatial structure in the disturbances. Either is a panel when
time_col or T is given.
Both are NUTS-only, and both need N, T and censoring stated
explicitly — the panel shape and the censoring threshold are not inferred.
Equations and constructor arguments are in
Supported Models.
import arviz as az
import numpy as np
import pandas as pd
from neighbayes import dgp
from neighbayes.models import SARTobit, SEMTobit
N, T, SIDE = 100, 5, 10 # 10x10 rook grid, 5 periods
RHO, LAM, SIGMA = 0.35, 0.35, 0.8
BETA = np.array([1.0, 1.4])
FIT = dict(draws=1000, tune=1000, chains=4, random_seed=42, progressbar=False)
rng = np.random.default_rng(42)
Fit a censored panel with a spatial lag¶
y and X are stacked long — \(N \cdot T\) rows, unit-major — and you tell the
model the shape with N and T.
sar_data = dgp.simulate_sar_tobit(
N=N,
T=T,
n_side=SIDE,
contiguity="rook",
rho=RHO,
beta=BETA,
sigma=SIGMA,
censoring=0.0,
rng=rng,
)
y_sar, X_sar, W = sar_data["y"], sar_data["X"], sar_data["W_graph"]
print(f"rows : {len(y_sar)} ({N} units x {T} periods)")
print(f"censored at 0 : {(y_sar == 0).mean():.1%}")
sar_model = SARTobit(y=y_sar, X=X_sar, W=W, N=N, T=T, censoring=0.0)
sar_idata = sar_model.fit(**FIT)
az.summary(sar_idata, var_names=["rho", "beta", "sigma"]).round(3)
rows : 500 (100 units x 5 periods)
censored at 0 : 19.2%
/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
Initializing NUTS using jitter+adapt_diag...
Multiprocess sampling (4 chains in 2 jobs)
NUTS: [rho, beta, sigma2, y_cens_gap]
Sampling 4 chains for 1_000 tune and 1_000 draw iterations (4_000 + 4_000 draws total) took 12 seconds.
| mean | sd | eti89_lb | eti89_ub | ess_bulk | ess_tail | r_hat | mcse_mean | mcse_sd | |
|---|---|---|---|---|---|---|---|---|---|
| rho | 0.329 | 0.038 | 0.27 | 0.39 | 2680 | 2643 | 1.00 | 0.00073 | 0.00058 |
| beta[x0] | 0.982 | 0.069 | 0.87 | 1.1 | 2765 | 2804 | 1.00 | 0.0013 | 0.00099 |
| beta[x1] | 1.408 | 0.044 | 1.3 | 1.5 | 2725 | 3156 | 1.00 | 0.00084 | 0.00066 |
| sigma | 0.8013 | 0.0286 | 0.76 | 0.85 | 4088 | 2963 | 1.00 | 0.00045 | 0.00044 |
Important
censoring must match your data
The threshold is not inferred. Pass the value below which observations are
recorded at the limit rather than at their true level — 0.0 here. Get it
wrong, or fit an uncensored model instead, and every coefficient is biased
toward zero because the pile-up at the limit reads as genuine variation.
Interpreting the coefficients¶
\(\beta\) is not a marginal effect once the outcome is censored: a unit change
in \(x\) moves the latent outcome, and only the uncensored part of that reaches the
observed one. impacts() reports the direct, indirect and total effects on the
latent scale, through the spatial multiplier within each period, as it does for
the cross-sectional SARTobit.
sar_model.impacts().round(3)
| 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 | 1.455 | 1.367 | 1.546 | 0.0 | 0.651 | 0.449 | 0.875 | 0.0 | 2.106 | 1.866 | 2.378 | 0.0 |
Put the spatial structure in the errors instead¶
The SEMTobit panel treats spatial correlation as a nuisance in the disturbances
rather than a channel between units. The spatial parameter is lam, and
because there are no covariate-mediated spillovers the effects decomposition
collapses to the coefficient.
sem_data = dgp.simulate_sem_tobit(
N=N,
T=T,
n_side=SIDE,
contiguity="rook",
lam=LAM,
beta=BETA,
sigma=SIGMA,
censoring=0.0,
rng=rng,
)
sem_model = SEMTobit(
y=sem_data["y"],
X=sem_data["X"],
W=sem_data["W_graph"],
N=N,
T=T,
censoring=0.0,
)
sem_idata = sem_model.fit(**FIT)
print(f"censored at 0 : {(sem_data['y'] == 0).mean():.1%}")
az.summary(sem_idata, var_names=["lam", "beta", "sigma"]).round(3)
censored at 0 : 30.8%
Initializing NUTS using jitter+adapt_diag...
Multiprocess sampling (4 chains in 2 jobs)
NUTS: [lam, beta, sigma2, y_cens_gap]
Sampling 4 chains for 1_000 tune and 1_000 draw iterations (4_000 + 4_000 draws total) took 13 seconds.
| mean | sd | eti89_lb | eti89_ub | ess_bulk | ess_tail | r_hat | mcse_mean | mcse_sd | |
|---|---|---|---|---|---|---|---|---|---|
| lam | 0.314 | 0.064 | 0.21 | 0.42 | 4637 | 2940 | 1.00 | 0.00094 | 0.00095 |
| beta[x0] | 0.868 | 0.058 | 0.78 | 0.96 | 5523 | 3216 | 1.00 | 0.00078 | 0.00094 |
| beta[x1] | 1.39 | 0.049 | 1.3 | 1.5 | 2907 | 2979 | 1.00 | 0.0009 | 0.00065 |
| sigma | 0.8094 | 0.032 | 0.76 | 0.86 | 4914 | 3073 | 1.00 | 0.00046 | 0.00056 |
What to check before trusting the output¶
The spatial parameter mixes slowest, and these are NUTS models, so divergences matter. Any at all are worth chasing down before you read the posterior.
pd.DataFrame(
[
pd.Series(
{
"spatial parameter": p,
"posterior mean": float(i.posterior[p].mean()),
"truth": t,
"divergences": int(i.sample_stats["diverging"].sum()),
"min ess_bulk": float(az.summary(i)["ess_bulk"].min()),
"max rhat": float(az.summary(i)["r_hat"].max()),
},
name=n,
)
for n, p, t, i in (
("SARTobit panel", "rho", RHO, sar_idata),
("SEMTobit panel", "lam", LAM, sem_idata),
)
]
).round(3)
| spatial parameter | posterior mean | truth | divergences | min ess_bulk | max rhat | |
|---|---|---|---|---|---|---|
| SARTobit panel | rho | 0.329 | 0.35 | 0 | 1407.111 | 1.006 |
| SEMTobit panel | lam | 0.314 | 0.35 | 0 | 2093.092 | 1.004 |
Short chains are used here so the docs build quickly. If ess_bulk on the
spatial parameter is in the low hundreds on your own data, raise draws and
tune before concluding anything from the interval.
See also¶
How to fit spatial tobit models — the cross-sectional versions, including the Durbin variant
Supported Models — equations and constructor arguments
How to set priors —
PanelSARTobitPriors,PanelSEMTobitPriors