learn_sigma_convergence

source

learn_sigma_convergence(n_units=60, n_years=21, rho=0.93, noise=0.0, seed=0)

Show σ-convergence on a panel whose dispersion narrows at a known rate.

Simulates a panel in which every unit’s value contracts geometrically toward a common mean mu: x_{i,t} = mu + (x_{i,0} - mu) * rho**t. Because the deviations from mu shrink by a constant factor rho each period while the mean stays fixed, every dispersion measure — the standard deviation, the Gini index and the coefficient of variation — scales as rho**t. The trend of its log on time therefore equals ln(rho) exactly, the true speed of σ-convergence. Running :func:expdpy.analyze_sigma_convergence on the panel should recover that slope for all three measures.

Parameters

Name	Type	Description	Default
n_units	int	Panel dimensions (units and annual periods). The horizon is `T = n_years - 1`.	`60`
n_years	int	Panel dimensions (units and annual periods). The horizon is `T = n_years - 1`.	`60`
rho	float	Per-period contraction factor in `(0, 1)`; the true log-dispersion trend is `ln(rho)` (closer to 1 means slower convergence).	`0.93`
noise	float	Standard deviation of an optional additive shock (`0` gives exact recovery).	`0.0`
seed	int	Random seed.	`0`

Returns

Name	Type	Description
	SandboxResult	`df` (recovered trend per measure vs the true `ln(rho)`), `fig`, `summary` and `topic`.

Examples

This sandbox simulates its own contracting panel, so the call needs no DataFrame:

import expdpy as ex

res = ex.learn_sigma_convergence()
res.fig