neighbayes.dgp.simulate_multilevel

neighbayes.dgp.simulate_multilevel(n_side=24, blocks=(4, 2), processes=('SAR', 'SAR', 'SAR'), rhos=(0.4, 0.5, 0.4), betas=None, sigmas=(1.0, 0.5, 0.5), gdf=None, err_hetero=False, rng=None, seed=None)[source]

Simulate nested levels with a graph and a process at each.

Level 0 is an n_side × n_side grid of units. Level ℓ’s groups are blocks[ℓ−1] × blocks[ℓ−1] blocks of level ℓ−1’s groups, so level ℓ has (n_side / (b_1⋯b_ℓ))² groups. Every level’s graph is the row-standardized rook adjacency of its own grid. From the top down,

\[\theta_\ell = S_\ell(X_\ell\beta_\ell + \Delta_\ell\theta_{\ell+1} + \sigma_\ell\varepsilon_\ell)\]

for a SAR level (\(S_\ell = (I-\rho_\ell W_\ell)^{-1}\)); a SEM level filters only the innovation, and an aspatial level (None) nothing. \(y = \theta_0\).

Parameters:
n_side : int, default 24

Side of the unit grid; must be divisible by prod(blocks).

blocks : sequence of int, default (4, 2)

Block side of each upper level, in groups of the level below.

processes : sequence of {"SAR", "SEM", None}

One per level, the units first, as Level takes them. The simulator draws no Durbin terms.

rhos : sequence of float

The autoregressive parameter of each level (ignored for None).

betas : sequence of sequences, optional

Coefficients per level. The units’ include the intercept first; upper levels have none. Default: [1, 1, -1] at the units and [0.5] above.

sigmas : sequence of float

Innovation sd per level.

gdf : None

Not supported (the levels are built on a grid); accepted for the common simulator signature.

err_hetero : bool, default False

Heteroskedastic unit innovations, σ_0 sqrt(1 + ‖x_i‖²).

rng=None

Randomness.

seed=None

Randomness.

Returns:

y, X (units’ design), W / W_sparse (units’ graph), levels (per upper level: X, W, W_sparse, parent — the index of each lower row’s group — and theta), frames (one DataFrame per level for formula use: the units with y, x1… and a key g1, g2… for every level above; each upper level with its key, z1… and the key of its parent), and params.

Return type:

dict