bayespecon.models.SARPanelRE¶

class bayespecon.models.SARPanelRE(**kwargs)[source]¶

Bayesian spatial lag panel model with unit random effects.

\[y_{it} = \rho (Wy)_{it} + X_{it}\beta + \alpha_i + \varepsilon_{it}\]

where \(\alpha_i \sim N(0, \sigma_\alpha^2)\) are unit-level random effects and \(\varepsilon_{it} \sim N(0, \sigma^2)\).

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.

y : array-like, optional

Stacked response of shape (N*T,). Required in matrix mode.

X : array-like or pandas.DataFrame, optional

Stacked design matrix. Required in matrix mode.

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

Spatial weights of shape (N, N). Should be row-standardised.

unit_col : str, optional

Column in data identifying the cross-sectional unit. Required in formula mode.

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.

T : int, optional

Number of time periods. Required in matrix mode.

priors : dict, optional

Override default priors. Supported keys:

rho_lower (float, default -1.0): Lower bound of Uniform prior on \(\rho\).
rho_upper (float, default 1.0): Upper bound of Uniform prior on \(\rho\).
beta_mu (float, default 0.0): Normal prior mean for \(\beta\).
beta_sigma (float, default 1e6): Normal prior std for \(\beta\).
sigma_sigma (float, default 10.0): HalfNormal prior std for \(\sigma\).
sigma_alpha_sigma (float, default 10.0): HalfNormal prior std for \(\sigma_\alpha\).
nu_lam (float, default 1/30): Rate of TruncExp(lower=2) prior on \(\nu\) (only used when robust=True).

logdet_method : str, optional

How to compute \(\log|I - \rho W|\); auto-selected ("eigenvalue" for N <= 2000 else "chebyshev") when None (default).

robust : bool, default False

If True, replace the Normal error with Student-t. See Robust regression below.

Notes

The base-class model argument is not exposed; pooled mean structure (model=0) is used because unit heterogeneity is captured by the random effect rather than by within-unit demeaning.

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_{it} \sim t_\nu(0, \sigma^2)\]

where \(\nu \sim \mathrm{TruncExp}(\lambda_\nu, \mathrm{lower}=2)\) with rate nu_lam (default 1/30). The default nu_lam = 1/30 gives a prior mean of approximately 30, favouring near-Normal tails. The lower bound of 2 ensures the variance exists.

__init__(**kwargs)[source]¶

Methods

`__init__`(**kwargs)
`fit`([draws, tune, chains, target_accept, ...])	Sample posterior and attach Jacobian-corrected log-likelihood.
`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, idata_kwargs=None, **sample_kwargs)[source]¶

Sample posterior and attach Jacobian-corrected log-likelihood.

The SAR panel RE model uses pm.Normal("obs", observed=y) which auto-captures the Gaussian log-likelihood, plus a pm.Potential Jacobian term that is not captured. When log_likelihood=True is requested, the Jacobian correction is added post-sampling.

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.