learn_spatial_markov

learn_spatial_markov(
    side=10,
    n_periods=30,
    base_move=0.1,
    contextual=0.25,
    seed=0,
)

Plant neighbor-dependent mobility, then watch the spatial Markov test flag it.

Simulates three-state dynamics on a lattice where each unit moves toward its neighbors’ average state with probability base_move + contextual but away with only base_move — so transition probabilities genuinely depend on the spatial context (set contextual=0 to restore homogeneity). Rey’s spatial Markov (:func:geometrics.analyze_spatial_markov) conditions the transition matrix on the neighbors’ class; its LR test should reject homogeneity and the upward-move probability should rise with richer neighbors.

Requires the dynamics extra (pip install "geometrics[dynamics]").

Parameters

Name	Type	Description	Default
side	int	Lattice side length (n = side²).	10
n_periods	int	Number of simulated periods.	30
base_move	float	Baseline per-period probability of moving a state in either direction.	0.1
contextual	float	Extra probability of moving toward the neighbors’ average state — the planted spatial effect the test should detect.	0.25
seed	int	Random seed.	0

Returns

Name	Type	Description
	SandboxResult	df (upward/stay/downward probabilities of the middle state by neighbor class), fig, summary, topic and the simulated panel in data.

Examples

import geometrics as gm

res = gm.learn_spatial_markov(contextual=0.25)
print(res.summary["lr_p"], res.summary["contextual_gap_est"])