neighbayes.models.Multilevel¶
-
class neighbayes.models.Multilevel(*levels, priors=
None, logdet_method=None, logdet_decomp='auto', logdet_adapt=True)[source]¶ Bayesian spatial multilevel model with a graph and a process at each level.
\[\theta_\ell = \rho_\ell W_\ell \theta_\ell + X_\ell \beta_\ell + \Delta_\ell \theta_{\ell+1} + \varepsilon_\ell, \qquad \ell = 0, \dots, L,\quad \theta_0 \equiv y,\]with a lag, an error process (\(v_\ell = \lambda_\ell W_\ell v_\ell + \varepsilon_\ell\)) or none at each level and \(\varepsilon_\ell \sim N(0, \sigma_\ell^2 I)\). Each level’s effect enters the equation of the level below, as in a hierarchical linear model, so a shift at level ℓ reaches the units through every filter beneath it. Each graph spans all groups at its level, whatever their parent.
- Parameters:¶
- *levels : Level¶
The units first, then each level above in turn. A level’s position is its index ℓ in the notation and in the posterior names.
- priors : dict or MultilevelPriors, optional¶
See
MultilevelPriors.- logdet_method : {"eigenvalue", "cheb", "aaa", "spline", "stochastic"}, optional¶
The log-determinant at the units; upper levels choose their own. How
log|I - rho*W|is computed over rho: summed over the eigenvalues ofW; 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 ofW:"eigenvalue"forn <= 500;"aaa"up ton = 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 andWis undirected, else"lu". Ignored by"eigenvalue"and"stochastic";"spline"on"chol"raises.- logdet_adapt : bool, default True¶
Halfway through Gibbs warmup, size each stochastic level’s Hutchinson probes to the run, as
SARdoes; the pools are recorded per level (idata.attrs["logdet_probes_ℓ"]).Falsekeeps 50.
Notes
Posterior variables follow the levels:
rho_ℓ(orlam_ℓfor an error process),beta_ℓ,sigma_ℓ, and the effectstheta_ℓforℓ ≥ 1(coordinategroup_ℓ). NUTS also recordstheta_ℓ_raw, the standardized innovations, andsigma2_0.The Gibbs sampler (the default) draws all coefficients and effects in one sparse Gaussian block and integrates them out of every ρ and upper-level σ (
fit(parametrization="collapsed"))."centred","noncentred"and"interweave"update the upper levels’ ρ and σ given the effects, given the standardized innovations, or both in turn — the schemes that carry over to non-Gaussian likelihoods.fit(store_theta=False)skips storing the effects.Examples
>>> from neighbayes.models import Multilevel, Level >>> m = Multilevel( ... Level("score ~ frl", data=schools, W=W_schools), ... Level("~ income", data=districts, W=W_districts, key="district"), ... Level(data=states, W=W_states, key="state", process="SEM"), ... )-
__init__(*levels, priors=
None, logdet_method=None, logdet_decomp='auto', logdet_adapt=True)[source]¶
Methods
__init__(*levels[, priors, logdet_method, ...])fit([draws, tune, chains, target_accept, ...])Draw samples from the posterior.
Return fitted values at posterior mean parameters.
impacts([level, on, ...])Direct, indirect and total effects of one level's covariates.
posterior_predictive([max_draws, random_seed])Replicated outcomes
(G, n), one per draw, given that draw's effects.Return residuals
y - fitted_values.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])Posterior summary of every level's parameters (effects excluded).
Attributes
Number of levels above the units.
Return the ArviZ DataTree from the most recent fit.
Each level's label, the units first.
Return the PyMC model object built for the most recent fit.
-
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"). WhensamplerisNone(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 to0.9for 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.
Noneauto-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 thataz.loo/az.compareneed, 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 topm.sample.- **sample_kwargs¶
For NUTS, forwarded to
pm.sample; for Gibbs, the family’s declared options (an unsupported key raises).
- Return type:¶
xarray.DataTree
-
impacts(level=
0, on='units', return_posterior_samples=False, max_draws=None, exact_max=500, n_probes=64, random_seed=None)[source]¶ Direct, indirect and total effects of one level’s covariates.
- Parameters:¶
- level : int or str, default 0¶
The level whose covariates shift, by number or name.
- on : {"units", "level"}, default "units"¶
"units": the effect on the outcome, through the composed multiplier \(S_0\Delta_0 S_1 \cdots \Delta_{\ell-1} S_\ell\) (\(S_m = (I-\rho_m W_m)^{-1}\) for a lag,Iotherwise). Direct is the mean effect on a unit of a shift in its own group; total, of a shift in every group; indirect, the difference — what arrives from other groups through the filters."level": the effect on the level’s own effects \(\theta_\ell\), through \(S_\ell\) alone. The two agree atlevel=0.- return_posterior_samples : bool, default False¶
Also return the per-draw arrays.
- max_draws : int, optional¶
Thin to this many draws; each draw factors every filter below.
- exact_max : int¶
The own-group trace is exact when the level has at most
exact_maxgroups, else estimated withn_probesRademacher probes.- n_probes : int¶
The own-group trace is exact when the level has at most
exact_maxgroups, else estimated withn_probesRademacher probes.- random_seed : int, optional¶
For the probes.
-
posterior_predictive(max_draws=
None, random_seed=None)[source]¶ Replicated outcomes
(G, n), one per draw, given that draw’s effects.
- 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
logpand the prior under the same model definition used by the NUTS path.
- residuals()[source]¶
Return residuals
y - fitted_values.- Returns:¶
Residual vector
y - fitted_valueson the same scale asfitted_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 matrixWto 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) andattrs["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
Wwas supplied.
See also
spatial_diagnostics_decisionModel-selection decision based on the test results.
impactsPosterior 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’sstge_classicimplements. A model that leaves two directions untested runs a plain and a robust LM test for each:Neither plain test is significant → keep the model.
One is → add that direction.
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 notWXalso rejects (the SAR or SEM then tests it); the lag andWXgo to the robust pair of Koley and Bera [2024], whose lag test is LM-Error at the OLS fit; the error andWX, 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
WXtests are those of Koley and Bera [2024]. Panel models run thePanel-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 agraphviz.Digraphobject that renders inline in Jupyter; if the optionalgraphvizpackage is not installed aUserWarningis issued and the ASCII rendering is returned instead.
- Returns:¶
Recommended model name when
format="model", an ASCII tree string whenformat="ascii", or agraphviz.Digraphwhenformat="graphviz"(with ASCII fallback on missing dep).- Return type:¶
str or graphviz.Digraph
See also
spatial_diagnosticsCompute the Bayesian LM test statistics.
References
Koley and Bera [2024], Anselin et al. [1996], Elhorst [2014]