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