inequality

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

Name Description
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

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

Name Type Description
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

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