neighbayes.models.SARZINB

class neighbayes.models.SARZINB(formula=None, data=None, y=None, X=None, W=None, *, unit_effects=None, time_effects=False, dynamic=False, mundlak=False, latent=None, X_zero=None, formula_zero=None, W_zero=None, unit_col=None, time_col=None, N=None, T=None, priors=None, logdet_method=None, robust=False, durbin_vars=None, logdet_decomp='auto', logdet_adapt=True)[source]

Bayesian zero-inflated SAR negative binomial: latent, or reduced with latent=False.

Parameters:
formula : str, optional

Wilkinson-style formula for the count equation, e.g. "y ~ x1 + x2". Requires data.

data : pandas.DataFrame or geopandas.GeoDataFrame, optional

Data source for formula mode.

y : array-like, optional

Non-negative integer counts of shape (n,). Required in matrix mode.

X : array-like, optional

Count covariate matrix of shape (n, k). Required in matrix mode.

X_zero : array-like or pandas.DataFrame, optional

Zero-part covariate matrix of shape (n, p); a DataFrame’s column names label beta_zero. If None (and no formula_zero), defaults to X (the same covariates in both parts).

formula_zero : str, optional

Right-hand side for the zero part, e.g. "~ z1 + z2", evaluated on data (formula mode). Alternative to X_zero.

W : libpysal.graph.Graph or scipy.sparse matrix

Spatial weights for the count part, shape (n, n) (N × N in a panel).

W_zero : libpysal.graph.Graph or scipy.sparse matrix, optional

Spatial weights for the zero part. If None, uses W (the same weights in both parts).

priors : dict, optional

Override default priors. Supported keys:

  • beta_mu_zero, beta_sigma_zero (float or array, default Gelman et al. 2008 on the logit scale, centred at even odds): Normal prior on beta_zero.

  • rho_lower_zero, rho_upper_zero (float, default -0.999 and 0.999): bounds for rho_zero.

  • beta_mu, beta_sigma (float or array, default Gelman et al. 2008 on the log scale): Normal prior on β, intercept at log(mean(y)) with scale 2.5 and slopes 2.5 / sd(x_j).

  • rho_lower (float, default -0.999): Lower bound for ρ.

  • rho_upper (float, default 0.999): Upper bound for ρ.

  • alpha_sigma, alpha_nu (float, default 2.5 and 3.0): Half-Student-t(ν, σ) prior on the NB dispersion α.

  • alpha_fixed (float, optional): hold α at this value instead; a large value (10-20 times the typical mean count) makes the count part essentially Poisson on the same exact sampler.

See SARZINBPriors.

logdet_method : {"eigenvalue", "cheb", "aaa", "spline", "stochastic"}, optional

How log|I - rho*W| is computed over rho: summed over the eigenvalues of W; interpolated (Chebyshev, AAA rational, or cubic spline) through values from a sparse factorization, exact to the interpolant’s tolerance; or expanded stochastically with no factorization, the one method with sampling error. None (default) selects from the size and symmetry of W: "eigenvalue" for n <= 500; "aaa" up to n = 60000 (NEIGHBAYES_LOGDET_FACTOR_MAX_N) unless the factorization’s fill-in would dominate; "stochastic" beyond.

logdet_decomp : {"auto", "chol", "lu"}, default "auto"

The factorization an interpolating method uses: sparse Cholesky (undirected W; scikit-sparse CHOLMOD) or sparse LU (KLU or UMFPACK, chosen by the sparsity pattern). "auto" takes "chol" where the method has it and W is undirected, else "lu". Ignored by "eigenvalue" and "stochastic"; "spline" on "chol" raises.

time_col : str, optional

Formula-mode panel: the period and unit columns of data. Given time, the model is a panel (neighbayes.models.panel._zinb), stacked by period, then unit, with structural zeros per period; X_zero may vary over time. A panel’s priors are PanelZINBPriors.

unit_col : str, optional

Formula-mode panel: the period and unit columns of data. Given time, the model is a panel (neighbayes.models.panel._zinb), stacked by period, then unit, with structural zeros per period; X_zero may vary over time. A panel’s priors are PanelZINBPriors.

N : int, optional

Matrix-mode panel: the numbers of units and periods.

T : int, optional

Matrix-mode panel: the numbers of units and periods.

unit_effects : {None, "random"}, default None

A panel’s random unit effects, inside the count filter. The zero part has none: a unit effect there would compete with the zero process for the same information.

time_effects : bool, default False

A panel’s fixed time effects in the count part (add period dummies to X_zero for period effects in the zero part).

mundlak : bool, default False

Add the unit means of the time-varying columns to a panel’s count design. Needs unit effects.

latent : bool, default True

The latent model; False fits the reduced form. In the latent model each part is a latent SAR propagating its own disturbance, a unit active when its logistic utility is positive and its count then Poisson given the log-mean (neighbayes.samplers.two_part_latent). As a panel its count part takes the effects above inside its filter, its zero part none.

Notes

fit() defaults to a 9-block Gibbs sampler that composes the SAR-logit blocks of the zero part (ω_z, η_z, β_z, ρ_z), the zero-allocation block (z), and the reduced-form SAR-NB blocks (ω^cnt, β, ρ, α); sampler="nuts" fits the same model and priors in PyMC (ZeroInflatedNegativeBinomial).

activation_probabilities, zero_attribution and the fitted means are posterior expectations averaged over draws; posterior_predictive simulates d ~ Bern(π), y = d · NB.

__init__(formula=None, data=None, y=None, X=None, W=None, *, unit_effects=None, time_effects=False, dynamic=False, mundlak=False, latent=None, **kwargs)[source]

Methods

__init__([formula, data, y, X, W, ...])

activation_probabilities([draws])

Posterior mean of each P(u > 0): an active unit (ZINB), a positive count (hurdle).

fit([draws, tune, chains, target_accept, ...])

Draw samples from the posterior.

fitted_values()

Return fitted values at posterior mean parameters.

impacts([equation, ...])

Direct, indirect and total impacts for one equation.

posterior_predictive(*args, **kwargs)

Posterior-predictive counts, shape (n_draws, n_obs).

residuals()

Return residuals y - fitted_values.

spatial_diagnostics()

Run Bayesian LM specification tests and return a summary table.

spatial_diagnostics_decision([alpha, format])

Return a model-selection decision from Bayesian LM test results.

summary([var_names])

Return posterior summary table.

zero_attribution([draws])

Posterior split of each observed zero into structural and sampling.

Attributes

inference_data

Return the ArviZ DataTree from the most recent fit.

pymc_model

Return the PyMC model object built for the most recent fit.

activation_probabilities(draws=200)[source]

Posterior mean of each P(u > 0): an active unit (ZINB), a positive count (hurdle).

The latent model’s averages the propagated disturbances by simulation.

fit(draws=2000, tune=1000, chains=4, target_accept=None, random_seed=None, progressbar=True, sampler=None, backend=None, thin=1, n_jobs=-1, idata_kwargs=None, **sample_kwargs)[source]

Draw samples from the posterior.

Dispatches to this model’s Gibbs sampler (sampler="gibbs") or NUTS (sampler="nuts"). When sampler is None (default), Gibbs is used if the model has a registered Gibbs sampler, otherwise NUTS.

Parameters:
draws : int

Post-warmup draws, warmup steps, and number of chains.

tune : int

Post-warmup draws, warmup steps, and number of chains.

chains : int

Post-warmup draws, warmup steps, and number of chains.

target_accept : float, optional

Target acceptance rate for NUTS. NUTS-only: passing it with the Gibbs sampler raises TypeError. Defaults to 0.9 for NUTS.

random_seed : int, optional

Seed for reproducibility.

progressbar : bool, default True

Show progress bar(s) during sampling.

sampler : {"gibbs", "nuts", None}, default None

Sampling method. None auto-selects Gibbs when this model has one, else NUTS.

backend : str, optional

What executes the sampler. For Gibbs, "auto" (the default), "jax" or "numpy"; "auto" takes JAX when it is installed and supported by the family, else NumPy. For NUTS, "pymc" (the default), "nutpie", "numpyro" or "blackjax".

thin : int, default 1

Keep every thin-th post-warmup Gibbs draw (Gibbs only).

n_jobs : int, default -1

Parallel workers for the NumPy Gibbs path (Gibbs only).

idata_kwargs : dict, optional

{"log_likelihood": True} stores the complete Jacobian-corrected pointwise log-likelihood that az.loo / az.compare need, for Gibbs and NUTS alike. Off by default, as in PyMC: it holds one value per draw, chain, and observation (16 GB at n = 250,000 with 4 × 2,000 draws). For NUTS the dict is also passed to pm.sample.

**sample_kwargs

For NUTS, forwarded to pm.sample; for Gibbs, the family’s declared options (an unsupported key raises).

Return type:

xarray.DataTree

fitted_values()[source]

Return fitted values at posterior mean parameters.

Returns:

Posterior-mean fitted values (on the model’s native scale; fixed-effects-transformed for panel models).

Return type:

np.ndarray

impacts(equation='count', return_posterior_samples=False, scale=None)[source]

Direct, indirect and total impacts for one equation.

Parameters:
equation : {"count", "zero"}, default "count"

"count": impacts of X on the count part’s log-mean, through (I − ρW)⁻¹Xβ. "zero": impacts of X_zero on the zero part’s log-odds, through (I − ρ_zero W_zero)⁻¹ X_zero β_zero.

return_posterior_samples : bool, default False

Also return the per-draw impacts.

scale : str, optional

The equation’s link scale ("logmean", "logodds", the default) or, for a latent model, its outcome scale: "count", the expected count of an active unit (ZINB) or of a positive count (hurdle), and "probability", of the zero part’s u > 0.

property inference_data[source]

Return the ArviZ DataTree from the most recent fit.

Returns:

The inference data object, or None if the model has not been fit yet.

Return type:

xarray.DataTree or None

posterior_predictive(*args, **kwargs)[source]

Posterior-predictive counts, shape (n_draws, n_obs).

Parameters:
n_draws : int, optional

Posterior draws to simulate from; all of them by default.

random_seed : int, optional

Seed for the simulation.

property pymc_model[source]

Return the PyMC model object built for the most recent fit.

For a Gibbs-fitted cross-section the PyMC model is not constructed during sampling; it is built lazily on first access so that downstream consumers (e.g. bridge sampling for marginal likelihoods) can evaluate logp and the prior under the same model definition used by the NUTS path.

Returns:

The model object used by fit(), or None if the instance has not been fit yet.

Return type:

pymc.Model or None

residuals()[source]

Return residuals y - fitted_values.

Returns:

Residual vector y - fitted_values on the same scale as fitted_values().

Return type:

np.ndarray

spatial_diagnostics()[source]

Run Bayesian LM specification tests and return a summary table.

Looks up the diagnostic suite registered for this model class and calls each test function on this fitted model, collecting the results into a tidy DataFrame. The set of tests depends on the model type — for example, an OLS model runs LM-Lag, LM-Error, LM-SDM-Joint, and LM-SLX-Error-Joint, while an SAR model runs LM-Error, LM-WX, and Robust-LM-WX. Panel models run the Panel--prefixed analogues (e.g. Panel-LM-Lag).

Requires the model to have been fit (.fit() called) and a spatial weights matrix W to have been supplied at construction time.

Returns:

DataFrame indexed by test name with columns:

Column

Description

statistic

Posterior mean of the LM statistic

median

Posterior median of the LM statistic

df

Degrees of freedom for the \(\chi^2\) reference

p_value

Bayesian p-value: 1 - chi2.cdf(mean, df)

ci_lower

Lower bound of 95% credible interval (2.5%)

ci_upper

Upper bound of 95% credible interval (97.5%)

The DataFrame has attrs["model_type"] (class name) and attrs["n_draws"] (total posterior draws) metadata.

Return type:

pandas.DataFrame

Raises:
  • RuntimeError – If the model has not been fit yet.

  • ValueError – If no spatial weights matrix W was supplied.

See also

spatial_diagnostics_decision

Model-selection decision based on the test results.

impacts

Posterior inference for direct/indirect/total impacts.

Examples

>>> ols = OLS(formula="price ~ income + crime", data=df, W=w)
>>> ols.fit()
>>> ols.spatial_diagnostics()
                 statistic  median  df  p_value  ci_lower  ci_upper
LM-Lag                3.21    2.98   1    0.073      0.12      8.54
LM-Error              5.67    5.34   1    0.017      0.34     12.10
LM-SDM-Joint          7.89    7.12   4    0.096      1.23     18.32
LM-SLX-Error-Joint    6.45    5.98   4    0.168      0.89     15.67
spatial_diagnostics_decision(alpha=0.05, format='graphviz')[source]

Return a model-selection decision from Bayesian LM test results.

One rule reads every fitted model’s tests: the specific-to-general rule of Anselin et al. [1996], which spreg’s stge_classic implements. A model that leaves two directions untested runs a plain and a robust LM test for each:

  1. Neither plain test is significant → keep the model.

  2. One is → add that direction.

  3. Both are → add the direction whose robust test is significant; if both or neither are, the one with the smaller robust p-value.

A plain test is valid when the other direction is absent and a robust one is valid either way, at a cost in power, so the robust pair only chooses between two plain rejections. The SDM and SDEM leave one direction, and its test decides. The directions, and the models they lead to:

  • OLS: lag → SAR, error → SEM, WX → SLX. With three directions untested, the lag and the error together go to their robust pair whether or not WX also rejects (the SAR or SEM then tests it); the lag and WX go to the robust pair of Koley and Bera [2024], whose lag test is LM-Error at the OLS fit; the error and WX, whose scores are uncorrelated there, to the smaller p-value.

  • SAR: WX → SDM, error → SARAR.

  • SEM: lag → SARAR, WX → SDEM.

  • SLX: lag → SDM, error → SDEM.

  • SDM: error → GNS. SDEM: lag → GNS.

SARAR and GNS are where the tests point; neighbayes does not fit them. The WX tests are those of Koley and Bera [2024]. Panel models run the Panel- tests through the same trees ([Elhorst, 2014]), and the Tobit classes the same trees with Tobit leaves. The logit, probit and NB at their aspatial null read their tests as a pair of their own.

Parameters:
alpha : float, default 0.05

Significance level for the Bayesian p-values.

format : {"graphviz", "ascii", "model"}, default "graphviz"

Output format. "model" returns the recommended-model name string. "ascii" returns an indented box-drawing rendering of the full decision tree with the chosen path highlighted. "graphviz" returns a graphviz.Digraph object that renders inline in Jupyter; if the optional graphviz package is not installed a UserWarning is issued and the ASCII rendering is returned instead.

Returns:

Recommended model name when format="model", an ASCII tree string when format="ascii", or a graphviz.Digraph when format="graphviz" (with ASCII fallback on missing dep).

Return type:

str or graphviz.Digraph

See also

spatial_diagnostics

Compute the Bayesian LM test statistics.

References

Koley and Bera [2024], Anselin et al. [1996], Elhorst [2014]

summary(var_names=None, **kwargs)[source]

Return posterior summary table.

Parameters:
var_names : list, optional

Variable names to include in the summary.

**kwargs

Additional arguments passed to arviz.summary().

Returns:

Posterior summary statistics.

Return type:

pandas.DataFrame

zero_attribution(draws=200)[source]

Posterior split of each observed zero into structural and sampling.

The latent model’s is the sampler’s: the average, over the sweeps after warmup, of each zero’s conditional probability that its unit is inactive (draws does not apply).