spatial_transitions

spatial_transitions(
    data,
    variable,
    *,
    w=None,
    k=5,
    m=None,
    per_year=False,
    relative=True,
    title=None,
    gdf=None,
    ref=None,
)

Spatial Markov transitions: does a unit’s mobility depend on where its neighbours stand?

Rey’s spatial Markov chain splits the transition matrix of transitions by the class of each unit’s neighbours (their weighted mean), and tests whether the matrices differ. Needs the [dynamics] extra.

Parameters

Name Type Description Default
data A dataset id, or a panel with geo_id and year, e.g. from load required
variable str The numeric column to follow, observed in at least two years; the units without a value in every year are left out required
w Spatial weights from weights (default: queen contiguity among the units with data) None
k int Number of quantile classes of the variable 5
m int | None Number of quantile classes of the neighbours’ mean (default: k) None
per_year bool Classify each year on its own; by default all years are classified together, so classes are fixed levels False
relative bool Divide the values by each year’s mean first (default), so that classes are levels relative to the average unit; needs positive means True
title str | None The figure title None
gdf Boundaries to use instead of the project’s (a GeoDataFrame with geo_id) None

Returns

Name Type Description
result object A result with .p_global (the transition probabilities of all units), .p_conditional (one matrix per class of the neighbours, from the lowest to the highest), .steady_states (the long-run distribution in each neighbourhood), .fig (the conditional matrices side by side), .gt (the tests of equal dynamics across neighbourhoods), .lr_stat, .lr_p, .q_stat, .q_p, .dof, .df (one row per unit and year with its state and neighbor_state) and .interpret().

Example

!pip install -q "geo4bolivia[dynamics]"
import geo4bolivia as geo

res = geo.spatial_transitions("ntl", "ln_NTLpc", k=5)
print(res.interpret())
res.fig

The spatial Markov chain splits Log night-time lights per capita’s 5-state transition matrix by the neighbors’ position (spatial lag under queen contiguity (1 island(s) attached to nearest neighbor), row-standardized, n=316), giving one matrix per neighborhood class (5 classes); values were expressed relative to each year’s mean first. The unconditional matrix keeps units in place with average probability 0.829. Conditioning on context, units surrounded by low-value neighbors stay in place with average probability 0.81, while units surrounded by high-value neighbors do so with 0.758 — movement is more common where the neighbors have high values. The homogeneity tests (LR = 112, p = 1.26e-05; Q = 160, p = 6.4e-12; 56 degrees of freedom) are statistically significant at the 1% level: transition dynamics differ across neighborhood contexts — a unit’s mobility is associated with the state of its neighbors.

These are associations, not causal effects. A causal reading needs a research design.