convergence_clubs(
data,
variable,
*,
first=None,
last=None,
log=False,
hp_filter=True,
hp_lambda=400.0,
trim=0.3,
tcrit=-1.65,
cr=0.0,
increment=0.05,
max_cr=3.0,
fraction=0.0,
adjust=False,
merge='ps',
map=True,
tiles='carto-positron',
title=None,
gdf=None,
ref=None,
)
Convergence clubs (Phillips and Sul): do all units converge, or do groups of them?
Tests whether the units’ paths converge (the log t test) and, when they do not, sorts the units into clubs that converge among themselves, on the units observed in every year.
Parameters
| data |
|
A dataset id, or a panel with geo_id and year, e.g. from load |
required |
| variable |
str |
The numeric column to analyse, used as given: pass a logarithm, or set log |
required |
| first |
|
The first and last year to use (default: every year with data). The years in between must all be there: at least 6 of them at the default trim |
None |
| last |
|
The first and last year to use (default: every year with data). The years in between must all be there: at least 6 of them at the default trim |
None |
| log |
bool |
Take the logarithm of variable first (it must then be strictly positive) |
False |
| hp_filter |
bool |
Analyse each unit’s Hodrick-Prescott trend instead of its raw path |
True |
| hp_lambda |
float |
The filter’s smoothing (400 for yearly data) |
400.0 |
| trim |
float |
The share of the first years that the log t regression leaves out |
0.3 |
| tcrit |
float |
The t-statistic above which convergence is not rejected (-1.65: the 5% level) |
-1.65 |
| cr |
float |
The threshold for adding a unit to a club’s core group, the step by which it is raised while the club fails the test, and its ceiling |
0.0 |
| increment |
float |
The threshold for adding a unit to a club’s core group, the step by which it is raised while the club fails the test, and its ceiling |
0.0 |
| max_cr |
float |
The threshold for adding a unit to a club’s core group, the step by which it is raised while the club fails the test, and its ceiling |
0.0 |
| fraction |
float |
Sort the units by their mean over the last 1 - fraction of the years instead of the last year (0) |
0.0 |
| adjust |
bool |
Add the units to a club one at a time (Schnurbus et al.) instead of raising cr |
False |
| merge |
str |
Join neighbouring clubs that converge together: "ps" (until none do), "single" (one pass) or "none" |
'ps' |
| map |
bool |
Draw the map of the clubs (False: no boundaries are loaded) |
True |
| tiles |
str | None |
The basemap style (None: no basemap) |
'carto-positron' |
| title |
str | None |
The figure title |
None |
| gdf |
|
Boundaries to use instead of the project’s (a GeoDataFrame with geo_id) |
None |
Returns
|
result object |
A result with .n_clubs, .n_divergent (units in no club), .converged (all units form one club), .global_tstat and .global_beta (the log t test on all units), .n_units, .n_periods, .membership (one row per unit with its club; 0 = in no club), .summary and .gt (one row per club with its test), .df (one row per unit and year: value, the relative path and club), .fig (the clubs’ average paths), .fig_paths (every unit’s path), .fig_clubs (one panel per club), .fig_map (the map of the clubs; None without boundaries), .notes and .interpret(). |
Example
!pip install -q geo4bolivia
import geo4bolivia as geo
res = geo.convergence_clubs("ntl", "ln_NTLpc") # 2012-2020, 316 units
print(res.interpret())
res.fig_map
Global convergence of Log night-time lights per capita is rejected for the 316 units (log(t) t = -32.2 ≤ -1.65): the panel is not heading toward one common path. The Phillips-Sul clustering instead finds 4 convergence clubs — groups whose members converge toward a shared, club-specific path while the clubs themselves stay apart. Club sizes — Club 1: 151, Club 2: 130, Club 3: 30, Club 4: 3. 2 units fit no club (the divergent group) and follow paths of their own. Club membership is a description of co-movement in the relative transition paths, not an explanation of why the groups differ.
These are associations, not causal effects. A causal reading needs a research design.