tracegamma 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 William J. Dwyer
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,102 @@
1
+ Metadata-Version: 2.4
2
+ Name: tracegamma
3
+ Version: 0.1.0
4
+ Summary: The trace-gamma distribution: a three-cumulant calibrated reference for quadratic-form tests
5
+ Author: William J. Dwyer
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/wjdwyer/tracegamma
8
+ Project-URL: Repository, https://github.com/wjdwyer/tracegamma
9
+ Project-URL: Issues, https://github.com/wjdwyer/tracegamma/issues
10
+ Project-URL: Changelog, https://github.com/wjdwyer/tracegamma/blob/main/python/CHANGELOG.md
11
+ Project-URL: Deposit, https://doi.org/10.5281/zenodo.22060095
12
+ Keywords: quadratic form,generalized chi-square,Satterthwaite,Welch,Behrens-Fisher,heteroscedasticity,reference distribution
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Intended Audience :: Science/Research
15
+ Classifier: License :: OSI Approved :: MIT License
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Programming Language :: Python :: 3.14
22
+ Classifier: Topic :: Scientific/Engineering :: Mathematics
23
+ Requires-Python: >=3.10
24
+ Description-Content-Type: text/markdown
25
+ License-File: LICENSE
26
+ Requires-Dist: numpy>=1.21
27
+ Requires-Dist: scipy>=1.7
28
+ Provides-Extra: test
29
+ Requires-Dist: pytest>=7; extra == "test"
30
+ Dynamic: license-file
31
+
32
+ # tracegamma (Python)
33
+
34
+ The **trace-gamma** is the closed-form shifted, scaled chi-square matched to the
35
+ first three cumulants of a quadratic form in near-normal variables. Those
36
+ cumulants are exact traces of one matrix product (Lancaster's identity), and the
37
+ three-moment fit is Solomon and Stephens's. Welch's F is the **two-cumulant
38
+ member** of the family and Pearson's chi-square the **equal-eigenvalue member**,
39
+ so the family contains the classical references rather than competing with them.
40
+
41
+ The package also provides the exact generalized chi-square by Imhof inversion,
42
+ so the closed form can be checked against the truth rather than against
43
+ simulation; the kurtosis and tail-rate defects that govern the error; and an
44
+ estimable correction for non-normal inputs.
45
+
46
+ ## Two things worth knowing before you use it
47
+
48
+ **The two-cumulant branch is requested, not discovered.** The fit falls back to
49
+ Satterthwaite's two-moment form when the standardized skewness does not exceed
50
+ `1e-6`. No spectrum of positive eigenvalues reaches that in practice: the
51
+ skewness is `2*sqrt(2)*p3/p2^1.5`, minimised at equal eigenvalues where it is
52
+ `2*sqrt(2)/sqrt(m)`, so `1e-6` would need about 8e12 eigenvalues. You reach the
53
+ branch by supplying `k3 = 0` — which is exactly how the paper states the Welch
54
+ special case — or a negative `k3`, which is discarded with a warning. Inspect
55
+ the fitted object's `branch` to see which fit you have.
56
+
57
+ **The exact-inversion method matters for small spectra.** `method = "quad"`, the
58
+ single adaptive call used in the deposited research code, is accurate for ten or
59
+ more eigenvalues and **unusable below three**: measured against the exact oracle
60
+ `sum of m unit chi-squares = chi-square on m`, its worst relative error is about
61
+ 0.69 at m = 1 and 1.0e-2 at m = 2. `method = "panel"`, the default, integrates
62
+ between successive zeros and stays below 5e-9 throughout. It is slower. Both are
63
+ kept: `"quad"` reproduces the published cross-check numbers exactly.
64
+
65
+ ## Provenance and honest limits
66
+
67
+ Ported from the research code deposited with the paper (Zenodo concept DOI
68
+ `10.5281/zenodo.22060095`). The port changes no formula and no constant; the
69
+ Python test suite pins it to the deposited module value for value. Two
70
+ departures are deliberate and documented in the source: the fitted branch is
71
+ recorded and a negative third cumulant warns, and the exact-inversion default is
72
+ the repaired panel method rather than the single quad call.
73
+
74
+ MIT licensed.
75
+
76
+ ## Install
77
+
78
+ ```
79
+ pip install tracegamma
80
+ ```
81
+
82
+ ## Use
83
+
84
+ ```python
85
+ from tracegamma import TraceGamma, imhof_ppf, kurtosis_defect
86
+
87
+ lam = [4.0, 2.0, 1.0, 1.0] # eigenvalues of M^{1/2} D M^{1/2}
88
+ tg = TraceGamma.from_eigs(lam)
89
+ tg.cutoff(0.05) # 21.249374...
90
+ tg.branch # 'three-cumulant'
91
+
92
+ imhof_ppf(0.95, lam) # 20.919385... the exact quantile
93
+ kurtosis_defect(lam) # what drives the shoulder error
94
+ ```
95
+
96
+ Also `TraceGamma.from_quadform(M, D)` and `TraceGamma(k1, k2, k3)`.
97
+
98
+ ## Test
99
+
100
+ ```
101
+ pytest --doctest-modules src/tracegamma tests
102
+ ```
@@ -0,0 +1,71 @@
1
+ # tracegamma (Python)
2
+
3
+ The **trace-gamma** is the closed-form shifted, scaled chi-square matched to the
4
+ first three cumulants of a quadratic form in near-normal variables. Those
5
+ cumulants are exact traces of one matrix product (Lancaster's identity), and the
6
+ three-moment fit is Solomon and Stephens's. Welch's F is the **two-cumulant
7
+ member** of the family and Pearson's chi-square the **equal-eigenvalue member**,
8
+ so the family contains the classical references rather than competing with them.
9
+
10
+ The package also provides the exact generalized chi-square by Imhof inversion,
11
+ so the closed form can be checked against the truth rather than against
12
+ simulation; the kurtosis and tail-rate defects that govern the error; and an
13
+ estimable correction for non-normal inputs.
14
+
15
+ ## Two things worth knowing before you use it
16
+
17
+ **The two-cumulant branch is requested, not discovered.** The fit falls back to
18
+ Satterthwaite's two-moment form when the standardized skewness does not exceed
19
+ `1e-6`. No spectrum of positive eigenvalues reaches that in practice: the
20
+ skewness is `2*sqrt(2)*p3/p2^1.5`, minimised at equal eigenvalues where it is
21
+ `2*sqrt(2)/sqrt(m)`, so `1e-6` would need about 8e12 eigenvalues. You reach the
22
+ branch by supplying `k3 = 0` — which is exactly how the paper states the Welch
23
+ special case — or a negative `k3`, which is discarded with a warning. Inspect
24
+ the fitted object's `branch` to see which fit you have.
25
+
26
+ **The exact-inversion method matters for small spectra.** `method = "quad"`, the
27
+ single adaptive call used in the deposited research code, is accurate for ten or
28
+ more eigenvalues and **unusable below three**: measured against the exact oracle
29
+ `sum of m unit chi-squares = chi-square on m`, its worst relative error is about
30
+ 0.69 at m = 1 and 1.0e-2 at m = 2. `method = "panel"`, the default, integrates
31
+ between successive zeros and stays below 5e-9 throughout. It is slower. Both are
32
+ kept: `"quad"` reproduces the published cross-check numbers exactly.
33
+
34
+ ## Provenance and honest limits
35
+
36
+ Ported from the research code deposited with the paper (Zenodo concept DOI
37
+ `10.5281/zenodo.22060095`). The port changes no formula and no constant; the
38
+ Python test suite pins it to the deposited module value for value. Two
39
+ departures are deliberate and documented in the source: the fitted branch is
40
+ recorded and a negative third cumulant warns, and the exact-inversion default is
41
+ the repaired panel method rather than the single quad call.
42
+
43
+ MIT licensed.
44
+
45
+ ## Install
46
+
47
+ ```
48
+ pip install tracegamma
49
+ ```
50
+
51
+ ## Use
52
+
53
+ ```python
54
+ from tracegamma import TraceGamma, imhof_ppf, kurtosis_defect
55
+
56
+ lam = [4.0, 2.0, 1.0, 1.0] # eigenvalues of M^{1/2} D M^{1/2}
57
+ tg = TraceGamma.from_eigs(lam)
58
+ tg.cutoff(0.05) # 21.249374...
59
+ tg.branch # 'three-cumulant'
60
+
61
+ imhof_ppf(0.95, lam) # 20.919385... the exact quantile
62
+ kurtosis_defect(lam) # what drives the shoulder error
63
+ ```
64
+
65
+ Also `TraceGamma.from_quadform(M, D)` and `TraceGamma(k1, k2, k3)`.
66
+
67
+ ## Test
68
+
69
+ ```
70
+ pytest --doctest-modules src/tracegamma tests
71
+ ```
@@ -0,0 +1,49 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "tracegamma"
7
+ version = "0.1.0"
8
+ description = "The trace-gamma distribution: a three-cumulant calibrated reference for quadratic-form tests"
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = {text = "MIT"}
12
+ authors = [{name = "William J. Dwyer"}]
13
+ keywords = ["quadratic form", "generalized chi-square", "Satterthwaite",
14
+ "Welch", "Behrens-Fisher", "heteroscedasticity", "reference distribution"]
15
+ classifiers = [
16
+ "Development Status :: 4 - Beta",
17
+ "Intended Audience :: Science/Research",
18
+ "License :: OSI Approved :: MIT License",
19
+ "Programming Language :: Python :: 3",
20
+ # One classifier per version the CI matrix actually runs. If a version is
21
+ # added or removed here it must be added or removed in python.yml too: an
22
+ # untested classifier is a claim, not a fact.
23
+ "Programming Language :: Python :: 3.10",
24
+ "Programming Language :: Python :: 3.11",
25
+ "Programming Language :: Python :: 3.12",
26
+ "Programming Language :: Python :: 3.13",
27
+ "Programming Language :: Python :: 3.14",
28
+ "Topic :: Scientific/Engineering :: Mathematics",
29
+ ]
30
+ dependencies = ["numpy>=1.21", "scipy>=1.7"]
31
+
32
+ [project.optional-dependencies]
33
+ test = ["pytest>=7"]
34
+
35
+ [project.urls]
36
+ Homepage = "https://github.com/wjdwyer/tracegamma"
37
+ Repository = "https://github.com/wjdwyer/tracegamma"
38
+ Issues = "https://github.com/wjdwyer/tracegamma/issues"
39
+ Changelog = "https://github.com/wjdwyer/tracegamma/blob/main/python/CHANGELOG.md"
40
+ Deposit = "https://doi.org/10.5281/zenodo.22060095"
41
+
42
+ [tool.setuptools.packages.find]
43
+ where = ["src"]
44
+
45
+ [tool.setuptools.package-data]
46
+ tracegamma = ["data/*.json"]
47
+
48
+ [tool.pytest.ini_options]
49
+ testpaths = ["tests"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,80 @@
1
+ # (c) 2026 William J. Dwyer. MIT License.
2
+ r"""tracegamma -- the three-cumulant calibrated reference for quadratic-form tests.
3
+
4
+ The trace-gamma is the closed-form shifted, scaled chi-square matched to the
5
+ first three cumulants of a quadratic form in near-normal variables. Welch's F is
6
+ its two-cumulant member and Pearson's chi-square its equal-eigenvalue member, so
7
+ the family *contains* the classical references rather than competing with them.
8
+
9
+ Quick start
10
+ -----------
11
+ >>> from tracegamma import TraceGamma
12
+ >>> tg = TraceGamma.from_eigs([4.0, 2.0, 1.0, 1.0])
13
+ >>> round(tg.cutoff(0.05), 6)
14
+ 21.249374
15
+ >>> tg.branch
16
+ 'three-cumulant'
17
+
18
+ Checking the closed form against the exact law:
19
+
20
+ >>> from tracegamma import imhof_ppf
21
+ >>> lam = [4.0, 2.0, 1.0, 1.0]
22
+ >>> round(TraceGamma.from_eigs(lam).ppf(0.95) - imhof_ppf(0.95, lam), 4)
23
+ 0.33
24
+
25
+ Citation
26
+ --------
27
+ Dwyer, W. J. (2026). *The trace-gamma distribution: a three-cumulant calibrated
28
+ reference for quadratic-form tests, with Welch's F and Pearson's chi-square as
29
+ special cases.* Zenodo concept DOI 10.5281/zenodo.22060095.
30
+ """
31
+ from .core import (
32
+ SKEW_FLOOR,
33
+ VAR_FLOOR,
34
+ TraceGamma,
35
+ cumulants_from_eigs,
36
+ cumulants_from_traces,
37
+ params_from_power_sums,
38
+ traces_from_quadform,
39
+ )
40
+ from .exact import imhof_cdf, imhof_ppf, imhof_sf
41
+ from .defects import (
42
+ cf_modulus,
43
+ kurtosis_defect,
44
+ rho_ratio,
45
+ standardized_cumulant,
46
+ tail_rate_defect,
47
+ )
48
+ from .correction import (
49
+ estimate_moments,
50
+ kurtosis_widening,
51
+ marginal_cumulants,
52
+ tracegamma_from_marginal,
53
+ )
54
+ from .bb import bb_scale_mixture
55
+
56
+ __version__ = "0.1.0"
57
+
58
+ __all__ = [
59
+ "TraceGamma",
60
+ "cumulants_from_traces",
61
+ "traces_from_quadform",
62
+ "cumulants_from_eigs",
63
+ "params_from_power_sums",
64
+ "SKEW_FLOOR",
65
+ "VAR_FLOOR",
66
+ "imhof_sf",
67
+ "imhof_cdf",
68
+ "imhof_ppf",
69
+ "kurtosis_defect",
70
+ "tail_rate_defect",
71
+ "standardized_cumulant",
72
+ "rho_ratio",
73
+ "cf_modulus",
74
+ "marginal_cumulants",
75
+ "tracegamma_from_marginal",
76
+ "estimate_moments",
77
+ "kurtosis_widening",
78
+ "bb_scale_mixture",
79
+ "__version__",
80
+ ]
@@ -0,0 +1,52 @@
1
+ # (c) 2026 William J. Dwyer. MIT License.
2
+ r"""The Berger-Boos scale mixture: the guaranteed test's oracle law.
3
+
4
+ The guaranteed statistic ``T_BB`` dilates the trace-gamma cutoff by a
5
+ data-dependent log-variance scale. Equivalently, the deployed statistic is the
6
+ trace-gamma core *divided* by an independent scale, so its law is a scale
7
+ mixture of the core over the log-chi-square dispersion -- the object the paper
8
+ names the **Berger-Boos scale mixture**.
9
+
10
+ Scope warning
11
+ -------------
12
+ This module is here because the scope chosen for the package was "everything in
13
+ the project tree". The statistic itself belongs to a different paper in the
14
+ series (m01A / T_BB), not to the trace-gamma paper. Nothing in the trace-gamma
15
+ propositions depends on it. Treat it as a convenience, and read that paper
16
+ before relying on the constant ``ks``.
17
+ """
18
+ from __future__ import annotations
19
+
20
+ import numpy as np
21
+
22
+ __all__ = ["bb_scale_mixture"]
23
+
24
+
25
+ def bb_scale_mixture(core_cutoff, ks, rbar, k):
26
+ r"""Inflate a trace-gamma cutoff to the guaranteed ``T_BB`` cutoff.
27
+
28
+ ``T_BB`` rejects when ``Q_obs > exp(ks sqrt(rbar/k)) * core_cutoff``.
29
+
30
+ Parameters
31
+ ----------
32
+ core_cutoff : float or array_like
33
+ The trace-gamma cutoff, e.g. from
34
+ :meth:`tracegamma.core.TraceGamma.cutoff`.
35
+ ks : float
36
+ The Berger-Boos constant for the design.
37
+ rbar : float
38
+ The design radius (log-variance dispersion).
39
+ k : int
40
+ Number of groups.
41
+
42
+ Returns
43
+ -------
44
+ float or ndarray
45
+ The inflated cutoff.
46
+
47
+ Examples
48
+ --------
49
+ >>> round(float(bb_scale_mixture(10.0, 0.0, 1.0, 4)), 12)
50
+ 10.0
51
+ """
52
+ return np.exp(ks * np.sqrt(rbar / k)) * core_cutoff