transitions

transitions(
    data,
    variable,
    *,
    k=5,
    scheme='quantiles',
    bins=None,
    per_year=True,
    relative=False,
    title=None,
    ref=None,
)

Markov transitions between classes of a variable’s distribution: how mobile are the units?

Every unit is assigned to one of k classes in each year, and all the moves from one year to the next are counted in a transition matrix: the probability of being in each class next year, given this year’s class. 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
k int Number of classes 5
scheme str How classes are formed: "quantiles" (equal numbers of units), "equal_interval" or "fisher_jenks" 'quantiles'
bins Upper bounds of fixed classes, the same in every year (replaces k, scheme and per_year) None
per_year bool Classify each year on its own, so a class is a position within that year’s distribution (default); False classifies all years together, so classes are fixed levels True
relative bool Divide the values by each year’s mean first False
title str | None The figure title None

Returns

Name Type Description
result object A result with .p (the transition probabilities, rows = this year’s class) and .counts, .fig (the matrix as a heatmap), .gt (mobility indices, long-run shares and expected stays), .df (one row per unit and year with its state), .states, .steady_state (the long-run distribution), .sojourn (expected years in each class), the mobility indices .shorrocks, .prais and .bartholomew, .n_transitions and .interpret().

Example

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

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

Pooling 2,528 year-to-year moves, Log night-time lights per capita was discretized into 5 quantile states and its movement summarized by a transition-probability matrix: each row gives the chance of ending the next year in each state, conditional on the current one. On average a unit stays in its current state with probability 0.83 — the diagonal is dominant, so positions in the distribution are highly persistent. The stickiest state is Q5 (stay probability 0.909); the most mobile is Q2 (0.758). The Shorrocks mobility index is 0.212 on a 0 (complete immobility: the identity matrix) to 1.25 (all mass off the diagonal) scale; the Prais determinant index is 0.639 and the Bartholomew index 0.212. If these transition probabilities kept operating, the cross-section would settle into the ergodic (steady-state) mix with the largest long-run share in Q1 (0.203, versus 0.2 under an even split). Expected sojourn times say a unit entering Q5 remains there for about 11 consecutive years before moving.

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