bayespecon.models.flow_panel.FlowPanelModel¶

class bayespecon.models.flow_panel.FlowPanelModel(y, G, X, T, col_names=None, k=None, model=0, priors=None, logdet_method='traces', restrict_positive=True, robust=False, miter=30, titer=800, trace_riter=50, trace_seed=None, symmetric_xo_xd=None, backend=None)[source]¶

Abstract base class for balanced panel spatial flow models.

Parameters:¶

y : array-like¶

Stacked panel response in one of these forms: - shape (T, n, n) - shape (T, n^2) - shape (n^2 * T,)

G : libpysal.graph.Graph¶

Row-standardized graph on n units.

X : np.ndarray or pandas.DataFrame, shape (n^2 * T, p)¶

Stacked panel design matrix in time-first order.

T : int¶

Number of panel periods.

col_names : list[str], optional¶

Feature names for X.

k : int, optional¶

Number of destination/origin covariate pairs used by flow effects. If omitted, inferred from column names with “dest_” prefix.

model : int, default 0¶

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

priors : dict, optional¶

Prior overrides.

logdet_method : str, default "traces"¶

Flow log-determinant method.

restrict_positive : bool, default True¶

If True, use simplex-constrained rho parameters.

robust : bool, default False¶

If True, use Student-t observation errors.

miter=30¶

Flow logdet approximation controls.

titer=800¶

Flow logdet approximation controls.

trace_riter=50¶

Flow logdet approximation controls.

trace_seed=None¶

Flow logdet approximation controls.

__init__(y, G, X, T, col_names=None, k=None, model=0, priors=None, logdet_method='traces', restrict_positive=True, robust=False, miter=30, titer=800, trace_riter=50, trace_seed=None, symmetric_xo_xd=None, backend=None)[source]¶

Methods

__init__(y, G, X, T[, col_names, k, model, ...])
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.