inequality
Inequality between units: Gini, Theil and the coefficient of variation in each year, the Lorenz curve, and Theil’s index split between and within groups of units.
Functions
| inequality |
Inequality between units in each year: is it narrowing or widening? |
| theil_decomposition |
Theil’s index split in two: inequality between groups of units and inequality within them. |
inequality
inequality.inequality(
data,
variable,
*,
measures=('gini', 'theil'),
first=None,
last=None,
spatial=False,
w=None,
permutations=99,
lorenz=True,
title=None,
gdf=None,
ref=None,
)
Inequality between units in each year: is it narrowing or widening?
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 (not logs) |
required |
| measures |
|
"gini", "theil" (needs strictly positive values) and/or "cv" (the coefficient of variation: standard deviation over the mean) |
('gini', 'theil') |
| first |
|
The first and the last year to use (default: every year with data); the years between them are used too |
None |
| last |
|
The first and the last year to use (default: every year with data); the years between them are used too |
None |
| spatial |
bool |
Add the spatial Gini: the part of the Gini owed to pairs of neighbouring units, with a permutation test. It needs boundaries and weights, and uses the units with data in every year. Giving w implies it |
False |
| w |
|
Spatial weights from weights (default: queen contiguity among the units with data) |
None |
| permutations |
int |
Random permutations behind the spatial Gini’s pseudo p-value (0: no test) |
99 |
| lorenz |
bool |
Also draw the Lorenz curve |
True |
| title |
str | None |
The title of the main figure |
None |
| gdf |
|
Boundaries to use instead of the project’s (a GeoDataFrame with geo_id) |
None |
Returns
|
InequalityResult |
A result with .df (one row per year: n_units and one column per measure, plus gini_spatial and gini_spatial_p when spatial), .fig (the measures over time), .summary (one row per measure: its value in the first and last year, their change, and the slope, se and pvalue of its log-trend, which needs three or more years), .gt (the trends; with two years, the measures in both years), .lorenz (one row per unit and year, from the lowest value to the highest, with the cumulative share of units cum_units and of the variable cum_share), .fig_lorenz (one curve per year, the first and the last when there are more than four, with the line of equality), .lorenz_share(year, share), .n_years, .n_units, .w_spec, .notes and .interpret(). |
theil_decomposition
inequality.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.inequality("sdg", "index_sdg")
print(res.interpret())
res.fig_lorenz
Cross-sectional inequality in Sustainable Development Index, IDS (0-100) is tracked across 343 units over 2 years (2012 to 2024).
The Gini index fell from 0.065 to 0.0493 between the first and last year.
The Theil index fell from 0.00663 to 0.00381 between the first and last year.
With two years (2012 and 2024) the measures can be compared, but their trend cannot be tested: that needs three or more years.
On the Lorenz curve of 2024, the half of the units with the lowest values holds 46% of the total (45% in 2012) and the tenth with the highest values holds 12% (12%); with no inequality they would hold 50% and 10%.
These are associations, not causal effects. A causal reading needs a research design.