learn_convergence_clubs

learn_convergence_clubs(
    n_per_club=15,
    levels=(10.0, 9.0),
    n_periods=35,
    rho=0.9,
    spread=0.4,
    noise=0.002,
    seed=0,
)

Plant convergence clubs, then watch the Phillips-Sul algorithm find them.

Each club k converges to its own level: unit j follows x_jt = levels[k] + dev_j rho^t + noise with dev_j ~ U(-spread, spread), so within a club the transition paths contract while the between-club gaps persist — global convergence should be rejected and the clustering should recover the planted groups. The summary reports the detected club count and the assignment accuracy.

Parameters

Name	Type	Description	Default
n_per_club	int	Units per planted club.	15
levels	tuple[float, …]	The clubs’ long-run (log) levels — one entry per club, at least two.	(10.0, 9.0)
n_periods	int	Number of periods (the log(t) test needs a long panel).	35
rho	float	Per-period contraction of within-club deviations, 0 < ρ < 1.	0.9
spread	float	Half-width of the uniform initial deviations around each club level.	0.4
noise	float	Standard deviation of the per-period noise.	0.002
seed	int	Random seed.	0

Returns

Name	Type	Description
	SandboxResult	df (unit, planted club, detected club), fig (the within-club transition paths from the real estimator), summary, topic and the simulated panel in data.

Examples

import geometrics as gm

res = gm.learn_convergence_clubs(levels=(10.0, 9.2, 8.5))
print(res.summary["detected_clubs"], res.summary["accuracy"])