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, backend=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 for n <= 2000) pre-computes W’s eigenvalues once and evaluates O(n) per step; "exact" uses symbolic pytensor det (slow for n > 500); "grid_dense" uses dense eigenvalue grid + cubic-spline interpolation (MATLAB-style lndetfull for dense W); "grid_sparse" uses sparse-LU grid + cubic-spline interpolation (lndetfull style for large sparse W); "sparse_spline" uses sparse-LU + spline on [max(rho_min, 0), rho_max] (lndetint style); "grid_mc" uses Monte Carlo trace approximation (lndetmc); "grid_ilu" uses ILU-based approximation (lndetichol analog); "chebyshev" (default for n > 2000) uses a Chebyshev polynomial approximation evaluated via Clenshaw’s algorithm.
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, backend=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 (or transformed-panel) 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. Pass nuts_sampler="blackjax" (or "numpyro", "nutpie") to select an alternative NUTS backend; defaults to PyMC’s built-in sampler.

Return type:¶

arviz.InferenceData

fitted_values()[source]¶: Return fitted values at posterior mean parameters.

property inference_data : arviz.data.inference_data.InferenceData | None[source]¶: Return the ArviZ InferenceData from the most recent fit.

property pymc_model : pymc.model.core.Model | None[source]¶: Return the PyMC model object built for the most recent fit.

residuals()[source]¶: Return residuals on the observed (or transformed-panel) scale.

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.

Requires the model to have been fit (.fit() called). For cross-sectional models a spatial weights matrix W must also have been supplied at construction time.

Returns:¶

DataFrame indexed by test name with columns statistic (posterior mean), median, df (degrees of freedom for the \(\chi^2\) reference), p_value (Bayesian p-value 1 - chi2.cdf(mean, df)), and ci_lower / ci_upper (95% credible interval). The DataFrame carries attrs["model_type"] and attrs["n_draws"] metadata.

Return type:¶

pandas.DataFrame

Raises:¶

RuntimeError – If the model has not been fit yet.
ValueError – If a cross-sectional model was constructed without W.