bayespecon.models.base.SpatialModel¶

class bayespecon.models.base.SpatialModel(formula=None, data=None, y=None, X=None, W=None, priors=None, logdet_method=None, robust=False, w_vars=None)[source]¶

Base class for Bayesian spatial regression models. Models follow the notation of [Anselin, 1988] and [LeSage and Pace, 2009]. The API supports both formula and matrix input modes.

Parameters:¶

formula : str, optional¶: Wilkinson-style formula string, e.g. "price ~ poverty + rev_rating". If provided, data must also be supplied. An intercept is included by default; suppress with "y ~ x - 1".
data : DataFrame or GeoDataFrame, optional¶: Data source when using formula mode.
y : array-like, optional¶: Dependent variable. Required in matrix mode.
X : array-like, optional¶: Predictor matrix. Required in matrix mode. If a DataFrame, column names are preserved for labelling.
W : libpysal.graph.Graph or scipy.sparse matrix¶: Spatial weights matrix of shape (n, n). Accepts a libpysal.graph.Graph (the modern libpysal graph API) or any scipy.sparse matrix. The legacy libpysal.weights.W object is not accepted directly; pass w.sparse to use the underlying sparse matrix, or convert with libpysal.graph.Graph.from_W(w). W should be row-standardised; a UserWarning is raised if not.
priors : dict, optional¶: Override default priors. Keys depend on the model subclass; see each model’s docstring for supported keys.
logdet_method : str¶: How to compute log|I - rho*W|. "eigenvalue" (default) pre-computes W’s eigenvalues once and evaluates O(n) per step; "exact" uses symbolic pytensor det (slow for n > 500); "grid" uses spline interpolation (approximate); "full" uses sparse-LU grid (MATLAB-style lndetfull); "int" uses sparse-LU + spline interpolation (lndetint); "mc" uses Monte Carlo trace approximation (lndetmc); "ichol" uses ILU-based approximation (lndetichol analog).
robust : bool, default False¶: If True, use a Student-t error distribution instead of Normal, yielding a model that is robust to heavy-tailed outliers. When robust=True, a nu (degrees of freedom) parameter is added to the model with an \(\mathrm{Exp}(\lambda_\nu)\) prior (default nu_lam = 1/30, mean ≈ 30). The nu prior can be controlled via the priors dict with key nu_lam.
w_vars : list of str, optional¶: Names of X columns to spatially lag. Only relevant for models that include WX terms (SLX, SDM, SDEM and their panel/Tobit variants). By default all non-constant columns are lagged. Pass a subset to restrict which variables receive a spatial lag, e.g. w_vars=["income", "density"].

__init__(formula=None, data=None, y=None, X=None, W=None, priors=None, logdet_method=None, robust=False, w_vars=None)[source]¶

Methods

`__init__`([formula, data, y, X, W, priors, ...])
`fit`([draws, tune, chains, target_accept, ...])	Draw samples from the posterior.
`fitted_values`()	Return fitted values at posterior mean parameters.
`residuals`()	Return residuals on the observed scale.
`spatial_diagnostics`()	Run Bayesian LM specification tests and return a summary table.
`spatial_diagnostics_decision`([alpha])	Return a model-selection decision from Bayesian LM test results.
`spatial_effects`([return_posterior_samples])	Compute Bayesian inference for direct, indirect, and total impacts.
`summary`([var_names])	Return posterior summary table.

Attributes

`inference_data`	Return the ArviZ InferenceData 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=0.9, random_seed=None, **sample_kwargs)[source]¶

Draw samples from the posterior.

Parameters:¶

draws : int¶: Number of posterior samples per chain (after tuning).
tune : int¶: Number of tuning (burn-in) steps per chain.
chains : int¶: Number of parallel chains.
target_accept : float¶: Target acceptance rate for NUTS.
random_seed : int, optional¶: Seed for reproducibility.
**sample_kwargs¶: Additional keyword arguments forwarded to pm.sample.

Return type:¶

arviz.InferenceData

fitted_values()[source]¶

Return fitted values at posterior mean parameters.

Returns:¶: Posterior-mean fitted values.
Return type:¶: np.ndarray

property inference_data : arviz.data.inference_data.InferenceData | None[source]¶

Return the ArviZ InferenceData from the most recent fit.

Returns:¶: The inference data object, or None if the model has not been fit yet.
Return type:¶: arviz.InferenceData or None

property pymc_model : pymc.model.core.Model | None[source]¶

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

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 on the observed scale.

Returns:¶: Residual vector y - fitted_values.
Return type:¶: np.ndarray

spatial_diagnostics()[source]¶

Run Bayesian LM specification tests and return a summary table.

Iterates over the class-level _spatial_diagnostics_tests registry 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.

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.
spatial_effects: 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)[source]¶

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

Implements the decision tree from Koley and Bera [2024] (the Bayesian analogue of the classical stge_kb procedure in Anselin et al. [1996]). The decision logic depends on the current model type and the pattern of significant tests:

From OLS (4-test decision tree):

If LM-SDM-Joint is significant → test Robust-LM-Lag-SDM and Robust-LM-Error-SDEM (requires re-fitting SLX first). If neither robust test is significant → OLS.
If LM-Lag is significant and LM-Error is not → SAR.
If LM-Error is significant and LM-Lag is not → SEM.
If both are significant → test Robust-Lag and Robust-Error. If Robust-Lag is significant → SAR; if Robust-Error → SEM; if neither → SARAR (both lag and error).

From SAR (3-test decision tree):

LM-Error significant → SARAR; LM-WX significant → SDM; Robust-LM-WX significant → SDM.

From SEM (2-test decision tree):

LM-Lag significant → SARAR; LM-WX significant → SDEM.

From SLX (4-test decision tree):

Robust-LM-Lag-SDM significant → SDM; Robust-LM-Error-SDEM significant → SDEM; both → MANSAR; neither → SLX.

From SDM: LM-Error significant → MANSAR; else SDM.

From SDEM: LM-Lag significant → MANSAR; else SDEM.

Parameters:¶

alpha : float, default 0.05¶: Significance level for the Bayesian p-values.

Returns:¶

Recommended model name (e.g. "SAR", "SDM", "OLS").

Return type:¶

str