How to fit spatial tobit models

Outcomes censored at a threshold — spending that cannot go below zero, demand recorded only above a reporting limit. SARTobit puts the spatial lag on the latent outcome, SEMTobit puts the spatial structure in the errors, and SDMTobit adds spatially lagged covariates.

All three are NUTS-only: none has a registered Gibbs sampler, so fit() uses NUTS and target_accept applies. Equations and constructor arguments are in Supported Models.

Note

For binary outcomes, use SARLogit or SARProbit (and their SEM and SDEM classes), which have exact Gibbs samplers — see How to fit a spatial logit model.

import contextlib
import io
import time

import arviz as az
import numpy as np
import pandas as pd

from neighbayes.dgp import simulate_sar_tobit, simulate_sdm_tobit, simulate_sem_tobit
from neighbayes.models import SARTobit, SDMTobit, SEMTobit

FIT = dict(draws=1000, tune=800, chains=4, random_seed=1)


def fit_timed(model, **kw):
    start = time.perf_counter()
    with (
        contextlib.redirect_stdout(io.StringIO()),
        contextlib.redirect_stderr(io.StringIO()),
    ):
        idata = model.fit(progressbar=False, **kw)
    return idata, time.perf_counter() - start

Fit a censored outcome

censoring is the threshold, and it must match your data — pass the value below which observations are recorded at the limit rather than at their true level. The DGP here censors at zero, so about a fifth of the sample piles up there.

data_sar = simulate_sar_tobit(
    n_side=18, rho=0.4, beta=np.array([1.0, 1.5]), sigma=0.8, censoring=0.0, seed=1
)
y, X, W = data_sar["y"], data_sar["X"], data_sar["W_graph"]

print(f"observations   : {len(y)}   (18 x 18 queen grid)")
print(f"censored at 0  : {(y <= 0).mean():.1%}")
print("true parameters: rho=0.4, beta=[1.0, 1.5], sigma=0.8")
observations   : 324   (18 x 18 queen grid)
censored at 0  : 21.0%
true parameters: rho=0.4, beta=[1.0, 1.5], sigma=0.8
/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
model_sar = SARTobit(y=y, X=X, W=W, censoring=0.0)
idata_sar, secs_sar = fit_timed(model_sar, **FIT)

az.summary(idata_sar, var_names=["rho", "beta", "sigma"]).round(3)
mean sd eti89_lb eti89_ub ess_bulk ess_tail r_hat mcse_mean mcse_sd
rho 0.405 0.043 0.33 0.47 2000 2321 1.00 0.00097 0.00069
beta[x0] 1.038 0.079 0.91 1.2 2097 2178 1.00 0.0017 0.0013
beta[x1] 1.542 0.058 1.5 1.6 2232 2456 1.00 0.0012 0.00087
sigma 0.794 0.036 0.74 0.86 3091 2935 1.00 0.00066 0.00054

Important

Get censoring right or the fit is meaningless The threshold is not inferred. Pass censoring=0.0 for data censored at zero, and the actual limit otherwise. Fitting a censored outcome with the wrong threshold — or with an ordinary Gaussian model — biases every coefficient toward zero, because the pile-up at the limit is read as genuine variation in the outcome.

Read marginal effects, not coefficients

This is the part that most often goes wrong. In a linear SAR model \(\beta\) is a marginal effect; under censoring it is not, because a unit change in \(x\) moves the latent outcome and only part of that reaches the observed one — the part that does depends on how close each observation sits to the threshold.

impacts() does the averaging and splits the result into direct, indirect and total components.

model_sar.impacts().round(4)
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.6187 1.4987 1.7415 0.0 0.9851 0.6813 1.3476 0.0 2.6038 2.2359 3.03 0.0

Report those. The gap between direct and the raw coefficient is the combined effect of the censoring and of the spatial multiplier feeding back onto the unit itself; indirect is what reaches other units.

Put the spatial structure in the errors instead

Use SEMTobit when the spatial pattern is a nuisance — clustered unobservables rather than a channel through which one unit’s covariates reach another. The spatial parameter is named lam, and because there are no covariate-mediated spillovers, the effects decomposition collapses to the coefficient itself.

data_sem = simulate_sem_tobit(
    n_side=18, lam=0.4, beta=np.array([1.0, 1.5]), sigma=0.8, censoring=0.0, seed=1
)
model_sem = SEMTobit(
    y=data_sem["y"], X=data_sem["X"], W=data_sem["W_graph"], censoring=0.0
)
idata_sem, secs_sem = fit_timed(model_sem, **FIT)

az.summary(idata_sem, var_names=["lam", "beta", "sigma"]).round(3)
mean sd eti89_lb eti89_ub ess_bulk ess_tail r_hat mcse_mean mcse_sd
lam 0.44 0.076 0.31 0.56 3315 3060 1.00 0.0013 0.0011
beta[x0] 1.099 0.08 0.97 1.2 3349 2353 1.00 0.0014 0.0013
beta[x1] 1.51 0.058 1.4 1.6 2729 2789 1.00 0.0011 0.0009
sigma 0.759 0.036 0.7 0.82 3362 3010 1.00 0.00063 0.00054

Add spatially lagged covariates

SDMTobit includes \(WX\) alongside \(X\), so a neighbour’s covariates enter your outcome directly rather than only through the lag. It is the right choice when you think the characteristics of neighbours matter, not just their outcomes — and it is the specification the LM tests point to when both the lag and the error channel register.

data_sdm = simulate_sdm_tobit(
    n_side=18, rho=0.4, beta1=np.array([1.0, 1.5]), sigma=0.8, censoring=0.0, seed=1
)
model_sdm = SDMTobit(
    y=data_sdm["y"], X=data_sdm["X"], W=data_sdm["W_graph"], censoring=0.0
)
idata_sdm, secs_sdm = fit_timed(model_sdm, **FIT)

print(f"coefficients: {idata_sdm.posterior['beta'].sizes['coefficient']} (X and WX)")
az.summary(idata_sdm, var_names=["rho", "sigma"]).round(3)
coefficients: 3 (X and WX)
mean sd eti89_lb eti89_ub ess_bulk ess_tail r_hat mcse_mean mcse_sd
rho 0.384 0.062 0.28 0.48 2030 2211 1.00 0.0014 0.001
sigma 0.783 0.035 0.73 0.84 3238 2863 1.00 0.00062 0.00053
pd.DataFrame(
    [
        pd.Series(
            {
                "spatial parameter": p,
                "posterior mean": float(i.posterior[p].mean()),
                "posterior sd": float(i.posterior[p].std()),
                "seconds": s,
                "ess": float(az.ess(i, var_names=[p])[p]),
                "rhat": float(az.rhat(i, var_names=[p])[p]),
            },
            name=n,
        )
        for n, p, i, s in (
            ("SARTobit", "rho", idata_sar, secs_sar),
            ("SEMTobit", "lam", idata_sem, secs_sem),
            ("SDMTobit", "rho", idata_sdm, secs_sdm),
        )
    ]
).round(3)
spatial parameter posterior mean posterior sd seconds ess rhat
SARTobit rho 0.405 0.043 56.703 2000.062 1.001
SEMTobit lam 0.440 0.076 13.827 3315.838 1.001
SDMTobit rho 0.384 0.062 61.840 2030.492 1.001

What to check before trusting the output

ess_bulk and r_hat on the spatial parameter first — it is the slowest-mixing quantity in all four models. Then check that the censored share in your data matches what you told the model, and look at impacts() rather than the coefficient table.

Because these are NUTS models, sample_stats also carries divergence counts; any divergences at all are worth investigating before reading the posterior.

pd.DataFrame(
    [
        pd.Series(
            {
                "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, i in (
            ("SARTobit", idata_sar),
            ("SEMTobit", idata_sem),
            ("SDMTobit", idata_sdm),
        )
    ]
)
divergences min ess_bulk max rhat
SARTobit 0.0 1380.430748 1.004478
SEMTobit 0.0 1742.670706 1.004583
SDMTobit 0.0 1553.690949 1.004312

See also