learn_convergence_clubs

source

learn_convergence_clubs(
    n_per_club=15,
    levels=(10.0, 9.3, 8.6),
    n_years=35,
    rho=0.9,
    spread=0.4,
    noise=0.002,
    seed=0,
)

Show Phillips-Sul club clustering recovering a planted club structure.

Builds a panel with len(levels) known convergence clubs: every unit in club k starts at its long-run level levels[k] plus an idiosyncratic deviation that decays geometrically (deviation * rho**t), so units within a club converge to a common path while the distinct club levels keep the panel from converging globally. Running :func:expdpy.analyze_convergence_clubs on it should reject whole-panel convergence and recover the planted clubs. Demonstrates that the clustering is data-driven, not imposed.

Parameters

Name	Type	Description	Default
n_per_club	int	Units per planted club.	`15`
levels	tuple[float, …]	The distinct long-run (log) levels, one per club; well-separated levels give clean clubs.	`(10.0, 9.3, 8.6)`
n_years	int	Number of annual periods (the horizon over which deviations decay).	`35`
rho	float	Per-period decay of the within-club deviations in `(0, 1)` (smaller converges faster).	`0.9`
spread	float	Half-width of the initial within-club deviation (uniform).	`0.4`
noise	float	Idiosyncratic shock standard deviation (kept tiny so the clubs stay sharp).	`0.002`
seed	int	Random seed.	`0`

Returns

Name	Type	Description
	SandboxResult	`df` (each unit’s planted vs detected club), `fig` (the recovered within-club average paths), `summary` and `topic`.

Examples

This sandbox simulates its own panel with a planted club structure, so the call needs no DataFrame:

import expdpy as ex

res = ex.learn_convergence_clubs()
res.fig