bayespecon.SDEMPanelFE¶

class bayespecon.SDEMPanelFE(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, trace_estimator='hutchpp', trace_k=None)[source]¶

Bayesian spatial Durbin error panel regression.

Implements

\[y_{it} = x_{it}'\beta + \Bigl(\sum_j w_{ij} x_{jt}\Bigr)'\theta + \alpha_i + \tau_t + u_{it}, \qquad u_{it} = \lambda \sum_j w_{ij} u_{jt} + \varepsilon_{it}, \qquad \varepsilon_{it} \sim \mathcal{N}(0, \sigma^2).\]

The sampled coefficient vector stacks the local and lagged-covariate blocks as \([\beta, \theta]\).

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) or (N*T, N*T). 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 if not inferable.

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.

priors : dict, optional¶

Override default priors. Supported keys:

lam_lower (float, default -1.0): Lower bound of Uniform prior on \(\lambda\).
lam_upper (float, default 1.0): Upper bound of Uniform prior on \(\lambda\).
beta_mu (array, default Gelman 2008): Normal prior mean for \([\beta, \theta]\).
beta_sigma (array, default Gelman 2008): Normal prior std for \([\beta, \theta]\).
sigma2_alpha (float, default 2.0): InverseGamma shape for \(\sigma^2\).
sigma2_beta (float, default Var(y)): InverseGamma scale for \(\sigma^2\).
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 - \lambda W|\); auto-selected when None (default).

robust : bool, default False¶

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

w_vars : list of str, optional¶

Names of X columns to spatially lag. By default all non-constant columns are lagged.

Notes

Robust regression

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

\[\varepsilon_t = (I - \lambda W)\bigl(y_t - X_t \beta - (W X_t)\theta - \alpha\bigr) \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__(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, trace_estimator='hutchpp', trace_k=None)[source]¶

Methods

`__init__`([formula, data, y, X, W, unit_col, ...])
`fit`([draws, tune, chains, target_accept, ...])	Sample posterior and attach pointwise log-likelihood for IC metrics.
`fitted_values`()	Return fitted values at posterior mean parameters.
`residuals`()	Return transformed residuals `y - fitted`.
`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.
`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, sampler='gibbs', thin=1, n_jobs=-1, progressbar=True, **sample_kwargs)[source]¶

Sample posterior and attach pointwise log-likelihood for IC metrics.

The SDEM panel model uses pm.Potential for both the Gaussian error log-likelihood and the Jacobian on the default (C / Numba) backend, so neither is auto-captured. On JAX backends the model is built via pm.CustomDist with an observed RV, so PyMC populates log_likelihood natively. We compute the complete pointwise log-likelihood manually after sampling only when needed.

fitted_values()[source]¶

Return fitted values at posterior mean parameters.

Returns:¶: Fitted values on transformed panel scale.
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 transformed residuals y - fitted.

Returns:¶: Residual vector on transformed panel scale.
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 OLSPanelFE model runs Panel-LM-Lag, Panel-LM-Error, Panel-LM-SDM-Joint, and Panel-LM-SLX-Error-Joint.

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.