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
| 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
|
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.