tracegamma 0.1.0__py3-none-any.whl
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.
- tracegamma/__init__.py +80 -0
- tracegamma/bb.py +52 -0
- tracegamma/core.py +328 -0
- tracegamma/correction.py +91 -0
- tracegamma/data/parity.json +594 -0
- tracegamma/defects.py +114 -0
- tracegamma/exact.py +179 -0
- tracegamma-0.1.0.dist-info/METADATA +102 -0
- tracegamma-0.1.0.dist-info/RECORD +12 -0
- tracegamma-0.1.0.dist-info/WHEEL +5 -0
- tracegamma-0.1.0.dist-info/licenses/LICENSE +21 -0
- tracegamma-0.1.0.dist-info/top_level.txt +1 -0
tracegamma/__init__.py
ADDED
|
@@ -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
|
+
]
|
tracegamma/bb.py
ADDED
|
@@ -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
|
tracegamma/core.py
ADDED
|
@@ -0,0 +1,328 @@
|
|
|
1
|
+
# (c) 2026 William J. Dwyer. MIT License.
|
|
2
|
+
r"""The trace-gamma reference distribution and its three constructors.
|
|
3
|
+
|
|
4
|
+
A test statistic that is a quadratic form ``Q = a' M a`` in a near-normal vector
|
|
5
|
+
``a ~ N(mu, D)`` has an exact null law that is a generalized chi-square -- a
|
|
6
|
+
weighted sum of chi-squares, one per eigenvalue of ``M^{1/2} D M^{1/2}``. That
|
|
7
|
+
law has no closed form. The trace-gamma is the closed-form three-cumulant match
|
|
8
|
+
|
|
9
|
+
.. math:: Q \;\approx\; b + a\,\chi^2_\nu
|
|
10
|
+
|
|
11
|
+
a shifted, scaled chi-square (equivalently a shifted gamma, equivalently Pearson
|
|
12
|
+
Type III), whose three parameters are fixed by the first three cumulants of
|
|
13
|
+
``Q``. Those cumulants are *exact traces* (Lancaster's trace-cumulant identity):
|
|
14
|
+
|
|
15
|
+
.. math:: \kappa_r = 2^{r-1}(r-1)!\,\operatorname{tr}((MD)^r)
|
|
16
|
+
|
|
17
|
+
so ``kappa_1 = t_1``, ``kappa_2 = 2 t_2``, ``kappa_3 = 8 t_3`` with
|
|
18
|
+
``t_r = tr((MD)^r)``.
|
|
19
|
+
|
|
20
|
+
Two classical references are *members* of this family rather than competitors:
|
|
21
|
+
|
|
22
|
+
* ``TraceGamma(k1, k2, 0)`` is Satterthwaite's two-moment scaled chi-square,
|
|
23
|
+
which applied to the between-group quadratic is Welch's (1951) reference;
|
|
24
|
+
* equal nonzero eigenvalues of ``MD`` give exactly ``chi^2`` on their number,
|
|
25
|
+
which is Pearson's reference.
|
|
26
|
+
|
|
27
|
+
Provenance
|
|
28
|
+
----------
|
|
29
|
+
This module is a behaviour-preserving port of ``mseries_qgamma.py`` as deposited
|
|
30
|
+
with the paper (Zenodo concept DOI 10.5281/zenodo.22060095). The port changes no
|
|
31
|
+
formula and no constant. ``tests/test_deposited.py`` pins the port to the
|
|
32
|
+
deposited module on a fixed grid; if that test fails, the port is wrong, not the
|
|
33
|
+
deposit.
|
|
34
|
+
|
|
35
|
+
Two deliberate, documented differences, neither on the numerical path:
|
|
36
|
+
|
|
37
|
+
1. ``cdf`` uses an ``if`` where the deposited module used ``numpy.where``. The
|
|
38
|
+
two arms of that ``where`` are algebraically identical -- ``(b - x)/(-a)``
|
|
39
|
+
equals ``(x - b)/a`` for every ``a != 0`` -- and ``a`` is a scalar, so the
|
|
40
|
+
branch was never selecting between different values. The ``if`` computes the
|
|
41
|
+
same number without evaluating a dead arm.
|
|
42
|
+
2. The fitted branch is recorded in :attr:`TraceGamma.branch` and a negative
|
|
43
|
+
third cumulant raises a warning. In the deposited module a negative ``k3``
|
|
44
|
+
silently takes the two-cumulant branch (see :class:`TraceGamma`); the value
|
|
45
|
+
returned here is unchanged, but the user is told.
|
|
46
|
+
"""
|
|
47
|
+
from __future__ import annotations
|
|
48
|
+
|
|
49
|
+
import warnings
|
|
50
|
+
|
|
51
|
+
import numpy as np
|
|
52
|
+
from scipy.stats import chi2 as _chi2
|
|
53
|
+
|
|
54
|
+
__all__ = [
|
|
55
|
+
"cumulants_from_traces",
|
|
56
|
+
"traces_from_quadform",
|
|
57
|
+
"cumulants_from_eigs",
|
|
58
|
+
"params_from_power_sums",
|
|
59
|
+
"TraceGamma",
|
|
60
|
+
]
|
|
61
|
+
|
|
62
|
+
#: Skewness below which the fit degenerates to the two-cumulant (Welch) form.
|
|
63
|
+
#: Frozen at the deposited value; exposed so the threshold is inspectable rather
|
|
64
|
+
#: than buried in a comparison.
|
|
65
|
+
SKEW_FLOOR = 1e-6
|
|
66
|
+
|
|
67
|
+
#: Lower clamp on the second cumulant, frozen at the deposited value.
|
|
68
|
+
VAR_FLOOR = 1e-12
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def cumulants_from_traces(t1, t2, t3):
|
|
72
|
+
r"""Cumulants of ``Q = a'Ma`` with ``a ~ N(0, D)`` from the traces.
|
|
73
|
+
|
|
74
|
+
Parameters
|
|
75
|
+
----------
|
|
76
|
+
t1, t2, t3 : float
|
|
77
|
+
The traces ``t_r = tr((MD)^r)``.
|
|
78
|
+
|
|
79
|
+
Returns
|
|
80
|
+
-------
|
|
81
|
+
tuple of float
|
|
82
|
+
``(kappa1, kappa2, kappa3) = (t1, 2*t2, 8*t3)``, Lancaster's identity
|
|
83
|
+
``kappa_r = 2^{r-1}(r-1)! t_r`` at ``r = 1, 2, 3``.
|
|
84
|
+
|
|
85
|
+
Examples
|
|
86
|
+
--------
|
|
87
|
+
>>> cumulants_from_traces(1.0, 1.0, 1.0)
|
|
88
|
+
(1.0, 2.0, 8.0)
|
|
89
|
+
"""
|
|
90
|
+
return t1, 2.0 * t2, 8.0 * t3
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
def traces_from_quadform(M, D):
|
|
94
|
+
r"""Exact ``t1, t2, t3 = tr(MD), tr((MD)^2), tr((MD)^3)``.
|
|
95
|
+
|
|
96
|
+
Parameters
|
|
97
|
+
----------
|
|
98
|
+
M : array_like, shape (p, p)
|
|
99
|
+
Symmetric form matrix.
|
|
100
|
+
D : array_like, shape (p,) or (p, p)
|
|
101
|
+
Covariance of ``a``. A 1-D argument is read as the diagonal.
|
|
102
|
+
|
|
103
|
+
Returns
|
|
104
|
+
-------
|
|
105
|
+
tuple of float
|
|
106
|
+
The three traces.
|
|
107
|
+
"""
|
|
108
|
+
M = np.asarray(M, float)
|
|
109
|
+
Dm = np.diag(np.asarray(D, float)) if np.ndim(D) == 1 else np.asarray(D, float)
|
|
110
|
+
MD = M @ Dm
|
|
111
|
+
MD2 = MD @ MD
|
|
112
|
+
return np.trace(MD), np.trace(MD2), np.trace(MD2 @ MD)
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
def cumulants_from_eigs(lam):
|
|
116
|
+
r"""Cumulants of the exact law ``sum_j lam_j chi^2_1``.
|
|
117
|
+
|
|
118
|
+
This is the generalized chi-square itself, so these cumulants are exact, not
|
|
119
|
+
an approximation: ``(sum lam, 2 sum lam^2, 8 sum lam^3)``.
|
|
120
|
+
|
|
121
|
+
Parameters
|
|
122
|
+
----------
|
|
123
|
+
lam : array_like
|
|
124
|
+
Eigenvalues of ``M^{1/2} D M^{1/2}``.
|
|
125
|
+
|
|
126
|
+
Returns
|
|
127
|
+
-------
|
|
128
|
+
tuple of float
|
|
129
|
+
``(kappa1, kappa2, kappa3)``.
|
|
130
|
+
"""
|
|
131
|
+
lam = np.asarray(lam, float)
|
|
132
|
+
return lam.sum(), 2.0 * (lam ** 2).sum(), 8.0 * (lam ** 3).sum()
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
def params_from_power_sums(lam):
|
|
136
|
+
r"""The closed-form parameters, straight from the eigenvalue power sums.
|
|
137
|
+
|
|
138
|
+
With ``p_r = sum_j lam_j^r`` (which equal the traces ``t_r`` when ``MD`` has
|
|
139
|
+
eigenvalues ``lam``),
|
|
140
|
+
|
|
141
|
+
.. math::
|
|
142
|
+
a = \frac{p_3}{p_2}, \qquad
|
|
143
|
+
\nu = \frac{p_2^3}{p_3^2}, \qquad
|
|
144
|
+
b = p_1 - \frac{p_2^2}{p_3}.
|
|
145
|
+
|
|
146
|
+
This is an *identity*, not a second method: it is the cumulant match of
|
|
147
|
+
:class:`TraceGamma` rewritten in the traces. The two agree to floating-point
|
|
148
|
+
rounding, and ``tests/test_identities.py`` checks that on designed spectra.
|
|
149
|
+
Keeping both lets each serve as the other's oracle.
|
|
150
|
+
|
|
151
|
+
Parameters
|
|
152
|
+
----------
|
|
153
|
+
lam : array_like
|
|
154
|
+
Strictly positive eigenvalues.
|
|
155
|
+
|
|
156
|
+
Returns
|
|
157
|
+
-------
|
|
158
|
+
tuple of float
|
|
159
|
+
``(a, nu, b)``.
|
|
160
|
+
"""
|
|
161
|
+
lam = np.asarray(lam, float)
|
|
162
|
+
p1, p2, p3 = lam.sum(), (lam ** 2).sum(), (lam ** 3).sum()
|
|
163
|
+
return p3 / p2, p2 ** 3 / p3 ** 2, p1 - p2 ** 2 / p3
|
|
164
|
+
|
|
165
|
+
|
|
166
|
+
def _unwrap(value, like):
|
|
167
|
+
"""Return a plain float when the input was scalar, else the array."""
|
|
168
|
+
if np.ndim(like) == 0:
|
|
169
|
+
return float(value)
|
|
170
|
+
return value
|
|
171
|
+
|
|
172
|
+
|
|
173
|
+
class TraceGamma:
|
|
174
|
+
r"""``Q ~ b + a * chi^2_nu``, matched to three cumulants of a quadratic form.
|
|
175
|
+
|
|
176
|
+
Parameters
|
|
177
|
+
----------
|
|
178
|
+
k1, k2, k3 : float
|
|
179
|
+
The first three cumulants of ``Q``. ``k2`` is clamped below at
|
|
180
|
+
:data:`VAR_FLOOR`.
|
|
181
|
+
|
|
182
|
+
Attributes
|
|
183
|
+
----------
|
|
184
|
+
a, nu, b : float
|
|
185
|
+
Scale, degrees of freedom, shift.
|
|
186
|
+
k1, k2, k3 : float
|
|
187
|
+
The cumulants actually used, after clamping.
|
|
188
|
+
branch : str
|
|
189
|
+
``"three-cumulant"`` or ``"welch-two-cumulant"`` -- which fit was taken.
|
|
190
|
+
|
|
191
|
+
Notes
|
|
192
|
+
-----
|
|
193
|
+
**The two-cumulant branch is requested, not discovered.** It is taken when
|
|
194
|
+
the standardized skewness ``gamma1 = k3 / k2**1.5`` does not exceed
|
|
195
|
+
:data:`SKEW_FLOOR`. For a quadratic form with *positive* eigenvalues that
|
|
196
|
+
cannot happen in practice: ``gamma1 = 2 sqrt(2) p_3 / p_2**1.5``, which is
|
|
197
|
+
minimised at equal eigenvalues and is then ``2 sqrt(2) / sqrt(m)`` for ``m``
|
|
198
|
+
of them, so reaching ``1e-6`` would take about ``8e12`` eigenvalues. The
|
|
199
|
+
branch is therefore reached by *supplying* ``k3 = 0`` -- which is exactly how
|
|
200
|
+
the paper states the Welch special case -- or a negative ``k3``.
|
|
201
|
+
|
|
202
|
+
**A negative third cumulant is discarded, with a warning.** An indefinite
|
|
203
|
+
``M`` can give ``k3 < 0``. ``gamma1`` is then negative, so the fit falls to
|
|
204
|
+
the two-cumulant form and the third cumulant plays no part. The deposited
|
|
205
|
+
module does this silently; this class does the same arithmetic and warns.
|
|
206
|
+
|
|
207
|
+
Examples
|
|
208
|
+
--------
|
|
209
|
+
Pearson's reference is the equal-eigenvalue member:
|
|
210
|
+
|
|
211
|
+
>>> tg = TraceGamma.from_eigs([1.0] * 5)
|
|
212
|
+
>>> [round(v, 12) for v in tg.params()]
|
|
213
|
+
[1.0, 5.0, 0.0]
|
|
214
|
+
>>> tg.branch
|
|
215
|
+
'three-cumulant'
|
|
216
|
+
|
|
217
|
+
Welch's reference is the two-cumulant member, obtained by asking for it:
|
|
218
|
+
|
|
219
|
+
>>> w = TraceGamma(10.0, 20.0, 0.0)
|
|
220
|
+
>>> w.branch
|
|
221
|
+
'welch-two-cumulant'
|
|
222
|
+
>>> [round(v, 12) for v in w.params()]
|
|
223
|
+
[1.0, 10.0, 0.0]
|
|
224
|
+
"""
|
|
225
|
+
|
|
226
|
+
def __init__(self, k1, k2, k3):
|
|
227
|
+
self.k1 = float(k1)
|
|
228
|
+
self.k2 = float(max(k2, VAR_FLOOR))
|
|
229
|
+
self.k3 = float(k3)
|
|
230
|
+
g1 = self.k3 / self.k2 ** 1.5
|
|
231
|
+
if g1 > SKEW_FLOOR:
|
|
232
|
+
self.branch = "three-cumulant"
|
|
233
|
+
self.nu = float(8.0 / g1 ** 2)
|
|
234
|
+
self.a = float(np.sqrt(self.k2 / (2.0 * self.nu)))
|
|
235
|
+
self.b = float(self.k1 - self.a * self.nu)
|
|
236
|
+
else:
|
|
237
|
+
self.branch = "welch-two-cumulant"
|
|
238
|
+
if self.k3 < 0.0:
|
|
239
|
+
warnings.warn(
|
|
240
|
+
"third cumulant k3=%.6g is negative, so the standardized "
|
|
241
|
+
"skewness is negative and the three-cumulant fit does not "
|
|
242
|
+
"apply; falling back to the two-cumulant (Welch) reference, "
|
|
243
|
+
"which ignores k3 entirely. Inspect .branch to confirm which "
|
|
244
|
+
"fit you have." % self.k3,
|
|
245
|
+
RuntimeWarning,
|
|
246
|
+
stacklevel=2,
|
|
247
|
+
)
|
|
248
|
+
self.nu = float(2.0 * self.k1 ** 2 / self.k2)
|
|
249
|
+
self.a = float(self.k2 / (2.0 * self.k1))
|
|
250
|
+
self.b = 0.0
|
|
251
|
+
|
|
252
|
+
# ---- constructors -----------------------------------------------------
|
|
253
|
+
@classmethod
|
|
254
|
+
def from_traces(cls, t1, t2, t3, kurt_widen=0.0, skew_shift=0.0):
|
|
255
|
+
r"""Build from the traces, with the two estimable non-normal corrections.
|
|
256
|
+
|
|
257
|
+
Parameters
|
|
258
|
+
----------
|
|
259
|
+
t1, t2, t3 : float
|
|
260
|
+
Traces ``tr((MD)^r)``.
|
|
261
|
+
kurt_widen : float, optional
|
|
262
|
+
Added to ``kappa_2``: the marginal-kurtosis widening
|
|
263
|
+
``sum_i M_ii^2 kappa4(a_i)``. See
|
|
264
|
+
:func:`tracegamma.correction.kurtosis_widening`.
|
|
265
|
+
skew_shift : float, optional
|
|
266
|
+
Added to ``kappa_1``: the test-specific mean/variance covariance
|
|
267
|
+
inflation.
|
|
268
|
+
|
|
269
|
+
Returns
|
|
270
|
+
-------
|
|
271
|
+
TraceGamma
|
|
272
|
+
"""
|
|
273
|
+
k1, k2, k3 = cumulants_from_traces(t1, t2, t3)
|
|
274
|
+
return cls(k1 + skew_shift, k2 + kurt_widen, k3)
|
|
275
|
+
|
|
276
|
+
@classmethod
|
|
277
|
+
def from_quadform(cls, M, D, **kw):
|
|
278
|
+
"""Build from the form matrix and covariance directly."""
|
|
279
|
+
return cls.from_traces(*traces_from_quadform(M, D), **kw)
|
|
280
|
+
|
|
281
|
+
@classmethod
|
|
282
|
+
def from_eigs(cls, lam):
|
|
283
|
+
"""Build from the eigenvalues of ``M^{1/2} D M^{1/2}``."""
|
|
284
|
+
return cls(*cumulants_from_eigs(lam))
|
|
285
|
+
|
|
286
|
+
# ---- distribution interface -------------------------------------------
|
|
287
|
+
def cdf(self, x):
|
|
288
|
+
"""Distribution function ``P(Q <= x)``."""
|
|
289
|
+
xa = np.asarray(x, float)
|
|
290
|
+
z = (xa - self.b) / self.a
|
|
291
|
+
out = _chi2.cdf(z, self.nu) if self.a > 0 else _chi2.cdf((self.b - xa) / -self.a, self.nu)
|
|
292
|
+
return _unwrap(out, x)
|
|
293
|
+
|
|
294
|
+
def sf(self, x):
|
|
295
|
+
"""Survival function ``P(Q > x)``."""
|
|
296
|
+
return _unwrap(1.0 - self.cdf(x), x)
|
|
297
|
+
|
|
298
|
+
def ppf(self, q):
|
|
299
|
+
"""Quantile function."""
|
|
300
|
+
return _unwrap(self.b + self.a * _chi2.ppf(q, self.nu), q)
|
|
301
|
+
|
|
302
|
+
def pdf(self, x):
|
|
303
|
+
"""Density."""
|
|
304
|
+
z = (np.asarray(x, float) - self.b) / self.a
|
|
305
|
+
return _unwrap(_chi2.pdf(z, self.nu) / self.a, x)
|
|
306
|
+
|
|
307
|
+
def rvs(self, size, rng=None):
|
|
308
|
+
"""Draw variates. ``rng`` is a :class:`numpy.random.Generator`."""
|
|
309
|
+
rng = rng or np.random.default_rng()
|
|
310
|
+
return self.b + self.a * rng.chisquare(self.nu, size)
|
|
311
|
+
|
|
312
|
+
def cutoff(self, alpha=0.05):
|
|
313
|
+
"""Upper-tail critical value, the ``1 - alpha`` quantile."""
|
|
314
|
+
return self.ppf(1.0 - alpha)
|
|
315
|
+
|
|
316
|
+
def cumulants(self):
|
|
317
|
+
"""The ``(k1, k2, k3)`` actually used, after clamping."""
|
|
318
|
+
return self.k1, self.k2, self.k3
|
|
319
|
+
|
|
320
|
+
def params(self):
|
|
321
|
+
"""The fitted ``(a, nu, b)`` as plain floats."""
|
|
322
|
+
return float(self.a), float(self.nu), float(self.b)
|
|
323
|
+
|
|
324
|
+
def __repr__(self):
|
|
325
|
+
return (
|
|
326
|
+
"TraceGamma(a=%.4g, nu=%.4g, b=%.4g; k1=%.4g, k2=%.4g, k3=%.4g, "
|
|
327
|
+
"branch=%s)" % (self.a, self.nu, self.b, self.k1, self.k2, self.k3, self.branch)
|
|
328
|
+
)
|
tracegamma/correction.py
ADDED
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
# (c) 2026 William J. Dwyer. MIT License.
|
|
2
|
+
r"""The estimable non-normal correction.
|
|
3
|
+
|
|
4
|
+
When the input vector is not exactly normal, the Gaussian trace cumulants are
|
|
5
|
+
wrong in a way that is itself estimable. For the simplest case ``Q = sum_j a_j^2``
|
|
6
|
+
with ``a_j`` standardized i.i.d. with standardized moments ``mu4``, ``mu6``:
|
|
7
|
+
|
|
8
|
+
.. math::
|
|
9
|
+
\kappa_1 = m, \qquad
|
|
10
|
+
\kappa_2 = m(\mu_4 - 1), \qquad
|
|
11
|
+
\kappa_3 = m(\mu_6 - 3\mu_4 + 2).
|
|
12
|
+
|
|
13
|
+
These are exact, not asymptotic. Substituting the normal values
|
|
14
|
+
``mu4 = 3, mu6 = 15`` returns the Gaussian answer ``(m, 2m, 8m)``, which is the
|
|
15
|
+
identity :func:`tracegamma.core.cumulants_from_eigs` gives for ``m`` unit
|
|
16
|
+
eigenvalues -- a check worth running, and ``tests/test_identities.py`` runs it.
|
|
17
|
+
|
|
18
|
+
Provenance
|
|
19
|
+
----------
|
|
20
|
+
Ported from ``qgamma_cumulant_correction.py``, where the oracle (true moments)
|
|
21
|
+
and plug-in (estimated moments) versions are both exercised against realized
|
|
22
|
+
size.
|
|
23
|
+
"""
|
|
24
|
+
from __future__ import annotations
|
|
25
|
+
|
|
26
|
+
import numpy as np
|
|
27
|
+
|
|
28
|
+
from .core import TraceGamma
|
|
29
|
+
|
|
30
|
+
__all__ = ["marginal_cumulants", "tracegamma_from_marginal", "estimate_moments",
|
|
31
|
+
"kurtosis_widening"]
|
|
32
|
+
|
|
33
|
+
#: Standardized fourth and sixth moments of the standard normal.
|
|
34
|
+
NORMAL_MU4, NORMAL_MU6 = 3.0, 15.0
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def marginal_cumulants(m, mu4=NORMAL_MU4, mu6=NORMAL_MU6):
|
|
38
|
+
r"""Exact ``(kappa1, kappa2, kappa3)`` of ``Q = sum_{j=1}^m a_j^2``.
|
|
39
|
+
|
|
40
|
+
Parameters
|
|
41
|
+
----------
|
|
42
|
+
m : int
|
|
43
|
+
Number of standardized i.i.d. terms.
|
|
44
|
+
mu4, mu6 : float
|
|
45
|
+
Standardized fourth and sixth moments of the common marginal. The
|
|
46
|
+
defaults are the normal values, which reproduce the Gaussian cumulants.
|
|
47
|
+
|
|
48
|
+
Returns
|
|
49
|
+
-------
|
|
50
|
+
tuple of float
|
|
51
|
+
|
|
52
|
+
Examples
|
|
53
|
+
--------
|
|
54
|
+
>>> marginal_cumulants(5)
|
|
55
|
+
(5.0, 10.0, 40.0)
|
|
56
|
+
"""
|
|
57
|
+
m = float(m)
|
|
58
|
+
return m, m * (mu4 - 1.0), m * (mu6 - 3.0 * mu4 + 2.0)
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def tracegamma_from_marginal(m, mu4=NORMAL_MU4, mu6=NORMAL_MU6):
|
|
62
|
+
"""The reference for ``Q = sum a_j^2`` under a common non-normal marginal."""
|
|
63
|
+
return TraceGamma(*marginal_cumulants(m, mu4, mu6))
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def estimate_moments(pool):
|
|
67
|
+
"""Plug-in ``(mu4, mu6)`` from a pooled sample, after standardizing it.
|
|
68
|
+
|
|
69
|
+
This is the deployable half of the correction: the oracle version needs
|
|
70
|
+
moments you do not have, this one estimates them from the same data.
|
|
71
|
+
"""
|
|
72
|
+
x = np.asarray(pool, float)
|
|
73
|
+
x = (x - x.mean()) / x.std()
|
|
74
|
+
return float((x ** 4).mean()), float((x ** 6).mean())
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
def kurtosis_widening(M_diag, kappa4):
|
|
78
|
+
r"""The ``kappa_2`` widening ``sum_i M_ii^2 kappa4(a_i)``.
|
|
79
|
+
|
|
80
|
+
Pass the result as ``kurt_widen`` to
|
|
81
|
+
:meth:`tracegamma.core.TraceGamma.from_traces`.
|
|
82
|
+
|
|
83
|
+
Parameters
|
|
84
|
+
----------
|
|
85
|
+
M_diag : array_like
|
|
86
|
+
The diagonal of the form matrix ``M``.
|
|
87
|
+
kappa4 : array_like or float
|
|
88
|
+
Fourth cumulant of each ``a_i`` (``mu4 - 3`` for a standardized input).
|
|
89
|
+
"""
|
|
90
|
+
M_diag = np.asarray(M_diag, float)
|
|
91
|
+
return float(np.sum(M_diag ** 2 * np.asarray(kappa4, float)))
|