bayespecon.models.flow.PoissonSARFlow¶
- class bayespecon.models.flow.PoissonSARFlow(y, G, X, **kwargs)[source]¶
Bayesian SAR flow model with a Poisson observation distribution.
Models origin-destination flow counts \(y_{ij} \in \mathbb{N}_0\) as:
\[y_{ij} \sim \operatorname{Poisson}(\lambda_{ij}), \qquad \log \boldsymbol{\lambda} = A(\boldsymbol{\rho})^{-1} X\beta\]where the system matrix \(A(\rho_d, \rho_o, \rho_w) = I_N - \rho_d W_d - \rho_o W_o - \rho_w W_w\).
The spatial filter is on the log-mean scale. The implicit solve \(\eta = A^{-1} X\beta\) is embedded in the PyMC graph via
SparseFlowSolveOp, which provides NUTS gradients via the adjoint method.- Parameters:¶
- y : array-like, shape (n, n) or (N,)¶
Observed non-negative integer flow counts. Float arrays whose values are close to integers are silently rounded.
- 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.
- **kwargs¶
Passed to
FlowModel.beta_sigmadefaults to 10.
Notes
There is no
sigmaparameter; the Poisson variance equals the mean.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_effects([draws, ...])Summarise posterior origin/destination/intra/network/total effects.
summary([var_names])Return posterior summary table via ArviZ.
Attributes
Return the most recent PyMC variational approximation, if any.
Return ArviZ InferenceData from the most recent fit, or None.
Return the PyMC model used for the most recent fit, or None.
-
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
lambdain 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 thataz.loo/az.waic/az.comparework out of the box; for SAR flow variants the captured Gaussian log-likelihood is post-processed to add the Jacobian contribution fromlog|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
lambdain 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)[source]¶ Draw posterior-predictive samples
y_rep.For each (subsampled) posterior draw, simulates a new flow vector
y_repfrom the implied data-generating process by solving the sparse systemA(rho) y_rep = X β + ε(Gaussian) ory_rep ~ Poisson(exp(A^{-1} X β))(Poisson variants).
- property pymc_model : pymc.model.core.Model | None[source]¶
Return the PyMC model used for the most recent fit, or None.
-
spatial_effects(draws=
None, return_posterior_samples=False, ci=0.95, mode='auto')[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.
- Returns:¶
Long-format summary indexed by
(predictor, side, effect)wheresideis one of"combined","dest","orig".- Return type:¶
pandas.DataFrame, or (DataFrame, dict)