neighbayes.dgp.simulate_sar_zinb

neighbayes.dgp.simulate_sar_zinb(n_side=None, W=None, gdf=None, rho=0.5, rho_zero=0.3, beta=None, beta_zero=None, alpha=2.0, X_zero=None, X=None, W_zero=None, rng=None, seed=None, contiguity='queen', target_pi=None, err_hetero=False, create_gdf=False, geometry_type='polygon', latent=True, *, T=None, N=None, unit_effects=None, time_effects=False, unit_effect_sd=None, time_effect_sd=None)[source]

Simulate data from a zero-inflated SAR-NB DGP.

Two-part model:

Zero part (unit activity — reduced-form SAR logit):

\[d_i \sim \text{Bernoulli}(\text{logit}^{-1}(\eta_{z,i})), \quad \eta_z = (I - \rho_z W_z)^{-1} X_z\beta_z,\]

the reduced-form zero part SARZINB fits. (Until 2026-10-03 a latent ν ~ N(0, I) was added inside the filter, a random effect the model does not have, which attenuated the β_z estimates.)

Count part (volume — reduced-form SAR-NB):

\[y_i \mid d_i = 1 \sim \text{NegBin}(\exp(\eta^{\text{cnt}}_i), \alpha), \quad \eta^{\text{cnt}} = (I - \rho W_{\text{cnt}})^{-1} X\beta\]

Observation:

\[y_i = 0 \text{ if } d_i = 0, \quad y_i \sim \text{NegBin}(\cdot) \text{ if } d_i = 1\]

With latent=True, the default, it draws the latent model the unmarked SARZINB fits, each part’s own disturbance propagated: \(d_i = \mathbf 1(u_i > 0)\), \(u = (I - \rho_z W_z)^{-1}(X_z\beta_z + \varepsilon_z)\) with \(\varepsilon_z\) logistic, and \(y_i \mid d_i = 1 \sim \mathrm{Poisson}(e^{\eta_i})\), \(\eta = (I - \rho W)^{-1}(X\beta + \varepsilon)\) with \(\varepsilon_i = \log\gamma_i\), \(\gamma_i \sim \mathrm{Gamma}(\alpha, \alpha)\); eta_zero and eta_cnt are then the drawn u and eta.

Parameters:
n_side : int, optional

Side length of the square rook grid used when neither W nor gdf is supplied (n_side**2 observations).

W : Graph or scipy.sparse matrix, optional

Spatial weights for the count part. Also used for the zero part when W_zero is not provided.

gdf : GeoDataFrame, optional

Geodataframe used to construct weights.

rho : float, default 0.5

Spatial autoregressive parameter for the count part.

rho_zero : float, default 0.3

Spatial autoregressive parameter for the zero part.

beta : ndarray, optional

Count-part coefficients (including intercept). Defaults to [1.0, 0.6].

beta_zero : ndarray, optional

Zero-part coefficients (including intercept). Defaults to [0.3, 1.0].

alpha : float, default 2.0

NB2 dispersion parameter. Must be strictly positive.

X_zero : ndarray, optional

Zero-part covariate matrix of shape (nobs, p). If not provided, a random design matrix is generated from beta_zero.

X : ndarray, optional

Count covariate matrix of shape (nobs, k). If not provided, a random design matrix is generated from beta.

W_zero : Graph or scipy.sparse matrix, optional

Spatial weights for the zero part. If None, uses W (the same weights in both parts).

rng : numpy.random.Generator, optional

Random number generator.

seed : int, optional

Random seed (used only if rng is None).

contiguity : str, default "queen"

Neighbor rule used when W is built from gdf.

target_pi : float, optional

If given, an intercept shift is solved so that the marginal activation probability mean(pi) == target_pi. The shift is added to beta_zero[0] (inside the filter, so the reported beta_zero generates eta_zero).

err_hetero : bool, default False

Not implemented for ZINB models. If True, a warning is issued and the parameter is ignored (homoskedastic errors are used).

create_gdf : bool, default False

Whether to attach a GeoDataFrame to the output.

geometry_type : str, default "polygon"

Type of geometry for the GeoDataFrame.

Returns:

Keys: y, d, X, X_zero, eta_cnt, eta_zero, W_sparse, W_graph, W_zero_sparse, W_zero_graph, params_true.

Return type:

dict