sigma_convergence

sigma_convergence(
    data,
    variable,
    *,
    first=None,
    last=None,
    vcov='hetero',
    title=None,
    ref=None,
)

Sigma-convergence: does the dispersion of a variable across units fall over time?

Measures the dispersion of the logarithm of variable in every year, on the units observed in all of them, and estimates its trend. A negative trend is convergence.

Parameters

Name Type Description Default
data A dataset id, or a panel with geo_id and year, e.g. from load required
variable str A numeric, strictly positive column in levels (its logarithm is taken here) required
first The first and last year to use (default: every year with data). The trend needs at least three years None
last The first and last year to use (default: every year with data). The trend needs at least three years None
vcov str Standard errors of the trend: "hetero" (robust, HC1) or "iid" 'hetero'
title str | None The figure title None

Returns

Name Type Description
result object A result with .std_slope (the trend of the log standard deviation per year: negative when dispersion falls), .std_se, .std_pvalue and .std_r2, the same for the Gini index (.gini_slope…) and the coefficient of variation (.cv_slope…), .n_units, .n_periods, .df (one row per year: n_units, mean, std, gini and cv of the logarithm), .fig (dispersion over time with the fitted trends), .gt and .summary (one row per measure), .notes (among them the units left out for lack of data) and .interpret().

Example

!pip install -q geo4bolivia
import geo4bolivia as geo

res = geo.sigma_convergence("pop", "pop")            # 20 years, 333 units
print(res.interpret())
res.fig

Across 333 units and 20 years, the cross-sectional dispersion of Population (standard deviation of its log) narrowed by about 0.196% per year (statistically significant at the 1% level). A negative log-dispersion trend is σ-convergence: the units are becoming more alike. All estimated measures (standard deviation, Gini, coefficient of variation) trend downward, so the narrowing is not an artifact of one dispersion metric.

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