theil_decomposition

theil_decomposition(
    data,
    variable,
    by=None,
    *,
    permutations=0,
    seed=12345,
    title=None,
    ref=None,
)

Theil’s index split in two: inequality between groups of units and inequality within them.

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 measure, in levels and strictly positive required
by str | None The groups: a column of the table, or a coarser scale the units nest in (see ancestors). Default: the coarsest such scale with two or more units. A unit must stay in the same group in every year None
permutations int Random reassignments of units to groups behind the pseudo p-value of the between component (0: no test) 0
seed int Makes the permutations reproducible 12345
title str | None The figure title None

Returns

Name Type Description
TheilResult A result with .df (one row per year: theil, between, within, which add up to it, between_share, and p_between with permutations), .fig (the two components stacked, with the between share), .gt, .by, .n_groups, .notes and .interpret().

Example

!pip install -q geo4bolivia
import geo4bolivia as geo

res = geo.theil_decomposition("sdg", "index_sdg", by="department")
print(res.interpret())
res.fig

The Theil index of Sustainable Development Index, IDS (0-100) splits additively into inequality between the 9 department groups and inequality within them (between + within = total, exactly).

In the latest year (2024), the total Theil index is 0.00381: about 15% of it lies between department groups and 85% within them — most inequality plays out among units inside the same department.

Over the window, the between-group share fell from 20% to 15% — group means are pulling closer together relative to the differences inside groups.

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