bayespecon.models.flow_panel.SEMFlowPanel¶

class bayespecon.models.flow_panel.SEMFlowPanel(y, G, X, T, **kwargs)[source]¶

Panel spatial-error flow model with three free spatial parameters.

Panel analogue of SEMFlow: applies the Kronecker spatial filter (\(W_d\), \(W_o\), \(W_w\)) to the disturbance rather than the dependent variable, period by period:

\[y_t = X_t \beta + u_t, \qquad B u_t = \varepsilon_t, \quad \varepsilon_t \sim \mathcal{N}(0, \sigma^2 I_N).\]

The Jacobian contribution scales as \(T \cdot \log|B|\) — identical in form to SARFlowPanel. Marginal mean is \(X_t \beta\), so there are no \(X\)-mediated spillovers; effects collapse to the closed-form expressions used by OLSFlowPanel.

Parameters:¶

y : array-like¶

Stacked panel response in shape (T, n, n), (T, n^2), or (n^2 * T,).

G : libpysal.graph.Graph¶

Row-standardised graph on n units.

X¶

Stacked panel design matrix in time-first order.

T : int¶

Number of panel periods (must be a positive integer).

col_names : list of str, optional

Feature names for X. Inferred from a DataFrame if omitted.

k : int, optional

Number of destination/origin covariate pairs used by flow effects; inferred from columns prefixed dest_ if omitted.

model : int, default 0

Fixed-effects transform: 0 pooled, 1 pair FE, 2 time FE, 3 two-way FE.

logdet_method : str, default "traces"

Log-determinant method. Only "traces" is supported here.

restrict_positive : bool, default True

If True, use pm.Dirichlet("lam_simplex", a=ones(4)) to enforce \(\lambda_d, \lambda_o, \lambda_w \geq 0\) and \(\lambda_d + \lambda_o + \lambda_w \leq 1\). If False, three independent pm.Uniform(lam_lower, lam_upper) priors are used with a differentiable quadratic-wall stability potential.

robust : bool, default False

If True, replace the Normal error with Student-t for robustness to heavy-tailed outliers. Adds a nu parameter with prior \(\nu \sim \mathrm{TruncExp}(\lambda_\nu, \mathrm{lower}=2)\), rate nu_lam (default 1/30, mean ≈ 30).

miter : int, default 30

Trace polynomial order for the log-determinant.

titer : int, default 800

Geometric tail cutoff for the log-determinant series.

trace_riter : int, default 50

Number of Monte Carlo probes for trace estimation.

trace_seed : int, optional

Random seed for trace estimation reproducibility.

symmetric_xo_xd : bool, optional

If None (default), origin and destination design blocks are compared and symmetry is auto-detected.

priors : dict, optional

Override default priors. Supported keys:

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.
lam_lower : float, default -1.0 — Lower bound of Uniform prior on each λ (only when restrict_positive=False).
lam_upper : float, default 1.0 — Upper bound of Uniform prior on each λ (only when restrict_positive=False).
nu_lam : float, default 1/30 — Rate of TruncExp prior on nu (only when robust=True).

__init__(y, G, X, T, **kwargs)[source]¶

Methods

`__init__`(y, G, X, T, **kwargs)
`fit`([draws, tune, chains, target_accept, ...])	Draw samples from the posterior.
`fit_approx`([draws, n, method, random_seed, ...])	Fit a variational approximation and return posterior draws.
`posterior_predictive`([n_draws, random_seed, ...])	Draw posterior-predictive samples `y_rep` for the full panel stack.
`spatial_diagnostics`()	Run Bayesian LM specification tests for flow panel models.
`spatial_diagnostics_decision`([alpha, ...])	Return a model-selection decision from Bayesian LM test results.
`spatial_effects`([draws, ...])	Summarise posterior origin/destination/intra/network/total effects.
`summary`([var_names])	Return posterior summary table via ArviZ.

Attributes

`approximation`	Return the most recent PyMC variational approximation, if any.
`inference_data`	Return posterior draws from the most recent fit.
`pymc_model`	Return the most recently built PyMC model.

property approximation[source]¶: Return the most recent PyMC variational approximation, if any.

fit(draws=2000, tune=1000, chains=4, target_accept=0.9, random_seed=None, store_lambda=False, idata_kwargs=None, **sample_kwargs)[source]¶: Draw samples from the posterior.

fit_approx(draws=2000, n=10000, method='advi', random_seed=None, store_lambda=False, compute_log_likelihood=True, **fit_kwargs)[source]¶: Fit a variational approximation and return posterior draws.

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

posterior_predictive(n_draws=None, random_seed=None, parallel=-1)[source]¶

Draw posterior-predictive samples y_rep for the full panel stack.

Parameters:¶

n_draws : int, optional¶: Number of posterior draws to use. Defaults to all.
random_seed : int, optional¶: Seed for the noise/Poisson sampler.
parallel : int or None, default -1¶: Number of worker threads for the per-draw loop. -1 uses os.cpu_count(); None/0/1 forces sequential execution. Reproducibility under a fixed random_seed is preserved across worker counts via SeedSequence.spawn.

Returns:¶

Array of shape (n_draws, N_flow * T) with posterior-predictive flows in time-first stacked order.

Return type:¶

np.ndarray

property pymc_model : pymc.model.core.Model | None[source]¶: Return the most recently built PyMC model.

spatial_diagnostics()[source]¶

Run Bayesian LM specification tests for flow panel models.

See bayespecon.models.base.SpatialModel.spatial_diagnostics() for the column schema.

Raises:¶: RuntimeError – If the model has not been fit yet.

spatial_diagnostics_decision(alpha=0.05, format='graphviz', theme='default')[source]¶

Return a model-selection decision from Bayesian LM test results.

Walks the panel-flow decision tree using Bayesian p-values from spatial_diagnostics() and recommends either OLSFlowPanel (no spatial dependence detected) or SARFlowPanel (at least one direction is significant).

Parameters:¶

alpha : float, default 0.05¶: Significance level for the Bayesian p-values.
format : {"graphviz", "ascii", "model"}, default "graphviz"¶: Output format. "model" returns the recommended model name string. "ascii" returns an indented box-drawing tree. "graphviz" returns a graphviz.Digraph (with ASCII fallback if graphviz is not installed).

Return type:¶

str or graphviz.Digraph

spatial_effects(draws=None, return_posterior_samples=False, ci=0.95, mode='auto', parallel=-1)[source]¶

Summarise posterior origin/destination/intra/network/total effects.

See bayespecon.models.flow.FlowModel.spatial_effects() for the mode semantics (auto / combined / separate destination-origin sides per Thomas-Agnan & LeSage 2014, §83.5.2) and the parallel kwarg.

summary(var_names=None, **kwargs)[source]¶: Return posterior summary table via ArviZ.