learn_theil_decomposition

learn_theil_decomposition(
    n_groups=3,
    n_per_group=40,
    gaps=(0.0, 0.25, 0.5, 0.75, 1.0),
    within_sd=0.5,
    jitter=0.0,
    seed=0,
)

Plant a between/within inequality split, then watch Theil decompose it.

Builds group log-income distributions on a deterministic quantile grid — group g at gap level tau is centered at g * tau with within-group spread within_sd — and sweeps gaps as successive “periods” of a panel, so one call to :func:geometrics.analyze_theil_decomposition traces how the between-group share rises with the planted gap. The truth is computed with an independent numpy implementation of the Theil-T decomposition.

Parameters

Name	Type	Description	Default
n_groups	int	Number of groups.	3
n_per_group	int	Units per group.	40
gaps	tuple[float, …]	The planted between-group log gaps, swept as periods (at least two values).	(0.0, 0.25, 0.5, 0.75, 1.0)
within_sd	float	Within-group standard deviation of log income (drives the within share).	0.5
jitter	float	Standard deviation of optional extra log noise (0 keeps the grid exact).	0.0
seed	int	Random seed (only used when jitter > 0).	0

Returns

Name	Type	Description
	SandboxResult	df (per gap: Theil, between, within, estimated and true between share), fig, summary, topic and the simulated panel in data.

Examples

import geometrics as gm

res = gm.learn_theil_decomposition(within_sd=0.3)
res.df[["gap", "between_share_est", "between_share_true"]]