neighbayes.models.OLS

class neighbayes.models.OLS(formula=None, data=None, y=None, X=None, W=None, *, unit_effects=None, time_effects=False, dynamic=False, centered=False, 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 ordinary least squares cross-sectional regression.

\[y = X\beta + \varepsilon, \quad \varepsilon \sim N(0, \sigma^2 I)\]

This model places diffuse Normal priors on the coefficient vector \(\beta\) and a HalfNormal prior on the noise standard deviation \(\sigma\).

W is optional. If supplied, Bayesian LM tests can be run on the OLS posterior to guide model selection.

Robust regression

When robust=True, the error distribution is changed from Normal to Student-t, yielding a model that is robust to heavy-tailed outliers:

\[\varepsilon \sim t_\nu(0, \sigma^2 I)\]

where \(\nu\) is a fixed hyperparameter set by priors={"nu": value} (default 4, LeSage’s rval); larger values approach the Normal. Values must exceed 2 so the variance exists.

Parameters:
formula : str, optional

Wilkinson-style formula string, e.g. "price ~ poverty + income". If provided, data must also be supplied.

data : pandas.DataFrame or geopandas.GeoDataFrame, optional

Data source when using formula mode.

y : array-like, optional

Dependent variable of shape (n,). Required in matrix mode.

X : array-like or pandas.DataFrame, optional

Predictor matrix. Required in matrix mode.

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

Spatial weights matrix of shape (n, n). Not used during estimation; required for Bayesian LM specification tests.

priors : dict, optional

Override default priors. Supported keys:

  • beta_mu (array or float, optional): Prior mean for \(eta\). Default is Gelman et al. (2008) weakly-informative mean (mean(y) for intercept/constant columns, 0 for slopes).

  • beta_sigma (array or float, optional): Prior std for \(eta\). Default is Gelman et al. (2008) weakly-informative scale: 2.5 * sd(y) for intercept/constant columns and 2.5 * sd(y) / sd(x_j) for each slope.

  • sigma2_alpha (float, default 2.0): Shape of the InverseGamma prior on \(\sigma^2\).

  • sigma2_beta (float, default Var(y)): Scale of the InverseGamma prior on \(\sigma^2\).

  • nu (float, default 4.0): Fixed Student-t degrees of freedom (only used when robust=True).

robust : bool, default False

If True, use a Student-t error distribution instead of Normal.

time_col : str, optional

Formula-mode panel: the period and unit columns of data. Given time, the model is a panel, stacked by period, then unit.

unit_col : str, optional

Formula-mode panel: the period and unit columns of data. Given time, the model is a panel, stacked by period, then unit.

N : int, optional

Matrix-mode panel: the numbers of units and periods; T=1 is the cross-section.

T : int, optional

Matrix-mode panel: the numbers of units and periods; T=1 is the cross-section.

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

Panel unit effects: "fixed" applies the within transformation (with Lee and Yu’s 2010 likelihood dimensions), "random" adds a normal effect per unit, unit_effect with sd unit_effect_sd (priors unit_effect_sd_nu and unit_effect_sd_scale, half-Cauchy on sd(y) by default).

time_effects : bool, default False

Fixed time effects (panels).

dynamic : bool, default False

Add the time lag \(\phi y_{t-1}\) (priors phi_lower, phi_upper). A dynamic panel takes no unit effects (Nickell 1981).

centered : bool, default False

With random unit effects, sample them centered under NUTS rather than as \(\alpha_i = \sigma_\alpha z_i\); better when every unit has many observations.

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

Methods

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

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

Draw samples from the posterior.

fitted_values()

Return fitted values at posterior mean parameters.

impacts([return_posterior_samples])

Compute Bayesian inference for direct, indirect, and total impacts.

predict(X_new, W[, oos, thin, random_seed])

Posterior predictive distribution of y at new units.

predict_in_sample(*[, thin, random_seed])

Leave-one-out conditional predictive of each fitted unit.

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.

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.

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(return_posterior_samples=False)[source]

Compute Bayesian inference for direct, indirect, and total impacts.

Computes impact measures for each posterior draw, then summarizes the posterior distribution with means, 95% credible intervals, and Bayesian p-values. This is the fully Bayesian analog of the simulation-based approach in LeSage and Pace [2009] and the asymptotic variance formulas in Arbia et al. [2020].

Models without a spatial lag on y do not exhibit global feedback propagation through \((I-\\rho W)^{-1}\). However, models with spatially lagged covariates (SLX, SDEM) can still have non-zero neighbor spillovers captured in the indirect term.

Parameters:
return_posterior_samples : bool, optional

If True, return a (DataFrame, dict) tuple where the dict contains the full posterior draws under keys "direct", "indirect", and "total". Default False.

Returns:

If return_posterior_samples is False (default), returns a DataFrame indexed by feature names with columns for posterior means, credible-interval bounds, and Bayesian p-values.

If return_posterior_samples is True, returns (DataFrame, dict) where the dict has keys "direct", "indirect", "total", each mapping to a (G, k) array of posterior draws.

Return type:

pd.DataFrame or tuple of (pd.DataFrame, dict)

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

predict(X_new, W, oos=None, *, thin=1, random_seed=None)[source]

Posterior predictive distribution of y at new units.

For each posterior draw the outcome at the new units \(O\), given the fitted outcomes \(y_S\), is exactly

\[y_O \mid y_S \sim N\bigl(\mu_O - \Lambda_{OO}^{-1} \Lambda_{OS}(y_S - \mu_S),\; \Lambda_{OO}^{-1}\bigr), \qquad \Lambda = (I - \theta W)^{\top}(I - \theta W)/\sigma^2,\]

the best predictor (BP) of Goulard et al. [2017] (eq. 9) at that draw. \(\theta\) is \(\rho\) for SAR and SDM, \(\lambda\) for SEM and SDEM, and zero for OLS and SLX, whose predictive is \(N(\mu_O, \sigma^2 I)\). The marginal mean \(\mu\) is \((I - \rho W)^{-1} Z\beta\) for the lag models and \(Z\beta\) otherwise, computed on the union graph.

Parameters:
X_new : DataFrame or array of shape (n_new, k)

Covariates of the new units. For a model built from a formula, a DataFrame with the variables the formula uses; the formula’s transforms are replayed on it. Otherwise, columns in the order of the fitted X (or a DataFrame with its column names).

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

Weights over the union of fitted and new units, n_fit + n_new square, standardized the way the fitted W was. For SLX, SDM and SDEM the lagged covariates of every unit are recomputed on this graph, since a fitted unit with a new neighbor gets a new WX row.

oos : array of int, optional

Positions of the new units in W, in the row order of X_new; the fitted units fill the remaining positions in their fitted order. Defaults to the last n_new positions.

thin : int, default 1

Use every thin-th draw of each chain.

random_seed : int, optional

Seed for the predictive draws.

Returns:

A predictions group with dimensions (chain, draw, obs_new) holding y (posterior predictive draws), y_bp (the conditional mean at each draw; its average over draws is the posterior predictive mean) and y_tc (the trend predictor \(\mu_O\), which ignores the observed neighbors), and a predictions_constant_data group with X_new. Comparing y_bp with y_tc shows what the spatial correction adds.

Return type:

xarray.DataTree

Notes

The parameters were estimated on the fitted units’ W, and the prediction uses the union W: the feasible practice of Goulard et al. [2017] (their eq. 8).

predict_in_sample(*, thin=1, random_seed=None)[source]

Leave-one-out conditional predictive of each fitted unit.

For each unit \(i\) and posterior draw, the distribution of \(y_i\) given every other fitted outcome is

\[y_i \mid y_{-i} \sim N\bigl(y_i - (\Lambda r)_i/\Lambda_{ii}, \; 1/\Lambda_{ii}\bigr), \qquad r = y - \mu,\]

the in-sample BP of Goulard et al. [2017] (eq. 14). All units together cost one sparse matrix-vector product per draw.

The draws condition on the posterior from the full data, which includes \(y_i\), so this is a smoother, not cross-validation; use neighbayes.diagnostics.spatial_kfold() to score held-out predictive accuracy.

Parameters:
thin : int, default 1

Use every thin-th draw of each chain.

random_seed : int, optional

Seed for the predictive draws.

Returns:

A predictions group with dimensions (chain, draw, obs) holding y (draws), y_bp (the leave-one-out conditional mean) and y_tc (the marginal mean \(\mu\)). Each unit’s draws follow its own conditional; they are marginally correct per unit but not a joint draw across units.

Return type:

xarray.DataTree

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