bayespecon.models.panel_base.SpatialPanelModel¶

class bayespecon.models.panel_base.SpatialPanelModel(formula=None, data=None, y=None, X=None, W=None, unit_col=None, time_col=None, N=None, T=None, model=0, priors=None, logdet_method=None, robust=False, w_vars=None, backend=None)[source]¶

Base class for static spatial panel models with FE transforms.

Holds the within-transformation, panel-aware sorting, and weights handling shared by all static fixed-effects panel model subclasses. Not instantiated directly.

Parameters:¶

formula : str, optional¶: Wilkinson-style formula, e.g. "y ~ x1 + x2". Requires data, unit_col, and time_col.
data : pandas.DataFrame, optional¶: Long-format panel data when using formula mode. Must contain the response, regressors, unit_col, and time_col.
y : array-like, optional¶: Stacked response of shape (N*T,) in unit-major order. Required in matrix mode.
X : array-like or pandas.DataFrame, optional¶: Stacked design matrix of shape (N*T, k). Required in matrix mode. DataFrame columns are preserved as feature names.
W : libpysal.graph.Graph or scipy.sparse matrix¶: Spatial weights of shape (N, N) (preferred — broadcast over time periods) or the full (N*T, N*T) block-diagonal panel matrix. Accepts a libpysal.graph.Graph or any scipy.sparse matrix. The legacy libpysal.weights.W object is not accepted; pass w.sparse or libpysal.graph.Graph.from_W(w). Should be row-standardised; a UserWarning is raised otherwise.
unit_col : str, optional¶: Column in data identifying the cross-sectional unit. Required in formula mode for panel sorting and N/T inference.
time_col : str, optional¶: Column in data identifying the time period. Required in formula mode.
N : int, optional¶: Number of cross-sectional units. Required in matrix mode if not inferable from W or the data shape.
T : int, optional¶: Number of time periods. Required in matrix mode if not inferable.
model : int, default 0¶: Fixed-effects specification: 0 pooled, 1 unit FE, 2 time FE, 3 two-way FE. The within transformation is applied to y and X before likelihood evaluation.
priors : dict, optional¶: Override default priors. Supported keys depend on the subclass; each subclass docstring lists its keys with defaults.
logdet_method : str, optional¶: How to compute \(\log|I - \rho W|\). None (default) auto-selects from the cross-sectional N x N weights size: "eigenvalue" for N <= 2000 else "chebyshev".
robust : bool, default False¶: If True, replace the Normal error with Student-t for robustness to heavy-tailed outliers. Adds a nu parameter with a TruncExp(lower=2) prior of rate nu_lam (default 1/30, mean ≈ 30). Override via priors={"nu_lam": value}.
w_vars : list of str, optional¶: Names of X columns to spatially lag. Only relevant for subclasses that include WX terms (SLXPanelFE, SDMPanelFE, SDEMPanelFE and their RE/dynamic analogues). By default all non-constant columns are lagged. Pass a subset, e.g. w_vars=["income", "density"].

__init__(formula=None, data=None, y=None, X=None, W=None, unit_col=None, time_col=None, N=None, T=None, model=0, priors=None, logdet_method=None, robust=False, w_vars=None, backend=None)[source]¶

Methods

`__init__`([formula, data, y, X, W, unit_col, ...])
`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.