σ-convergence: track and test the cross-sectional dispersion of a panel variable.
For each period the function measures how spread out var is across units — the standard deviation, the Gini index and the coefficient of variation — and then asks whether that dispersion shrinks over time by regressing the log dispersion on time. A negative trend slope is σ-convergence: the cross-sectional distribution is narrowing (units are becoming more alike). This is the distributional complement to β-convergence (which compares growth to the initial level); see :func:analyze_beta_convergence.
The variable is used as supplied — no log or other transform is taken — so pass it on whatever scale the analysis calls for. The panel must be balanced (every unit present in every period) so the dispersion is comparable across periods.
| Name | Type | Description | Default |
|---|---|---|---|
| df | pd.DataFrame | Panel data frame. | required |
| var | str | Numeric variable whose cross-sectional dispersion is tracked (e.g. "lifeExp"). Used as supplied. The Gini index additionally requires non-negative values. |
required |
| entity | str | None | Panel identifiers. Default to those declared via :func:expdpy.set_panel. |
None |
| time | str | None | Panel identifiers. Default to those declared via :func:expdpy.set_panel. |
None |
| start | float | None | Optional first and last period to include. Default to the full range; the retained window must still be balanced. | None |
| end | float | None | Optional first and last period to include. Default to the full range; the retained window must still be balanced. | None |
| min_periods | int | Minimum number of periods required to estimate a dispersion trend (at least 3). | 3 |
| vcov | Literal['hetero', 'iid'] | Standard-error type for the trend coefficients: "hetero" (HC1, the default) or "iid". Does not change the point estimate. |
'hetero' |
| title | str | None | Title for the dual-axis figure. | None |
| Name | Type | Description |
|---|---|---|
| SigmaConvergenceResult | The per-period dispersion table df (time, n_units, mean, std, gini, cv); the dual-axis fig (std on the left axis, Gini on the right); the trend table gt / summary (one row per measure: slope, SE, p-value, R²); the fitted trend models; the panel dimensions n_periods / n_units; and the headline trend scalars (std_slope and its std_se / std_pvalue / std_r2, plus the gini_* and cv_* counterparts). notes records any degraded measure (e.g. a Gini set to NaN because the variable has negative values). |
For a measure of dispersion D_t computed cross-sectionally at each time t, the trend is the OLS slope b in
.. math:: D_t = a + b , t + _t,
so b is the average proportional change in dispersion per period and b < 0 is σ-convergence. The standard deviation uses ddof = 1; the Gini index is the relative mean absolute difference over twice the mean; the coefficient of variation is the standard deviation over the mean. If every unit’s value contracts geometrically toward a common mean at rate rho per period, each dispersion measure scales as rho**t and the trend recovers b = ln(rho) exactly. See Barro & Sala-i-Martin, Economic Growth, ch. 11.
Basic — σ-convergence of log GDP per capita across Bolivian provinces. The panel must be balanced; set_labels(..., set_panel=True) declares (entity, time) so the call omits entity= / time= and the figure axes are labelled:
import expdpy as ex
from expdpy.data import load_bolivia112_gdppc, load_bolivia112_gdppc_data_def
df = ex.set_labels(
load_bolivia112_gdppc(), load_bolivia112_gdppc_data_def(), set_panel=True
)
res = ex.analyze_sigma_convergence(df, "log_gdppc")
res.fig # std (left axis) and Gini (right axis) over time
res.gt # the trend table
res.std_slope # < 0 indicates σ-convergence-0.00968270020949833