bayespecon.models.flow.PoissonSARFlowSeparable¶

class bayespecon.models.flow.PoissonSARFlowSeparable(y, G, X, **kwargs)[source]¶

Bayesian separable SAR flow model with a Poisson observation distribution.

Combines the Poisson observation model of PoissonSARFlow with the separability constraint \(\rho_w = -\rho_d \rho_o\), enabling the exact eigenvalue-based log-determinant:

\[\log|A| = n\,\log|I_n - \rho_d W| + n\,\log|I_n - \rho_o W|\]

Parameters:¶

y : array-like of int, shape (n, n) or (N,)¶

Observed non-negative integer flow counts. Float arrays whose values round exactly to integers are silently coerced.

G : libpysal.graph.Graph¶

Row-standardised spatial graph on n units.

X : np.ndarray or pandas.DataFrame, shape (N, p)¶

Full origin-destination design matrix with \(N = n^2\) rows. DataFrame columns are preserved as feature names.

col_names : list of str, optional

Column labels for X. Inferred from a DataFrame if omitted.

k : int, optional

Number of regional attribute columns. Inferred from dest_*/orig_* column names when the standard LeSage layout is used.

logdet_method : {"eigenvalue", "chebyshev", "trace_mc"}, default "eigenvalue"

Method for the Kronecker-factored log-determinant.

miter : int, default 30

Polynomial / approximation order (used by "chebyshev" / "trace_mc").

titer : int, default 800

Geometric tail cutoff for series-based variants.

trace_riter : int, default 50

Number of Monte Carlo probes (used by "trace_mc").

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 10.0 — Normal prior std for beta.
rho_lower : float, default -0.999 — Lower bound of Uniform prior on rho_d and rho_o.
rho_upper : float, default 0.999 — Upper bound of Uniform prior on rho_d and rho_o.

Notes

There is no sigma parameter; the Poisson variance equals the mean. Robust (Student-t) likelihoods are not supported for Poisson counts. The restrict_positive argument has no effect on this class.

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

Methods

`__init__`(y, G, X, **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`.
`spatial_diagnostics`()	Run Bayesian LM specification tests for flow 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 ArviZ InferenceData from the most recent fit, or None.
`pymc_model`	Return the PyMC model used for the most recent fit, or None.

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.

Parameters:¶

draws : int, default 2000¶: Number of posterior samples per chain (after tuning).
tune : int, default 1000¶: Number of tuning (warm-up) steps per chain.
chains : int, default 4¶: Number of parallel chains.
target_accept : float, default 0.9¶: Target acceptance rate for NUTS.
random_seed : int, optional¶: Seed for reproducibility.
store_lambda : bool, default False¶: If True, include the high-dimensional fitted mean lambda in the stored posterior. Leaving this False reduces memory and conversion overhead for Poisson flow models.
idata_kwargs : dict, optional¶: Forwarded to pm.sample. Defaults to {"log_likelihood": True} so that az.loo / az.waic / az.compare work out of the box; for SAR flow variants the captured Gaussian log-likelihood is post-processed to add the Jacobian contribution from log|I_N - rho_d W_d - rho_o W_o - rho_w W_w|.
**sample_kwargs¶: Additional keyword arguments forwarded to pm.sample.

Return type:¶

arviz.InferenceData

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.

Parameters:¶

draws : int, default 2000¶: Number of samples to draw from the fitted approximation.
n : int, default 10000¶: Number of optimisation iterations for pm.fit.
method : {"advi", "fullrank_advi"}, default "advi"¶: Variational inference family to fit.
random_seed : int, optional¶: Seed for optimisation and posterior sampling.
store_lambda : bool, default False¶: If True, keep the high-dimensional fitted mean lambda in the posterior draws.
compute_log_likelihood : bool, default True¶: If True, compute pointwise log-likelihood after sampling and attach to the InferenceData (with Jacobian correction for SAR flow variants), enabling az.loo / az.waic.
**fit_kwargs¶: Additional keyword arguments forwarded to pm.fit.

property inference_data : arviz.data.inference_data.InferenceData | None[source]¶: Return ArviZ InferenceData from the most recent fit, or None.

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

Draw posterior-predictive samples y_rep.

For each (subsampled) posterior draw, simulates a new flow vector y_rep from the implied data-generating process by solving the sparse system A(rho) y_rep = X β + ε (Gaussian) or y_rep ~ Poisson(exp(A^{-1} X β)) (Poisson variants).

Parameters:¶

n_draws : int, optional¶: Number of posterior draws to use. Defaults to all available.
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) with posterior-predictive flows.

Return type:¶

np.ndarray

property pymc_model : pymc.model.core.Model | None[source]¶: Return the PyMC model used for the most recent fit, or None.

spatial_diagnostics()[source]¶

Run Bayesian LM specification tests for flow models.

Iterates over the class-level _spatial_diagnostics_tests registry and returns a tidy DataFrame with one row per test. 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 flow decision tree using Bayesian p-values from spatial_diagnostics() and recommends either OLSFlow (no spatial dependence detected) or SARFlow (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.

Wraps _compute_spatial_effects_posterior() to produce a tidy DataFrame indexed by predictor with posterior means, credible-interval bounds, and Bayesian p-values for each effect type (origin, destination, intra, network, total). Following Thomas-Agnan & LeSage (2014, §83.5.2), when destination and origin design blocks differ the decomposition is reported separately for shocks applied to each side.

Parameters:¶

draws : int, optional¶: Maximum number of posterior draws to use. Defaults to all.
return_posterior_samples : bool, default False¶: If True, also return the underlying posterior-draw arrays.
ci : float, default 0.95¶: Credible-interval coverage.
mode : {"auto", "combined", "separate"}, default "auto"¶: Controls whether destination- and origin-side effects are summed or reported separately. "auto" collapses to combined when the destination and origin design blocks are identical (self._symmetric_xo_xd) and reports both sides otherwise. "combined" always sums; "separate" always reports both.
parallel : int or None, default -1¶: Number of worker threads for the per-draw effects loop. -1 uses os.cpu_count(); None/0/1 forces sequential execution. Ignored by closed-form (OLSFlow, SEMFlow) variants.

Returns:¶

Long-format summary indexed by (predictor, side, effect) where side is one of "combined", "dest", "orig".

Return type:¶

pandas.DataFrame, or (DataFrame, dict)

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

Return posterior summary table via ArviZ.

Parameters:¶

var_names : list, optional¶: Variable names to include. Defaults to all parameters.
**kwargs¶: Additional keyword arguments forwarded to az.summary.

Return type:¶

pandas.DataFrame