neighbayes.dgp.generate_panel_negbin_flow_data

neighbayes.dgp.generate_panel_negbin_flow_data(n=None, T=5, G=None, rho_d=0.3, rho_o=0.2, rho_w=0.1, beta_d=None, beta_o=None, alpha=2.0, gamma_dist=-0.5, seed=42, k=2, k_d=None, k_o=None, err_hetero=False, gdf=None, knn_k=4)[source]

Generate panel NB2 flow counts from a spatial autoregressive DGP.

For each period \(t = 1, \dots, T\), generates \(N = n^2\) flow counts from:

\[\eta_t = A^{-1} X_t \beta, \quad y_{ij,t} \sim \operatorname{NegBin}(\mu=\exp(\eta_{ij,t}),\, \alpha)\]

where the system matrix is

\[A = I_N - \rho_d (I_n \otimes W) - \rho_o (W \otimes I_n) - \rho_w (W \otimes W), \quad N = n^2\]

Observations are stacked in time-first order. There is no \(\sigma\) parameter (the NB variance is determined by the mean and alpha).

Parameters:
n : int

Number of spatial units. Must match the size of G.

T : int, default 5

Number of time periods.

G : libpysal.graph.Graph

Row-standardized spatial graph on n units.

rho_d : float, default 0.3

Destination autocorrelation parameter.

rho_o : float, default 0.2

Origin autocorrelation parameter.

rho_w : float, default 0.1

Network autocorrelation parameter.

beta_d : float or list of float or None, default None

Destination-side coefficients for the k attributes. A scalar broadcasts to all columns. Defaults to 1.0 for all columns.

beta_o : float or list of float or None, default None

Origin-side coefficients. Defaults to 1.0 for all columns.

alpha : float, default 2.0

NB2 dispersion parameter. Must be strictly positive.

gamma_dist : float, default -0.5

Coefficient on the log-distance regressor.

seed : int, default 42

Seed for numpy.random.default_rng.

k : int, default 2

Number of destination/origin attribute columns.

err_hetero : bool, default False

Accepted for API parity with other DGP functions; ignored for the NB model (the variance is determined by the mean and alpha).

gdf : object, optional

Accepted for API parity with other DGP functions; not used (pass G directly instead).

Returns:

Dictionary with keys:

  • "y" (n²T,): time-first stacked count vector (int64).

  • "lambda" (n²T,): time-first stacked NB means.

  • "X" (n²T, p): time-first stacked O-D design matrix.

  • "col_names" list[str]: feature names.

  • "G" libpysal.graph.Graph: spatial graph.

  • "rho_d", "rho_o", "rho_w": true parameters.

  • "beta_d", "beta_o": true coefficient vectors.

  • "alpha": true NB2 dispersion parameter.

  • "params_true" dict: nested dict of all true parameters.

Return type:

dict

Raises:

ValueError – If alpha <= 0 or the A matrix is singular.