Supported Models¶
Model suite¶
A model class names a process (Aspatial, SLX, SAR, SEM, SDM, SDEM) and a
family (Gaussian, Tobit, logit, probit, and the count families), plus Flow
when the outcome is an origin–destination flow: SAR, SARLogit,
SARNegBinFlow. The design is a set of arguments to the same class:
time_col (formula mode) or T (matrix mode) makes it a panel;
unit_effects (pair_effects for flows) is None, "fixed", or "random";
time_effects=True adds fixed time effects; dynamic=True adds the time lag
("restricted" for the restricted dynamic SDM); and separable=True pins
\(\rho_w = -\rho_d \rho_o\) in a flow model. A combination the package does not
implement raises when the model is constructed. Each cell below lists the
processes implemented for that combination.
Gaussian · Cross-section |
Gaussian · Panel |
Other families · Cross-section |
Other families · Panel |
|
|---|---|---|---|---|
Single |
Aspatial, SLX, SAR, SEM, SDM, SDEM |
Aspatial, SLX, SAR, SEM, SDM, SDEM |
Aspatial, SAR, SEM, SDM, SDEM |
Aspatial, SAR, SEM |
Flow |
Aspatial, SAR, SEM |
Aspatial, SAR, SEM |
Aspatial, SAR |
Aspatial, SAR |
Gaussian panels take fixed or random unit effects and have dynamic
(lagged-dependent-variable) forms. Every spatial flow model has a separable
form (separable=True) that pins \(\rho_w = -\rho_d \rho_o\). The other families include negative binomial,
zero-inflated NB and hurdle NB count models (and Poisson for cross-sectional
flows). Outside the table, Multilevel nests units in groups in larger
groups, with a graph and a process at every level
(multilevel models). The sections below list every class
with its equation.
Cross Sectional Models¶
OLS¶
SLX¶
SAR¶
SEM¶
SDM¶
SDEM¶
Panel Models¶
Each Gaussian class is a panel when time_col or T is given; the fixed-effects
models below take unit_effects="fixed" and time_effects=True for two-way
effects, and the random-effects models unit_effects="random".
OLS panel¶
SAR panel¶
SEM panel¶
SDM panel¶
SDEM panel¶
SLX panel¶
OLS panel (Random Effects)¶
The random-effects Gibbs sampler (this and the spatial variants below) updates \(\sigma_\alpha\) by interweaving a centered step (\(\sigma_\alpha \mid \alpha\)) with a non-centered one (\(\sigma_\alpha \mid \alpha/\sigma_\alpha\), exact under the Gaussian likelihood). The centered step alone mixes at about 1% of draws when the unit effects are small against \(\sigma/\sqrt{T}\), the common many-units, few-periods spatial panel.
SAR panel (Random Effects)¶
SEM panel (Random Effects)¶
SDEM panel (Random Effects)¶
Multilevel Models¶
Multilevel¶
Units (level 0) nest in groups (level 1), which nest in larger groups, up to
level \(L\): schools in districts in states, tracts in counties in states. Each
level has its own graph \(W_\ell\), covariates \(X_\ell\), innovation sd
\(\sigma_\ell\) and process, and each level’s effect \(\theta_\ell\) enters the
equation of the level below through \(\Delta_\ell\), which maps a row to its
parent. A level’s process is one of the acronyms used everywhere else. In
place of the lag ("SAR", the default), any level may carry an error process
("SEM"),
\(\theta_\ell = X_\ell\beta_\ell + \Delta_\ell\theta_{\ell+1} + v_\ell\) with
\(v_\ell = \lambda_\ell W_\ell v_\ell + \varepsilon_\ell\), or none (None), and
any level may add the Durbin terms \(W_\ell X_\ell\) ("SDM", "SDEM", "SLX").
Every graph spans all groups at its level, whatever their parent: a West Texas county neighbors New Mexico counties. Because each level’s effect passes through the filter of the level below, a shift at the top reaches the units through every filter beneath it. In the reduced form with a lag at every level,
so a Texas policy spreads into Oklahoma’s border districts and from there into their schools. With two levels this chain and an additive entry of the effects coincide, and the model nests the two-level hierarchical SAR models: Dong & Harris’s HSAR (a lag at the units, an error process with no covariates above), the dual spatial-error model of Wolf et al. (spvcm), and Lacombe & McIntyre’s upper-level lag or error with Durbin terms. The units carry the only intercept; upper levels drop theirs, since through row-standardized filters constants at different levels are confounded.
from neighbayes.models import Level, Multilevel
m = Multilevel(
Level("score ~ frl + log_enroll", data=schools, W=W_schools), # level 0
Level("~ income + segregation", data=districts, W=W_districts,
key="district_id"), # level 1
Level("~ spending", data=states, W=W_states, key="fips",
process="SEM"), # level 2
)
idata = m.fit()
A level’s position is its index \(\ell\). key names the id column shared with
the level below; it is looked up in the level below’s data, then in the units’
data, where strict nesting is checked. A Graph’s ids order a level’s groups (its
data are reindexed to them). In matrix mode, groups gives each lower row’s
parent label. The posterior follows the levels: rho_ℓ (or lam_ℓ for an
error process), beta_ℓ, sigma_ℓ, and the effects theta_ℓ (coordinate
group_ℓ).
Priors. \(\sigma_0^2 \sim \text{Inv-}\Gamma(2, s_w^2)\), the data-informed prior
of the single-level models with \(s_w^2\) the pooled variance of \(y\) within level-1
groups: \(\operatorname{Var} y\) would also count the upper levels’ variance and
bias \(\sigma_0\) upward when those levels are strong. Each upper level’s \(\sigma_\ell \sim \text{half-}t_3(0, \operatorname{sd} y)\), since
every level’s effects are in the outcome’s units; Gelman et al. (2008) priors on
each level’s \(\beta_\ell\); uniform priors on each graph’s stability bounds for
\(\rho_\ell\). See MultilevelPriors.
Sampling. Given the \(\rho\)’s and \(\sigma\)’s, the coefficients of every level
and all the effects are jointly Gaussian with a sparse precision, so the Gibbs
sampler draws them in one sparse Cholesky block. Drawing them together removes
the ridge between the units’ intercept and the mean of the effects. Every
\(\rho_\ell\) and upper-level \(\sigma_\ell\) is drawn from its conditional with that
block integrated out (parametrization="collapsed", the default), at one
refactorization per evaluation. Three other schemes update the upper levels’
\(\rho_\ell\) and \(\sigma_\ell\) given the block instead:
"centred", given the effects;"noncentred", given the standardized innovations \(\varepsilon_\ell/\sigma_\ell\), a move that needs no Jacobian;"interweave", both in turn (Yu & Meng 2011).
These need only the block’s conditional, so they carry over to non-Gaussian likelihoods.
On a three-level lag model with 16 units per group, the collapsed scheme gave 7–14× the effective sample size of interweaving for the upper levels’ \(\rho\) and \(\sigma\), and the most per second.
backend="jax", the default when JAX is installed, runs the same sweep
compiled, using sparsax’s CHOLMOD and LU. When the top level is small (a few
dozen states, say), its \(\rho\) and \(\sigma\) are updated through a dense Schur
complement, which spares the large factorizations. The sweep is compiled once
per model structure and reused by later fits, including fits to new data of
the same shape, so a simulation study pays for compilation once. Per sweep it
ran:
2–10× faster than NumPy with about 600 units;
1.5–4× faster with 14,400 units, where the collapsed scheme’s cost is CHOLMOD’s own factorization.
sampler="nuts"fits the same model non-centered. Gibbs and NUTS agree across lag, error and no-process configurations. The units’ intercept is heavy-tailed: its spread grows as the top level’s \(\rho\) nears 1, where NUTS diverges.
Impacts. impacts(level=ℓ) reports the impacts of level \(\ell\)’s
covariates on the units, through the composed multiplier
\(S_0\Delta_0 S_1 \cdots \Delta_{\ell-1}S_\ell\), where \(S_m\) is the identity for a
level with an error process or none:
direct: the mean effect on a unit of a shift in its own group;
total: the mean effect of a shift in every group;
indirect: the difference, which is what reaches a unit from other groups through the filters.
on="level" gives the impacts on \(\theta_\ell\) itself, through \(S_\ell\) alone.
The own-group trace is exact up to exact_max groups and estimated with
Rademacher probes above.
Multilevel: Gaussian, cross-sectional, \(L \ge 1\) nested levels. Panels, count likelihoods and crossed (non-nested) classifications are planned.
Dynamic Panel Models¶
Pass dynamic=True to a panel, or dynamic="restricted" to an SDM panel. Dynamic
panels take no unit effects (Nickell 1981) but may take time_effects=True.
OLS, dynamic (dynamic linear model)¶
SDM, restricted dynamic (dynamic="restricted")¶
SDM, dynamic (unrestricted)¶
SAR, dynamic¶
SEM, dynamic¶
SDEM, dynamic¶
SLX, dynamic¶
Non-Linear Models¶
Binary models¶
A binary outcome is the sign of a latent utility, \(y_i = \mathbf{1}[y_i^* > 0]\).
The latent SAR propagates the link’s own disturbance through the multiplier,
standard logistic for the logit and standard normal for the probit, so its
\(\rho = 0\) member is the aspatial model and no scale parameter is pinned: the
link fixes it. The reduced form propagates only the covariates. The unmarked SAR
class is the latent SAR in both links, as in every family (ADR 0004):
SARProbit and SARLogit, with latent=False fitting the reduced form. The
SEM and SDEM classes are latent too and take no latent argument.
The latent models share one exact Gibbs sweep: the utilities from their
truncated normal conditionals (Albert and Chib 1993), one at a time on NumPy or a
color class at a time on JAX (the default), then \(\rho\) or \(\lambda\) with
\(\beta\) integrated out, then \(\beta\), and a scale move on \((y^*, \beta)\). The
logit adds the Kolmogorov scales that make its disturbance a normal scale
mixture (Holmes and Held 2006). The likelihood is an orthant probability, so
there is no NUTS path; idata_kwargs={"log_likelihood": True} integrates each
observation’s utility out of its likelihood, given the others’, for LOO.
Impacts are on the latent index (scale="index" for the probit, "logodds" for
the logit) or on \(P(y_i = 1)\) (scale="probability").
SARProbit (latent SAR)¶
The textbook SAR probit (McMillen 1992; LeSage and Pace 2009, §10.1).
SARProbit, reduced form (latent=False)¶
Sampled as the reduced SARLogit is, with Albert–Chib utilities in place of
its Pólya–Gamma step: \(\beta\) conjugate given the utilities, \(\rho\) by a slice
with \(\beta\) integrated out, where the log-determinant cancels.
SEMProbit¶
SDEMProbit¶
SEMProbit with random unit effects (unit_effects="random")¶
Each unit, a row of \(W\), is observed more than once (unit_col, or units in
matrix mode, gives each observation’s unit), and the error process carries one
random effect per unit (unit_effect, with sd unit_effect_sd) in place of the
probit’s disturbance: LeSage and Pace’s (2009, §10.6) spatially structured
effects probit (Smith and LeSage 2004). It is fitted by NUTS; its probability
impacts are the average marginal effects, with no indirect part.
Tobit (SAR Tobit)¶
Tobit (SEM Tobit)¶
Tobit (SDM Tobit)¶
Panel Tobit (SAR)¶
Panel Tobit (SEM)¶
SARTobit and SEMTobit given time (time_col, or T) fit the pooled panel. It
takes no unit or time effects, because a within transformation would mix censored
and uncensored values in the likelihood. Impacts are on the latent scale, through
the spatial multiplier within each period.
Panel count models, reduced form (SARNegBin(latent=False), NegBin)¶
Unit effects \(c\) come from unit_effects="random" and period effects \(\tau_t\)
from time_effects=True. The Gaussian panels’ within transform does not carry
to a log link, so the effects are parameters, held as a unit index rather than
dummy columns. The unit effects enter inside the spatial filter, with the
covariates, as random effects do in every spatial equation of the package:
persistent unobservables propagate as \(X\) does. Under the partial pooling below
this is a different model from independent effects added after the filter, not
a reparameterization of it: the propagated effects \((I - \rho W)^{-1} c\) carry
the SAR covariance \(\sigma^2 (A'A)^{-1}\), so the effects themselves inform
\(\rho\). The two coincide only for unpooled effects. The Gibbs sampler
integrates the unit effects out of every \(\rho\) update by an ω-weighted
analogue of the within transform, recomputed each sweep from the Pólya–Gamma
weights; its effect block has the sparse precision
\(\operatorname{diag}(w) + A'A/\sigma^2\), factored by CHOLMOD at each
candidate \(\rho\).
The unit effects are partially pooled: \(c_i \sim N(\mu, \sigma^2)\) with
\(\sigma\) learned (a half-\(t_3\) prior with scale unit_effect_sd_scale,
default 1; the posterior’s unit_effect and unit_effect_sd, or pair_effect
and pair_effect_sd in the flow panels), so a unit seen in few periods is shrunk toward the common mean in
proportion to how little its data say. Spatial panels typically have many units
and few periods (Elhorst 2014), and there a fixed, wide prior leaves each
unit’s level pinned only by its own few periods, which biases the dispersion \(\alpha\) and \(\rho\) (the incidental-parameter problem)
and lets \(\rho\) drift toward 1, where the filter’s amplification of an
unanchored level goes unchecked. The unit effects absorb no column: the
intercept and time-invariant covariates stay in the design. Period effects keep
a fixed prior and absorb the columns that vary only over time. Pooling assumes
the effects are unrelated to \(X\); when they are not, mundlak=True adds the
unit means of the time-varying columns to the design inside the filter (Mundlak
1978), which absorbs the correlation (in a nonlinear model only approximately).
The Gibbs sampler updates \(\sigma\) by interweaving a centered step
(\(\sigma \mid c\)) with a non-centered one (\(\sigma \mid \tilde c\),
\(\tilde c = (c - \mu)/\sigma\); Yu & Meng 2011), the latter on the exact
likelihood rather than the Pólya–Gamma working one, so no augmentation layer
stands between \(\sigma\) and the data (Papaspiliopoulos, Roberts & Sermaidis
2011). That keeps \(\sigma\) mixing in the large-\(N\), small-\(T\) regime, where each
unit’s data say little about its effect.
Both classes default to Gibbs; sampler="nuts" runs the PyMC model. priors={"alpha_fixed": a} holds \(\alpha\) fixed; a large value
(10-20 times the typical mean count) gives an essentially Poisson model that
keeps the exact Pólya–Gamma sampler.
SARNegBin, reduced form (latent=False)¶
No disturbance propagates — spatial dependence enters only through the mean propagator. Supports both NUTS and Pólya–Gamma Gibbs sampling. Unit effects need a panel (above): in a cross-section one draw per observation is a disturbance, not a unit effect.
SARNegBin (latent SAR)¶
The latent SAR: the multiplier propagates the negative binomial’s own gamma
disturbance, so \(\rho = 0\) is NegBin and the GLM suite’s LM-Lag is its score
test. The Gibbs sampler carries the log-means \(\eta\), given which the
disturbances are a sparse linear map and every conditional is log-concave: the
log-means are drawn one at a time by slice on NumPy and a color class at a time
by independence Metropolis–Hastings on JAX (the default), then \(\rho\) with
\(\beta\) shifted along the least-squares fit of \(W\eta\) on \(X\), \(\beta\) from a
t at its Laplace approximation, and \(\alpha\). Small counts pin \(\eta\) only
loosely, so two moves interweave the parametrization that holds the
disturbances instead (Yu & Meng 2011): \(\alpha\) with the standardized
disturbances held, and \(\rho\) with the disturbances held. When \(\alpha\) is
small and most counts are zero, \(\rho\), \(\alpha\) and the depth of the zeros’
log-means move together, and every one-parameter move pins them; a last move
draws \(\rho\), \(\log\alpha\) and the level of \(X\beta\) jointly, holding the log-means
at the positive counts and the standardized disturbances at the zeros, by a
slice along the eigenvectors of its Hessian. On a 100 × 100 lattice with 95%
zeros and \(\alpha = 0.05\) it raised the effective sample size of \(\rho\) from
0.1% to 4.5% of the sweeps. There is no NUTS path.
The pointwise log-likelihood
(idata_kwargs={"log_likelihood": True}) integrates each observation’s latent
value out given the others, \(p(y_i \mid \theta, \eta_{-i}) = \int p(y_i \mid
\eta_i)\, p(\eta_i \mid \eta_{-i}, \theta)\, d\eta_i\), a one-dimensional
integral over the equations the column of \(I - \rho W\) touches. That is the
integrated importance sampling of Li, Qiu, Zhang and Feng (2016), whose weights
PSIS-LOO handles; the likelihood conditional on \(\eta_i\) would give degenerate
ones (Merkle, Furr and Rabe-Hesketh 2019). It is comparable with the reduced
form’s: both estimate \(\sum_i \log p(y_i \mid y_{-i})\).
As a panel (T), it takes random unit effects and period effects, both
inside the filter as in the Gaussian SAR with random effects,
\((I - \rho W)\eta_t = X_t\beta + \tau_t + c + \varepsilon_t\), \(c_i \sim
N(\mu, \sigma_c^2)\) with \(\sigma_c\) learned; each period’s gamma disturbance
propagates through the same filter, so the Jacobian is \(T\log|I - \rho W|\).
The sweep runs over the stacked periods, and a unit effect, entering only its
own unit’s equations, is drawn from a t at its conditional mode. With period
effects and a row-standardized \(W\), the target also carries Lee and Yu’s (2010)
time-effects term, \(-T\log(1 - \rho)\), as the Gaussian panels do: a period
effect inside the filter moves its period’s log-mean level by
\(\tau_t/(1 - \rho)\), so priors flat on the \(\tau_t\) themselves would leave a
factor \(1 - \rho\) per period in the marginal of \(\rho\) and bias it down
(by about one posterior sd at \(N = 100\)); the term makes them flat on the
levels.
Impacts are on the log-mean by default; impacts(scale="count") gives them on
the expected count, which averages over the propagated heterogeneity. With \(u =
S(\rho)\varepsilon\) and \(m = S(\rho)X\beta\),
the reduced form’s count-scale impact with each row scaled by the mean of the
propagated heterogeneity. The product needs every entry of \(S\), but depends on
the parameters only through \((\rho, \alpha)\), so it is computed at a few values
of those and interpolated across the draws, in \(\operatorname{atanh}\rho\) and
\(\log\alpha\), with no factorization per draw beyond \(m\). It is not simulated:
at small \(\alpha\) rare draws carry the mean of \(e^{u_i}\), and at \(\alpha = 0.05\)
128 simulations read 16–29% low at \(\rho = 0.7\) and lose the effect entirely at
\(\rho = 0.9\). A draw with an entry \(S_{ij} \le -\alpha\) (a negative \(\rho\) at
small \(\alpha\)) has no expected count; it is left out of the effects with a
warning. The same holds, with \(S\) replaced by \((I - \lambda W)^{-1}\) and no
spillover through the mean, for SEMNegBin and SDEMNegBin, and for the count
part of a latent SARZINB. The count part of a latent SARHurdleNegBin takes
the same mean less a simulated bounded remainder, which is at most half of it.
SEMNegBin¶
The latent SEM, sampled as the latent SAR is, with \(\beta\) shifted so that the
disturbances keep their level as \(\lambda\) moves; \(\lambda = 0\) is NegBin and
the GLM suite’s LM-Error is its score test. It takes no latent switch.
SDEMNegBin¶
SEMNegBin on the design \([X, WX]\). Impacts are on the log-mean, direct
\(\beta\) and indirect \(\theta\) (times the mean row sum of \(W\)), or with
scale="count" on the expected count.
SARZINB, reduced form (latent=False)¶
Zero-inflated negative binomial: a spatial-lag logit zero part (is the unit
active?) and a spatial-lag NB count part, both reduced-form SARs. The zero
part’s parameters are the count part’s names with a _zero suffix: rho_zero
and beta_zero in the posterior, X_zero, formula_zero and W_zero in the
constructor, and beta_mu_zero, rho_lower_zero and so on in the priors. Pólya–Gamma Gibbs
by default; sampler="nuts" fits the same model in PyMC. Activation
probabilities, zero attribution and fitted means are posterior expectations;
posterior_predictive simulates the zero process too.
Identification. Only the shape of the count distribution separates
structural zeros from sampling zeros. When active units average about one
count, NB with a smaller α explains the zeros nearly as well as zero inflation
does. The zero part is then weakly identified, the posterior of rho_zero is
close to its prior, and the Gibbs chain mixes slowly. Repeated periods fix this:
in a panel with unit (or pair) effects, a unit’s other periods pin down its
count distribution, and the zeros in excess of it are structural. For “any
versus none” questions on sparse counts, use a hurdle model
(below), whose zero part is fit to the observed
zeros.
SARZINB (latent)¶
Each part is a latent SAR with its own disturbance: the zero part is the
latent SAR logit (\(\varepsilon_z\) logistic; a unit is active when its utility
is positive), the count part the latent SAR negative binomial
(\(\varepsilon_i = \log\gamma_i\), \(\gamma_i \sim \operatorname{Gamma}(\alpha,
\alpha)\)). The sweep is the two latent samplers in turn, coupled through the
zero counts: a zero leaves its unit’s activation unknown, so its utility’s
side of zero is drawn given the count part, the active side weighted by
\(P(y_i = 0 \mid \text{active}) = e^{-e^{\eta_i}}\), and the count part then
observes the active units only. zero_attribution is the sampler’s
Rao–Blackwellized probability that each zero is structural.
log_likelihood integrates both latent values out of each observation, for
LOO. impacts(equation, scale=...) reports each part on its link scale (the
default) or its outcome scale: "probability" of activation, and "count",
the expected count of an active unit. The identification caveat above applies
unchanged. As a panel (\(T\) periods stacked time-first, each filter acting
within a period) the count part takes random unit effects inside its filter
and period effects (unit_effects="random", time_effects=True), as the
latent SARNegBin panel does; the zero part takes none, as in the reduced
form. NumPy or backend="jax".
ZINB panels (SARZINB, ZINB)¶
The same two parts per period, \(T\) periods stacked time-first, with
per-period structural zeros and unit and period effects on the count part
(unit_effects="random", time_effects=True, as for the NB panels). The
zero part’s design X_zero may vary over time.
Flow ZINB (SARZINBFlow, separable)¶
Both parts are separable flow models,
\(\eta_z = (L_{z,o} \otimes L_{z,d})^{-1} X_z\beta_z\) and
\(\eta^{\mathrm{cnt}} = (L^{\rho}_o \otimes L^{\rho}_d)^{-1} X\beta\), sampled by a
structured \(n \times n\) sweep (NumPy or backend="jax") that never forms
an \(n^2 \times n^2\) matrix. The panel adds pair and period effects on the count
part; the cross-section is the panel with \(T = 1\). Flow counts are usually
sparse, so the identification caveat above bites hardest here: use the panel
with pair effects, or the flow hurdle.
Hurdle models (SARHurdleNegBin and family)¶
A hurdle separates whether a count is positive from how large it is when
it is. In the reduced form (latent=False) both parts are reduced-form SARs:
the spatial lag acts on the linear predictor and no latent disturbance enters,
so neither part has a Jacobian. The unmarked SARHurdleNegBin is the latent
model (below).
The zero part is named as in SARZINB (rho_zero, beta_zero, X_zero,
W_zero).
Hurdle or ZINB. Both give positive counts the same zero-truncated NB
distribution; they differ only in the probability of a positive count. The
hurdle models it directly, \(P(y > 0) = \pi\). ZINB splits it into an
activation probability and the NB’s own chance of a positive count,
\(\pi\,(1 - \operatorname{NB}(0))\), and so can call a zero structural. The data
see that split only through the shape of the positive counts, which on sparse
counts barely constrains it (see SARZINB). The hurdle’s zero part is fit to
the observed zeros, so it is identified however sparse the counts are. What it
gives up is the split: its beta_zero and rho_zero describe whether any count occurs, not
whether a unit is “open”. Use the hurdle when the question is “any versus none”,
and ZINB, in a panel with unit or pair effects, when the question is
“structurally closed versus open but quiet”.
Sampling. The zero part is a Pólya–Gamma logit. In the count part the
truncation is augmented exactly: each positive cell gets a geometric count of
the zeros the truncation hid, after which the cell is Pólya–Gamma conjugate.
When the positive counts are mostly ones, the count level and α trade off along
a ridge, so they are drawn jointly by a slice sampler that moves along it.
sampler="nuts" fits the same model in PyMC (HurdleNegativeBinomial).
SARHurdleNegBin: cross-section, with separate
X_zero(orformula_zero) andW_zerofor the zero part.Panels (
SARHurdleNegBin,HurdleNegBinwithtime_colorT): \(T\) periods stacked time-first, with unit and period effects (unit_effects="random",time_effects=True) in both parts. In the zero part a unit effect absorbs the unit’s baseline chance of a positive count, sobeta_zerocomes mostly from within-unit switches between zero and positive periods. The posterior names the zero part’s effectsunit_effect_zero,unit_effect_sd_zeroandtime_effect_zero. Both parts’ unit effects are partially pooled, with their own learned sds; the pooling is what keeps α and ρ unbiased when units have few positive periods (about three per unit in simulations, where a fixed, wide prior gave α at half its true value).Flows (
SARHurdleNegBinFlow(separable=True), cross-section or panel): both parts are separable flow models, sampled by the structured \(n \times n\) sweep (NumPy orbackend="jax"), with pair and period effects in both parts.
The halves share no parameters, so the posterior factorizes. Linking them through correlated unit (pair) effects is a planned extension.
Latent (the unmarked SARHurdleNegBin). Each part is a latent SAR with its
own disturbance: a count is positive when the utility
\(u = (I - \rho_z W_z)^{-1}(X_z\beta_z + \varepsilon_z)\), \(\varepsilon_z\)
logistic, is positive, and is then \(\operatorname{Poisson}(e^{\eta_i})\)
truncated at zero, \(\eta = (I - \rho W)^{-1}(X\beta + \varepsilon)\),
\(\varepsilon_i = \log\gamma_i\). The truncation conditions on \(\eta_i\), as in
hurdle models with random effects. The parts still share nothing: the zero
part is the latent SARLogit fitted to \(\mathbf 1(y > 0)\), the count part
the latent SAR NB observing the positive counts only, and a sweep is one sweep
of each. LOO and impacts work as for the latent SARZINB, the count part’s
outcome being the expected positive count. As a panel both parts take random
unit effects and period effects, each inside its own filter; given the
logistic’s normal scales the zero part’s unit effects are Gaussian. NumPy or
backend="jax".
Logit¶
Non-spatial logistic regression baseline.
NegBin¶
Non-spatial negative binomial baseline.
SARLogit, reduced form (latent=False)¶
The reduced form: the spatial multiplier acts on the mean of the log-odds. Pólya–Gamma Gibbs sampler only — no NUTS path. Binary outcomes pin \(\rho\) slowly: expect to need about 900 units or more.
There is no spatial logit with random effects. In a cross-section the effects’ sd trades off against \(\beta\) (the logit’s attenuation) and against \(\rho\) or \(\lambda\), and binary outcomes barely constrain the trade: on 1,225 units with effects of sd 2, an SEM logit with such effects had its \(\lambda\) near 0.3 against 0.5 and the effects’ sd at 6 ± 6, held only by its prior.
SARLogit (latent SAR)¶
The latent SAR: the multiplier propagates the logit’s own disturbance, so
\(\rho = 0\) is the logit and the GLM suite’s LM-Lag is its score test. It has no
variance parameter, which is why it is identified where the random-effects
logits were not. The Gibbs sampler is exact: it draws the latent utilities
(Albert and Chib 1993), the Kolmogorov scales that make the logistic a normal
scale mixture (Holmes and Held 2006, through augax), \(\rho\) with \(\beta\)
integrated out, then \(\beta\), and ends with a scale move that rescales the
utilities and \(\beta\) together (Liu and Wu 1999), which keeps \(\rho\) mixing as
it nears one (at \(\rho = 0.97\) it quadruples its effective draws). It runs on
JAX by default, drawing the
utilities a color class at a time (classes of utilities that share no row of
\(I - \rho W\) are conditionally independent), and on NumPy one at a time. There
is no NUTS path (the likelihood is an orthant probability). Its pointwise
log-likelihood integrates each utility out as the negative binomial’s does, the
observation’s term being the probability that the utility falls on the observed
side of zero.
Impacts are on the latent index by default; impacts(scale="probability") gives
them on \(P(y_i = 1) = P(u_i > -m_i)\), with \(u = S(\rho)\varepsilon\) and \(m =
S(\rho)X\beta\): \(\partial P(y_i = 1)/\partial x_{jk} = f_{u_i}(-m_i)\,S_{ij}\beta_k\),
the logistic counterpart of the SAR probit’s \(\phi\) term in LeSage and Pace
(2009). The density of the weighted sum of logistics \(f_{u_i}\) is estimated per
posterior draw by Monte Carlo, conditioning on every disturbance but the unit’s
own, whose logistic density then enters exactly. SEMLogit and SDEMLogit take
the same scale.
SEMLogit¶
The latent SEM, sampled as the latent SAR is; \(\lambda = 0\) is the logit and
the GLM suite’s LM-Error is its score test. A SEM whose error process carried no
disturbance would be the aspatial logit, so the SEM logit takes no latent
switch.
SDEMLogit¶
SEMLogit on the design \([X, WX]\), sampled the same way: \(\theta\) carries the
covariates’ spillover and \(\lambda\) the clustering of the disturbance, which a
latent SAR ties together through one \(\rho\). Impacts are on the latent index,
direct \(\beta\) and indirect \(\theta\) (times the mean row sum of \(W\)), or with
scale="probability" on the probability.
Flow Models¶
Vectorize the origin-destination flow matrix to \(y \in \mathbb{R}^{N}\) with \(N = n^2\), and define destination, origin, and origin–destination weight matrices as \(W_d\), \(W_o\), and \(W_w\).
OLSFlow¶
NegBinFlow¶
SARFlow¶
One class: separable=True gives the separable form below, and T a panel.
The unrestricted flow’s fit() runs the resolvent-gradient sampler and
sampler="nuts" PyMC with the exact trace-series Jacobian; the separable flow
samples by NUTS. robust=True (Student-t errors, fixed \(\nu\)) needs NUTS.
SARFlow, separable¶
SARNegBinFlow¶
SARNegBinFlow, separable¶
pair_effects="fixed" (a panel) is the fixed-effects static panel: a level
per origin–destination pair after the filter, under a flat prior,
\(\eta_{t,ij} = (A^{-1}X_t\beta)_{ij} + c_{ij} + \tau_t\). Under a flat prior a
level inside the filter is a reparameterization of one after it. The pair
levels absorb every time-invariant column (intercept, log distance, the intra
indicator, time-invariant attributes), so \(\rho\) and \(\beta\) are identified by
the within-pair variation of the time-varying columns, which is what makes the
estimates robust to time-invariant confounding. A pair with no count in any
period has no proper posterior and leaves the likelihood. The posterior
integrates each level out rather than profiling it, and the NB2 log-mean is
information-orthogonal to \(\alpha\), so \(\alpha\) escapes the leading
\(O(1/T)\) incidental-parameter bias of the dummy-variable estimator (Lancaster
2002); in simulation at \(T = 2\)–16 its posterior mean showed no bias, where
random pair levels pulled \(\alpha\) low at small \(T\).
origin_effects and destination_effects ("random" or "fixed") add a
level per origin and per destination after the filter,
\(\eta_{ij} = (A^{-1}X\beta)_{ij} + \gamma_i + \kappa_j\); random levels are
\(\gamma_i \sim N(\mu_o, \tau_o^2)\), \(\kappa_j \sim N(\mu_d, \tau_d^2)\) with
both scales learned, fixed ones flat: the production-, attraction- or doubly
constrained gravity model with balancing factors (Griffith & Fischer 2016).
For a row-standardized \(W\) the filter maps a column constant along each row to
one again, so the levels absorb the intercept and the time-invariant origin
(destination) attributes, which are dropped with a warning. The spatial
parameters are then identified only by the remaining columns, such as
distance; with distance alone they can sit near a bound, on any sampler. With
origin levels alone \(\rho_d\) is well identified, with destination levels alone
\(\rho_o\); with both, \(\rho\) is weakly identified.
time_effects=True adds period levels \(\tau_t\): beside other effects the
first period is the baseline; alone, every period has one and the intercept is
absorbed. All of these run on the exact-likelihood Gibbs sampler, which moves
the levels with the coefficients and with \(\rho\) (otherwise they crawl
against each other); cell_mask removes cells (the intraregional diagonal)
from the likelihood. NUTS takes the random levels and the period effects only.
The SAR NB flow takes no random pair effects: random pair effects inside the
filter tie \(\rho\) to the spatial pattern of the pair levels, and in
simulation moved it by about ten posterior sd. The unrestricted SAR NB panel
takes period effects only.
SARPoissonFlow¶
No dispersion parameter. Sampled by auxiliary-mixture Gibbs
(Frühwirth-Schnatter & Wagner 2006) rather than Pólya–Gamma, which admits no
exact Poisson representation. Use it for counts close to Poisson: the normal
mixture behind the sampler has lighter tails than the error it replaces, so
under overdispersion it is biased toward large counts (fit reports the
Pearson dispersion and warns above 2). For overdispersed counts use the NB
flow models; an NB with priors={"alpha_fixed": a}, a 10-20 times the
typical mean, is an essentially Poisson model on the exact Pólya–Gamma
sampler.
SARPoissonFlow, separable¶
The recommended Poisson flow model — the separable restriction removes the weakly-identified \(\rho\) ridge of the unrestricted variant.
SEMFlow¶
Designs and samplers as SARFlow, except that the unrestricted SEM flow has
no PyMC model, so only the separable one takes robust=True.
SEMFlow, separable¶
Panel Flow Models¶
Stack the flow models above across \(T\) periods in time-first order; any flow class is a panel when T is given, with pair_effects and time_effects. The
SAR NB panel takes fixed pair effects after the filter (see SARNegBinFlow
above). The ZINB and hurdle panels take pair and period effects as parameters,
the pair effects partially pooled,
\(\log \boldsymbol{\mu}_t = A(\boldsymbol{\rho})^{-1} (X_t\beta + c) + \tau_t\),
with one effect per origin-destination pair held as an index, never as \(n^2\)
dummy columns; see the panel count models above. Their separable panels keep a
structured \(n \times n\) sweep. Their \(n^2 \times n^2\)
effect block cannot be integrated out at scale, so the sweep holds the effects
while \(\rho\) moves (interweaving steps with the effects and with their
propagated values held), draws them by conjugate gradients, and moves the
time-invariant coefficients (intercept, distance, intraunit indicators)
jointly with the effects they trade off against.
OLSFlow panel¶
NegBinFlow panel¶
SARFlow panel¶
SARFlow panel, separable¶
SARNegBinFlow panel¶
SARNegBinFlow panel, separable¶
SEMFlow panel¶
SEMFlow panel, separable¶
Specification Tests¶
Lagrange-multiplier tests for choosing a spatial specification, called directly
from neighbayes.diagnostics.lmtests or through spatial_diagnostics() and
spatial_diagnostics_decision() on any fitted model.
Each Gaussian test is the score test of the general nesting model, \((I - \rho W)y = X\beta + WX\theta + u\), \((I - \lambda W)u = \varepsilon\), at the fitted null. The score of the tested parameters is evaluated at every posterior draw, Neyman-orthogonal to everything the null estimates (Doğan, Taşpınar & Bera 2021),
with the efficient information \(J_{TT} - J_{TF}J_{FF}^{-1}J_{FT}\) at the posterior mean. At a draw the scores \(g_F\) of the null’s own parameters are not zero, as they are at the restricted maximum, so a raw score correlated with them would carry their posterior spread: the lag score does, through the part of \(WX\beta\) in the span of \(X\) (for a row-standardized \(W\), the intercept’s \(\beta_0 W\mathbf 1 = \beta_0\mathbf 1\)). The reported statistic and p-value are the test at the posterior-mean parameters, the counterpart of the score test at the estimate; the per-draw values give the posterior distribution behind the credible interval. A robust test also removes the directions its alternative leaves at zero (Bera & Yoon 1993), so a test robust only to parameters the null estimates is the plain test.
Test |
\(H_0\) |
Null |
Robust to |
df |
|---|---|---|---|---|
LM-Lag |
\(\rho = 0\) |
OLS, SLX, SEM |
1 |
|
LM-Error |
\(\lambda = 0\) |
OLS, SLX, SAR |
1 |
|
LM-SDM (joint) |
\(\rho = \theta = 0\) |
OLS |
\(1 + k_{wx}\) |
|
LM-SLX-Error (joint) |
\(\lambda = \theta = 0\) |
OLS |
\(1 + k_{wx}\) |
|
Robust LM-Lag |
\(\rho = 0\) |
OLS |
\(\lambda\) |
1 |
Robust LM-Error |
\(\lambda = 0\) |
OLS |
\(\rho\) |
1 |
Robust LM-Lag-SDM |
\(\rho = 0\) |
SLX |
\(\lambda\) |
1 |
Robust LM-Error-SDEM |
\(\lambda = 0\) |
SLX |
\(\rho\) |
1 |
LM-WX |
\(\theta = 0\) |
OLS, SAR, SEM |
\(k_{wx}\) |
|
Robust LM-WX |
\(\theta = 0\) |
OLS |
\(\rho\) |
\(k_{wx}\) |
Robust LM-WX |
\(\theta = 0\) |
SAR |
\(\lambda\) |
\(k_{wx}\) |
Robust LM-Error |
\(\lambda = 0\) |
SAR |
\(\theta\) |
1 |
Robust LM-Lag |
\(\rho = 0\) |
SEM |
\(\theta\) |
1 |
Robust LM-WX |
\(\theta = 0\) |
SEM |
\(\rho\) |
\(k_{wx}\) |
LM-Error-SDM |
\(\lambda = 0\) |
SDM |
1 |
|
LM-Lag-SDEM |
\(\rho = 0\) |
SDEM |
1 |
At a degenerate posterior on the OLS estimate the tests are the classical ones: Anselin et al. (1996)’s LM-lag, LM-error and their robust pair, and the WX and joint tests of Koley & Bera (2024).
The same tests serve the panels: pooled panels stack their periods, fixed
effects use the transformed likelihood of Lee & Yu (2010) that the demeaned
data give (traces counted \(T - 1\) times under unit effects, the direction
\(\mathbf 1\) removed under time effects), random unit effects enter as
coefficients carrying their prior, and a dynamic panel conditions on its first
period with the lagged outcome as a regressor; the functions carry the
bayesian_panel_lm_* prefix.
At the OLS null the lag score is the error score plus \(\hat\beta^\top\) times the WX score, and the error and WX scores are uncorrelated. So the two joint tests are one statistic, which splits two ways: LM-SDM-Joint = LM-Lag + Robust LM-WX (Koley & Bera 2024) = LM-Error + LM-WX. The lag robust to WX, their Robust LM-Lag-SDM, is therefore LM-Error there, and the error and WX tests robust to each other are the plain ones; the OLS suite runs none of these duplicates.
spatial_diagnostics_decision() reads a fitted model’s tests by the rule of
Anselin et al. (1996), the one spreg’s stge_classic implements. A model that
leaves two directions untested (OLS: lag and error; SAR: WX and error; SEM: lag
and WX; SLX: lag and error) is kept when neither plain test rejects, and gains
the direction whose plain test rejects when one does. When both do, it gains the
direction whose robust test rejects, or, when both or neither do, the one with
the smaller robust p-value. A plain test is valid when the other direction is
absent and a robust one either way, at a cost in power, so the robust pair only
settles a double rejection. The OLS fit also leaves WX untested, and a lone WX
rejection there adds it (the SLX). The lag and the error together go to their
robust pair whether or not WX also rejects, and the SAR or SEM fit then tests WX.
The lag and WX go to Koley & Bera’s robust pair, whose lag test is LM-Error
there: it has not rejected, so WX goes ahead if Robust LM-WX rejects, and the
smaller p-value of the two decides otherwise. The error and WX go to the smaller
p-value. The SDM and SDEM read their one test. The trees name
SARAR and GNS where the tests point, though neighbayes does not fit them; panel
and Tobit models follow the same trees.
Logit and negative binomial¶
At the GLM null (Logit, NegBin) the tests are the score tests of the latent
SAR, \(\eta = S(\rho)(X\beta + \varepsilon)\) with \(\varepsilon\) the family’s own
disturbance. Its score at \(\rho = 0\) splits into a spillover term
\(s = \tilde e^\top W X\beta\) and an error term \(q = \tilde e^\top W h\), with
\(\tilde e\) the score residual and \(h = E[\varepsilon \mid y]\) the predicted
disturbance; the two are uncorrelated, and each is standardized by its own
information, using the Fisher weights.
Test |
Statistic |
Score test of |
df |
|---|---|---|---|
LM-Lag |
\((s + q)^2 / (I_s + V_q)\) |
latent SAR |
1 |
LM-Error |
\(q^2 / V_q\) |
latent SEM, \(\eta = X\beta + S(\lambda)\varepsilon\) |
1 |
Robust LM-Lag |
\(s^2 / I_s\) |
reduced-form SAR, \(\eta = S(\rho)X\beta\) |
1 |
Robust LM-Error |
\((I_s q - V_q s)^2 / ((I_s + V_q) I_s V_q)\) |
error beyond one \(\rho\) |
1 |
LM-SARMA |
\(s^2/I_s + q^2/V_q\) |
both |
2 |
The suites also carry LM-WX and Moran-Working, a Moran diagnostic on the
Pólya–Gamma working residuals that is not the score test of a fitted model. At
a reduced-form SAR null (SARLogit(latent=False), SARNegBin(latent=False))
the suites are LM-Error, the
score of a latent error process added to the fitted model, and LM-WX; both are
uncorrelated with the other scores there, so their robust forms are the same
statistics. A fitted latent SAR, the default, has no such suite yet: the tests
with the latent SAR as their null are not derived.
Logit.spatial_diagnostics_decision() and NegBin.spatial_diagnostics_decision()
read the tests as a pair (the table names the logit’s classes; the negative
binomial’s are SARNegBin, SEMNegBin and SDEMNegBin). A latent SAR
moves both terms, in the proportion its one \(\rho\) implies; Robust LM-Error
measures the departure from that proportion.
Robust LM-Lag |
LM-Error |
Robust LM-Error |
Recommendation |
|---|---|---|---|
significant |
not |
— |
|
significant |
significant |
not |
|
significant |
significant |
significant |
|
not |
significant |
significant |
|
not |
significant |
not |
|
not |
not |
— |
|
The last but one row is ambiguous by construction: without a spillover term to compare it against, an error term alone cannot say whether one \(\rho\) moved it.
The GLM scores are orthogonalized and the statistic taken at the posterior-mean parameters as for the Gaussian tests.
Origin–destination flows¶
The flow tests are the score tests of the lag-flow model
\(y = \rho_d W_d y + \rho_o W_o y + \rho_w W_w y + X\beta + \varepsilon\) at a
fitted OLSFlow, cross-section or panel (the panel on the Lee and Yu
transformed likelihood), built as the Gaussian tests are. With
\(W_d = I_n \otimes W\), \(W_o = W \otimes I_n\) and \(W_w = W \otimes W\), every
trace in the information factors into traces of \(W\), so the \(n^2\) pairs never
form a Kronecker product.
Test |
H₀ |
df |
|---|---|---|
LM-Flow-Destination, -Origin, -OD |
one of \(\rho_d\), \(\rho_o\), \(\rho_w\) is 0 |
1 |
LM-Flow-Joint |
\(\rho_d = \rho_o = \rho_w = 0\) |
3 |
Robust-LM-Flow-Destination, -Origin, -OD |
one \(\rho\) is 0, robust to the other two |
1 |
The decision tree reads the joint test: SARFlow if it rejects, OLSFlow
if not. A fitted SARFlow estimates the lags these tests test, so it has no
suite; neither, yet, do the count flows.
Sources¶
Doğan, O., Taşpınar, S., Bera, A.K. (2021). “A Bayesian robust chi-squared test for testing simple hypotheses.” Journal of Econometrics, 222(2), 933–958.
Koley, M., Bera, A.K. (2024). “To Use, or Not to Use the Spatial Durbin Model? – That Is the Question.” Spatial Economic Analysis, 19(1), 30–56.
Bera, A.K., Yoon, M.J. (1993). “Specification testing with locally misspecified alternatives.” Econometric Theory, 9(4), 649–658.
Anselin, L., Bera, A.K., Florax, R., Yoon, M.J. (1996). “Simple diagnostic tests for spatial dependence.” Regional Science and Urban Economics, 26(1), 77–104.
LeSage, J.P., Pace, R.K. (2008). “Spatial Econometric Modeling of Origin–Destination Flows.” Journal of Regional Science, 48(5), 941–967.
Lee, L.-F., Yu, J. (2010). “Estimation of spatial autoregressive panel data models with fixed effects.” Journal of Econometrics, 154(2), 165–185.
Sampling Backends¶
Choosing a sampler¶
fit() takes sampler={"gibbs", "nuts", None}, and None — the default —
selects Gibbs whenever the model has a registered Gibbs sampler, and NUTS
otherwise. For SAR/SEM/SDM/SDEM, the count families, the ZINB model and the
Gaussian panel families, that means Gibbs unless you ask for something else.
NUTS is not universally available. SARLogit (in both forms), SEMLogit,
SDEMLogit, the latent SARNegBin, SEMNegBin, SDEMNegBin and the
auxiliary-mixture Poisson flow classes build no PyMC graph at all, and
fit(sampler="nuts") raises NotImplementedError. Robust (Student-t) SAR/SEM/SDM/SDEM and
Gaussian panel FE models keep Gibbs: the Student-t error is sampled as a
normal scale mixture with the same fixed nu the NUTS path uses. Robust
random-effects and Tobit models still require NUTS.
target_accept is NUTS-only and raises TypeError if passed with Gibbs.
Execution backends¶
For any Gibbs sampler, backend selects the execution path:
Value |
Behavior |
|---|---|
|
default — JAX when installed and supported by the family, else NumPy |
|
the sweep compiled into one XLA program; chains run in parallel, vectorized under |
|
pure NumPy/SciPy; chains as separate processes via |
Both backends implement the same sampler and target the same posterior.
With sampler="nuts", backend names the NUTS implementation instead:
"pymc" (the default), "nutpie", "numpyro" or "blackjax". A backend
that belongs to the other sampler raises.
A JAX sweep is compiled once per model structure (its dimensions and its process, effect and prior options) and reused for the rest of the session. The first fit pays for compilation, from under a second to a few seconds; a refit, a longer run, or new data of the same dimensions on the same graph does not, so a simulation study compiles once rather than once per replicate.
Gibbs Sampler (Gaussian models)¶
Gaussian cross-sectional models (SAR, SEM, SDM, SDEM) and the Gaussian panel families exploit conditional conjugacy with a 3-block strategy:
Block |
Full conditional |
Update |
|---|---|---|
β | ρ, σ², y |
Normal |
Direct draw (conjugate) |
σ² | β, ρ, y |
Inverse-Gamma |
Direct draw (conjugate) |
ρ/λ | β, σ², y |
1-D non-conjugate |
Adaptive slice sampling |
SAR and SDM update the spatial parameter with β and σ² integrated out (a collapsed conditional); SEM and SDEM update it conditional on them.
model = SAR(y=y, X=X, W=W)
idata = model.fit(draws=2000, tune=1000, chains=4) # Gibbs, by default
The family accepts one option beyond the shared fit() arguments:
slice_width, the initial slice interval for ρ/λ. See the
Gibbs sampler how-to for details.
Gibbs Sampler (SAR Negative Binomial)¶
SARNegBin (reduced form) supports a Pólya–Gamma Gibbs sampler via sampler="gibbs" (the default):
model = SARNegBin(y=y_int, X=X, W=W)
idata = model.fit(draws=2000, tune=1000, chains=4)
The reduced form has no latent σ² — spatial dependence enters only through the mean propagator \((I - \rho W)^{-1}\):
Block |
Full conditional |
Update |
|---|---|---|
ω | β, ρ, α, y |
Pólya–Gamma |
Direct draw (conjugate augmentation) |
β | ρ, ω, y |
Normal |
Direct draw (conjugate, via \(\tilde{X} = (I-\rho W)^{-1}X\)) |
ρ | ω, y |
1-D non-conjugate |
Adaptive slice sampling (β marginalised) |
α | y, η |
1-D non-conjugate |
Slice sampling on log(α) |
SARNegBin(unit_effects="random") adds η and σ² blocks via a separate Gibbs sampler in neighbayes.samplers.negbin.
Gibbs Sampler (NB flow models)¶
NB flow models (SARNegBinFlow, unrestricted or separable, and NegBinFlow) support Gibbs sampling via sampler="gibbs":
model = SARNegBinFlow(y_int, X, G) # positional: (y, X, W)
idata = model.fit(sampler="gibbs", draws=2000, tune=1000, chains=4)
Spatial dependence enters only through the mean propagator \(A^{-1}\); there is no σ² parameter. The unrestricted model uses Pólya–Gamma augmentation:
Block |
Full conditional |
Update |
|---|---|---|
ω | β, α, y |
Pólya–Gamma |
Direct draw (conjugate augmentation) |
β | ρ, ω, y |
Normal |
Direct draw (conjugate, via \(\tilde{X} = A^{-1}X\)) |
ρ | ω, y |
1-D non-conjugate |
Adaptive slice sampling (β marginalised) |
α | y, η |
1-D non-conjugate |
Slice sampling on log(α) |
Each ρ parameter (ρ_d, ρ_o, ρ_w) is updated by its own 1-D slice with β
marginalised out. The aspatial NegBinFlow omits the ρ block entirely.
The separable model (separable=True, cross-section or panel without pair
effects) slices its exact NB2 likelihood instead, with no augmentation. At
small α the Pólya–Gamma likelihood given ω is far more precise than the NB2
one, and chains that condition on ω crawl: on a Los Angeles tract panel at
α ≈ 0.015 their information ratio reached 71. The model has no latent field,
only \(k + 3\) parameters, so slicing the exact likelihood is cheap. With
\(a = -\log(1-\rho_d)\), \(b = -\log(1-\rho_o)\) and \(\theta = \beta /
((1-\rho_d)(1-\rho_o))\), which holds the mean level fixed while ρ moves,
Block |
Update |
|---|---|
θ | a, b, α |
Slice along each eigenvector of the Fisher information (\(\eta\) is linear in θ) |
(a, b) | θ, α |
Slice along each eigenvector of their warmup covariance |
α | y, η |
Slice sampling on log(α) |
and ρ_w = −ρ_d·ρ_o is deterministic. Fixed pair effects, origin and destination effects and period effects are levels after the filter, drawn in blocks of their own and carried along by the θ and (a, b) moves.
Log-Determinant Methods¶
The log-determinant \(\log|I - \rho W|\) is evaluated at every MCMC draw, and is
the term that makes large problems expensive. Two arguments of the model
constructor (not of fit()) choose how it is computed, and both samplers
honor them:
logdet_methodis the method:"eigenvalue"sums over the eigenvalues of \(W\) from one dense eigendecomposition;"cheb","aaa"and"spline"interpolate values from a sparse factorization (Chebyshev, AAA rational, cubic spline), exact to the interpolant’s tolerance;"stochastic"is a stochastic Chebyshev expansion (Han et al. 2015) that needs no factorization and is the one method with sampling error.logdet_decompis the factorization an interpolating method uses:"chol"(sparse Cholesky through scikit-sparse’s CHOLMOD, for an undirected \(W\)) or"lu"(sparse LU by KLU or UMFPACK, routed by the sparsity pattern, for any \(W\))."auto"takes"chol"where the method has it and \(W\) is undirected, else"lu";"eigenvalue"and"stochastic"ignore it.
|
|
|
|---|---|---|
|
✅ |
✅ |
|
✅ |
✅ |
|
— |
✅ |
A pair marked — raises. Leaving both at their defaults auto-selects by size, by whether \(W\) is undirected, and by how much fill-in a sparse factorization would incur:
\(n\) |
\(W\) |
Chosen |
Why |
|---|---|---|---|
≤ 500 |
any |
|
one \(O(n^3)\) eigendecomposition, then \(O(n)\) per ρ — exact and cheap at this size |
≤ 60000 |
undirected |
|
sparse Cholesky at adaptively chosen AAA support points; root-exponential convergence |
≤ 60000 |
directed |
|
the same rational scheme over sparse LU (KLU or UMFPACK) — k-nearest-neighbor, travel time, migration |
> 60000 |
any |
|
no factorization, at the cost of stochastic error |
Fill-in guard. Size alone does not predict factorization cost — a dense or
hub-dominated graph blows up under Cholesky regardless of \(n\). Before
committing to a factorization the selector estimates
\(\mathrm{nnz}(W^2)/\mathrm{nnz}(W)\) in \(O(\mathrm{nnz})\); if that exceeds 20 it
warns and falls back to stochastic. A KNN-50 graph or a fully dense \(W\)
at moderate \(n\) takes that branch.
Adaptation. With logdet_adapt=True (the default) the Gibbs sampler fits
the log-determinant to where the chains are halfway through warmup: an
interpolant is refit on that ρ range (recorded in
idata.attrs["logdet_refit_window"]), AAA adds factorizations near a
singularity, and stochastic grows its probe pool until the bias it leaves is
small against the posterior sd.
Flows. The unrestricted three-ρ flow models take "trace_series" (exact,
from trace moments of the \(n \times n\) \(W\)) or "resolvent" (a stochastic
resolvent estimator whose accuracy improves with the flow sample size, run on
fit(backend=...)); None takes the trace series for an undirected \(W\) and
the resolvent for a directed one. The separable flows factor the
log-determinant into \(n \times n\) terms and take the single-\(W\) methods above.
Cutoffs are configurable through the environment:
NEIGHBAYES_LOGDET_EIGEN_MAX_N (default 500),
NEIGHBAYES_LOGDET_FACTOR_MAX_N (default 60000), and
NEIGHBAYES_LOGDET_MAX_FILLIN_RATIO (default 20).