Kruskal Wallis Test

Kruskal-Wallis Test (cross-cutting/numerics/kruskal-wallis-test)

Use when the task is a distribution-free comparison of three or more independent groups, the rank-based counterpart of the parametric one-way location comparison: merge all observations, rank them with average ranks for ties, form the H statistic, correct it for ties, and convert it to a p-value through the chi-square survival function. This leaf implements the standard Kruskal-Wallis method in pure Python, stdlib only, with its own regularized lower incomplete gamma pair for the chi-square survival (no sibling imports). It pairs with cross-cutting/numerics/rank-based-hypothesis-testing, which owns paired and two independent-group comparisons, and with cross-cutting/numerics/hypothesis-testing, which owns the parametric location and scale tests this leaf does not need.

Domain quick reference

• Ranks: merge the N observations of all groups and rank the merged sample; equal observations share the average of the rank positions they occupy (average ranks for ties).
• H statistic: H = (12 / (N (N + 1))) sum_i(R_i^2 / n_i) - 3 (N + 1), where R_i is the sum of the ranks of group i and n_i its size. H = 0 when all groups are identical.
• Ties correction: with tie runs of size t the denominator is C = 1 - sum((t^3 - t) / (N^3 - N)); C = 1.0 when there are no ties, and the corrected statistic is H' = H / C, so ties move H upward.
• Degrees of freedom: df = k - 1 for k groups.
• p-value: p = P(chi2_(k-1) > H'), the survival function evaluated as the regularized upper incomplete gamma Q(df / 2, H' / 2), computed with the standard series and continued-fraction pair.
• Verdict: reject when p <= alpha, fail to reject otherwise; alpha defaults to 0.05 and must lie in (0, 1).
• All quantities are pure floats; the module is deterministic and offline.
• NACA-TR-824 frames the statistical data-analysis context; the relations above are standard engineering methodology, summary-only.

Workflow

1. Collect the groups: assemble the k >= 3 independent samples of finite measurements (group collection); every group needs at least two observations, and the significance level alpha must lie in (0, 1).
2. Rank the merged sample: concatenate all groups and assign average ranks for ties with rank_data (rank assignment step).
3. Compute the H statistic with kruskal_wallis_h, which returns the uncorrected H of the formula above (H statistic computation step).
4. Apply the ties correction: read the denominator C from ties_correction and form h_corrected = H / C (ties correction step; C = 1.0 leaves H unchanged).
5. Convert to significance: kruskal_wallis_p_value(h_corrected, group_count) evaluates the chi-square survival with df = group_count - 1 through the self-contained incomplete gamma pair (significance conversion step).
6. Read the verdict report: kruskal_wallis_test(groups, alpha) returns the dict with keys h, h_corrected, df, p_value, verdict and group_rank_sums, where verdict is reject when p_value <= alpha (verdict report step).
7. Confirm the deterministic checks with the contract test run: python3 scripts/test_kruskal_wallis_test.py (contract test step).

Worked example

Three groups of three, x = [2.1, 2.2, 2.3], y = [2.9, 3.0, 3.1], z = [3.7, 3.8, 3.9], alpha 0.05 (module outputs shown):

• Merged ranks: x takes ranks 1 to 3 (sum 6), y ranks 4 to 6 (sum 15), z ranks 7 to 9 (sum 24); N = 9, no ties.
• H = (12 / 90) (36/3 + 225/3 + 576/3) - 30 = 7.200000000000003, within 1e-9 of 7.2; ties_correction returns C = 1.0, so h_corrected = 7.200000000000003.
• df = 2; p_value = 0.027323722447292528 from the chi-square survival (matches exp(-3.6), the exact df-2 survival at H = 7.2).
• Verdict: reject at 0.05; group_rank_sums [6.0, 15.0, 24.0].

A tied comparison, groups [1, 2, 3], [1.5, 2.5, 3.5], [2, 3, 4]: values 2 and 3 both recur, C = 0.9833333333333333 below 1, H = 1.4222222222222243, h_corrected = 1.4463276836158214 (H divided by C), p_value = 0.4852146824247665, verdict fail to reject at 0.05.

Pitfalls

• Correcting ties the wrong direction: the model divides H by C = 1 - sum((t^3 - t) / (N^3 - N)) with C below 1 when ties exist, so the corrected statistic rises above the raw H; multiplying by C instead would understate the separation.
• Forgetting average ranks: tied observations must share the mean of their rank block, not arbitrary distinct integers, or H and the p-value drift.
• Using the leaf on designs it does not own: paired measurements and two independent-group comparisons belong to cross-cutting/numerics/rank-based-hypothesis-testing, and parametric location and scale tests belong to cross-cutting/numerics/hypothesis-testing.
• Reading a group rank sum as a mean: group_rank_sums lists the raw sums of average ranks per group in input order, and the sums always total N (N + 1) / 2 whether ties are present or not.
• Passing undersized input: fewer than 3 groups, a group with a single observation, non-finite values, a negative corrected statistic, or alpha outside (0, 1) all raise ValueError.
• Treating the p-value as exact for small samples: the p-value comes from the chi-square survival approximation with df = k - 1, exact for the worked example but asymptotic for very small group sizes.

Verification

• Confirm kruskal_wallis_h on the worked example returns 7.200000000000003, within 1e-9 of 7.2, and kruskal_wallis_test returns df 2, p_value 0.027323722447292528 (within 1e-3 of 0.0273), verdict reject at 0.05 and group_rank_sums [6.0, 15.0, 24.0].
• Confirm all-identical groups return H = 0.0, p_value 1.0 and verdict fail to reject, with the zero correction denominator handled.
• Confirm the tied example gives C = 0.9833333333333333 below 1 and h_corrected = h / C above the raw H.
• Confirm rank invariance: multiplying every observation by 10 leaves H unchanged because only the rank assignment feeds the statistic.
• Confirm every undersized, non-finite and out-of-range input raises ValueError, and that repeated calls return identical reports.
• Run the contract test offline: python3 scripts/test_kruskal_wallis_test.py (35 tests, deterministic).

Related leaves

• cross-cutting/numerics/rank-based-hypothesis-testing: paired and two independent-group location tests, the k = 2 family this leaf does not cover.
• cross-cutting/numerics/hypothesis-testing: the parametric one-way location comparison and scale tests for normal data.
• cross-cutting/numerics/runs-test: randomness and sequence structure checks on a single sample.
• cross-cutting/numerics/grubbs-outlier-test: single-outlier detection on grouped or pooled measurements.
• cross-cutting/numerics/probability-distributions: the distributions behind the survival-function context.

Behavior contract (gate 3)

Run the deterministic contract test (stdlib unittest, offline):

python3 scripts/test_kruskal_wallis_test.py

The test covers the worked-example contract (H within 1e-9 of 7.2, df 2, p_value 0.027323722447292528 within 1e-3 of 0.0273, verdict reject at 0.05, per-group rank sums 6, 15, 24), the chi-square survival anchor exp(-3.6) at df 2, average-rank assignment for ties, the ties correction denominator and the h_corrected = H / C identity, all-identical groups with H = 0 and p = 1, rank invariance under monotone transforms, the rank-sum total identity N (N + 1) / 2, report dict keys and determinism, and ValueError rejection of two groups, a single-observation group, non-finite values, negative corrected statistics, and alpha outside (0, 1).

Compliance

• Standards referenced, not reproduced: NACA-TR-824 is a public-domain NACA technical report; the Kruskal-Wallis relations above are standard engineering methodology, summary-only per standards-map.yaml.
• compliance: STANDARDS-REF, gated: false.