bayespecon.models.SpatialProbit¶

class bayespecon.models.SpatialProbit(formula=None, data=None, y=None, X=None, W=None, region_col=None, region_ids=None, mobs=None, priors=None, robust=False, backend=None)[source]¶

Bayesian spatial probit with regional random effects.

A binary-response model in which the latent utility includes a spatially autoregressive regional random effect. Each observation \(i\) belongs to one of \(m\) regions; region-level effects \(a\) follow a SAR process on the region-level weights matrix \(W\), and observation-level disturbances are standard Normal (probit link).

\[y_i = \mathbb{1}[z_i > 0],\quad z_i = x_i'\beta + a_{r(i)} + \varepsilon_i,\quad \varepsilon_i \sim \mathcal{N}(0, 1),\]

\[a = \rho W a + u,\quad u \sim \mathcal{N}(0, \sigma_a^2 I_m),\]

so that \(a \sim \mathcal{N}(0, \sigma_a^2 (I_m - \rho W)^{-1} (I_m - \rho W)^{-T})\). The marginal choice probability is \(P(y_i = 1 \mid \beta, a) = \Phi(x_i'\beta + a_{r(i)})\).

Parameters:¶

formula : str, optional¶

Formula for the binary response model, e.g. "y ~ x1 + x2". Requires data and region_col.

data : pandas.DataFrame, optional¶

Data source used with formula mode.

y : array-like, optional¶

Binary dependent variable (0/1), required in matrix mode.

X : array-like or pandas.DataFrame, optional¶

Covariate matrix, required in matrix mode.

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

Region-level m x m spatial weights matrix. 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 or convert with libpysal.graph.Graph.from_W(w). W should be row-standardised; a UserWarning is raised if not.

region_col : str, optional¶

Region identifier column in data (formula mode).

region_ids : array-like, optional¶

Region identifier per observation (matrix mode).

mobs : array-like, optional¶

Region observation counts (m,) in sorted region order (matrix mode alternative to region_ids).

priors : dict, optional¶

Override default priors. Supported keys:

• rho_lower (float, default -0.95): Lower bound of the Uniform prior on \(\rho\).

• rho_upper (float, default 0.95): Upper bound of the 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_a_sigma (float, default 10.0): HalfNormal scale for the regional random-effect std \(\sigma_a\).

robust : bool, default False¶

Not supported. The probit link uses a Normal CDF; a Student-t analogue is not implemented. Setting robust=True raises.

Notes

This class follows the core semip_g structure (binary response with spatially dependent regional effects). It uses a standard probit link with unit observation-level variance and does not currently sample the v_i/ r heteroskedastic hierarchy from legacy semip_g.

Robust regression

robust=True is not supported for SpatialProbit. The probit link function uses a Normal CDF; a robust version would require a Student-t CDF link, which is not yet implemented. Use robust=True with Gaussian models (OLS, SAR, SEM, etc.) instead.

__init__(formula=None, data=None, y=None, X=None, W=None, region_col=None, region_ids=None, mobs=None, priors=None, robust=False, backend=None)[source]¶

Methods

__init__([formula, data, y, X, W, ...])
fit([draws, tune, chains, target_accept, ...])	Draw samples from the posterior.
fitted_probabilities()	Return posterior mean fitted probabilities for observed data.
random_effects_mean()	Return posterior mean regional effects.
spatial_effects([return_posterior_samples])	Compute average marginal effects (AME) for the spatial probit model.
summary([var_names])	Return posterior summary table.

Attributes

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.

fitted_probabilities()[source]¶

Return posterior mean fitted probabilities for observed data.

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

random_effects_mean()[source]¶

Return posterior mean regional effects.

spatial_effects(return_posterior_samples=False)[source]¶

Compute average marginal effects (AME) for the spatial probit model.

For the spatial probit with SAR regional random effects

\[z_i = x_i'\beta + a_{r(i)} + \varepsilon_i, \quad a = \rho W a + u,\]

the marginal effect of covariate \(k\) on the choice probability is

\[\frac{\partial P(y_i=1)}{\partial x_{ik}} = \phi(x_i'\beta + a_{r(i)}) \, \beta_k,\]

where \(\phi(\cdot)\) is the standard-normal PDF.

Because the spatial autoregression enters only through the unobserved regional effects \(a\) (not through a spatial multiplier on \(x\)), there is no indirect effect of \(x_j\) on \(y_i\) for \(i \neq j\). The indirect column is therefore zero and total equals direct.

Parameters:¶

return_posterior_samples : bool, default False¶

If True, also return a dict of posterior draws for each effect type.

Returns:¶

• pandas.DataFrame – One row per non-intercept covariate with columns direct, direct_ci_lower, direct_ci_upper, direct_pvalue, indirect_*, total_*.

• dict, optional – Only returned when return_posterior_samples=True. Keys: direct_samples, indirect_samples, total_samples.

summary(var_names=None, **kwargs)[source]¶

Return posterior summary table.