gaffke 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,16 @@
1
+ __pycache__/
2
+ *.pyc
3
+ *.egg-info/
4
+ dist/
5
+ build/
6
+ .pytest_cache/
7
+ R/gaffke.Rcheck/
8
+ R/*.tar.gz
9
+ paper/*.aux
10
+ paper/*.log
11
+ paper/*.out
12
+ paper/*.fls
13
+ paper/*.fdb_latexmk
14
+ paper/*.bbl
15
+ paper/*.blg
16
+ .DS_Store
gaffke-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Louis Abraham
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.
gaffke-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,44 @@
1
+ Metadata-Version: 2.5
2
+ Name: gaffke
3
+ Version: 0.1.0
4
+ Summary: The Gaffke confidence interval for the mean of a discrete bounded variable: exact, narrow and fast
5
+ Project-URL: Homepage, https://github.com/louisabraham/gaffke
6
+ Project-URL: Source, https://github.com/louisabraham/gaffke
7
+ Author-email: Louis Abraham <abraham.cie@gmail.com>
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Keywords: Clopper-Pearson,Dirichlet,Gaffke,confidence interval,mean,multinomial,nonparametric
11
+ Classifier: Intended Audience :: Science/Research
12
+ Classifier: Operating System :: OS Independent
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Topic :: Scientific/Engineering :: Mathematics
15
+ Requires-Python: >=3.9
16
+ Requires-Dist: numpy>=1.22
17
+ Requires-Dist: scipy>=1.9
18
+ Provides-Extra: test
19
+ Requires-Dist: mpmath; extra == 'test'
20
+ Requires-Dist: pytest; extra == 'test'
21
+ Description-Content-Type: text/markdown
22
+
23
+ # gaffke (Python)
24
+
25
+ The Gaffke confidence interval for the mean of a discrete bounded variable:
26
+ **exact** (coverage at least 1 - alpha for every sample size and every
27
+ distribution), **narrow** (the shortest published interval with this
28
+ guarantee in our experiments) and **fast** (under a millisecond for any n).
29
+
30
+ ```python
31
+ from gaffke import gaffke_ci
32
+
33
+ # 3 answers "1", 5 answers "2", 2 answers "3" on a 1-3 scale
34
+ gaffke_ci([3, 5, 2], [1, 2, 3], alpha=0.05)
35
+ # {'lower': 1.4276..., 'upper': 2.4186...}
36
+ ```
37
+
38
+ For two values it is the Clopper-Pearson interval. The endpoints are
39
+ quantiles of a weighted sum of Dirichlet variables; `dirichlet_sum_cdf`,
40
+ `dirichlet_sum_sf`, `dirichlet_sum_pdf` and `dirichlet_sum_ppf` give this
41
+ law directly.
42
+
43
+ Method, references and experiments: see the implementation note at
44
+ https://github.com/louisabraham/gaffke.
gaffke-0.1.0/README.md ADDED
@@ -0,0 +1,22 @@
1
+ # gaffke (Python)
2
+
3
+ The Gaffke confidence interval for the mean of a discrete bounded variable:
4
+ **exact** (coverage at least 1 - alpha for every sample size and every
5
+ distribution), **narrow** (the shortest published interval with this
6
+ guarantee in our experiments) and **fast** (under a millisecond for any n).
7
+
8
+ ```python
9
+ from gaffke import gaffke_ci
10
+
11
+ # 3 answers "1", 5 answers "2", 2 answers "3" on a 1-3 scale
12
+ gaffke_ci([3, 5, 2], [1, 2, 3], alpha=0.05)
13
+ # {'lower': 1.4276..., 'upper': 2.4186...}
14
+ ```
15
+
16
+ For two values it is the Clopper-Pearson interval. The endpoints are
17
+ quantiles of a weighted sum of Dirichlet variables; `dirichlet_sum_cdf`,
18
+ `dirichlet_sum_sf`, `dirichlet_sum_pdf` and `dirichlet_sum_ppf` give this
19
+ law directly.
20
+
21
+ Method, references and experiments: see the implementation note at
22
+ https://github.com/louisabraham/gaffke.
@@ -0,0 +1,31 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "gaffke"
7
+ version = "0.1.0"
8
+ description = "The Gaffke confidence interval for the mean of a discrete bounded variable: exact, narrow and fast"
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ authors = [{ name = "Louis Abraham", email = "abraham.cie@gmail.com" }]
13
+ requires-python = ">=3.9"
14
+ dependencies = ["numpy>=1.22", "scipy>=1.9"]
15
+ keywords = ["confidence interval", "mean", "multinomial", "Dirichlet", "Gaffke", "Clopper-Pearson", "nonparametric"]
16
+ classifiers = [
17
+ "Programming Language :: Python :: 3",
18
+ "Operating System :: OS Independent",
19
+ "Intended Audience :: Science/Research",
20
+ "Topic :: Scientific/Engineering :: Mathematics",
21
+ ]
22
+
23
+ [project.optional-dependencies]
24
+ test = ["pytest", "mpmath"]
25
+
26
+ [project.urls]
27
+ Homepage = "https://github.com/louisabraham/gaffke"
28
+ Source = "https://github.com/louisabraham/gaffke"
29
+
30
+ [tool.hatch.build.targets.wheel]
31
+ packages = ["src/gaffke"]
@@ -0,0 +1,28 @@
1
+ """gaffke: the Gaffke confidence interval for the mean of a discrete bounded variable.
2
+
3
+ >>> from gaffke import gaffke_ci
4
+ >>> gaffke_ci([3, 5, 2], [1, 2, 3]) # counts of the values 1, 2, 3
5
+ {'lower': 1.4276..., 'upper': 2.4186...}
6
+
7
+ The endpoints are quantiles of a weighted sum of Dirichlet variables,
8
+ computed by gaffke.dirichlet_sum (see the implementation note in the
9
+ repository).
10
+ """
11
+
12
+ from gaffke.ci import gaffke_ci
13
+ from gaffke.dirichlet_sum import (
14
+ dirichlet_sum_cdf,
15
+ dirichlet_sum_pdf,
16
+ dirichlet_sum_ppf,
17
+ dirichlet_sum_sf,
18
+ )
19
+
20
+ __version__ = "0.1.0"
21
+
22
+ __all__ = [
23
+ "gaffke_ci",
24
+ "dirichlet_sum_cdf",
25
+ "dirichlet_sum_sf",
26
+ "dirichlet_sum_pdf",
27
+ "dirichlet_sum_ppf",
28
+ ]
@@ -0,0 +1,66 @@
1
+ """Gaffke confidence interval for the multinomial weighted mean.
2
+
3
+ For X ~ Mult(n, p) and mu = v^T p, the interval is built from two
4
+ Dirichlet posteriors that each add one pseudo-count at an extreme
5
+ category:
6
+
7
+ P_- ~ Dir(x + e_min), P_+ ~ Dir(x + e_max)
8
+ CI = [ Q_{alpha/2}(v^T P_-), Q_{1-alpha/2}(v^T P_+) ]
9
+
10
+ where e_min / e_max are the indicators of the categories carrying the
11
+ smallest / largest value. There is no optimisation over the simplex
12
+ and no enumeration of multinomial outcomes: each endpoint is one
13
+ scalar quantile of a Dirichlet-weighted sum.
14
+
15
+ Categories with a zero Dirichlet parameter contribute no mass and are
16
+ dropped, which is the correct limit of Dir(alpha) as alpha_i -> 0.
17
+ Categories with equal values are merged. See gaffke.dirichlet_sum for
18
+ the computation of the quantile.
19
+ """
20
+
21
+ from __future__ import annotations
22
+
23
+ import numpy as np
24
+
25
+ from gaffke.dirichlet_sum import dirichlet_sum_ppf
26
+
27
+
28
+ def gaffke_ci(counts, values, alpha=0.05, *, tol=1e-12):
29
+ """Gaffke confidence interval for the multinomial weighted mean.
30
+
31
+ Parameters
32
+ ----------
33
+ counts : array-like of int
34
+ Observed category counts.
35
+ values : array-like of float
36
+ Numerical value assigned to each category.
37
+ alpha : float
38
+ Significance level (default 0.05 for a 95% CI).
39
+ tol : float
40
+ Tolerance of the root finder, relative to max(values) - min(values).
41
+
42
+ Returns
43
+ -------
44
+ dict with keys: lower, upper.
45
+ """
46
+ counts = np.asarray(counts, dtype=np.float64)
47
+ values = np.asarray(values, dtype=np.float64)
48
+
49
+ if counts.ndim != 1 or len(counts) != len(values) or len(counts) == 0:
50
+ raise ValueError("counts and values must be 1-d with the same nonzero length")
51
+ if np.any(counts < 0) or not np.all(np.isfinite(counts)):
52
+ raise ValueError("counts must be finite and nonnegative")
53
+ if not np.all(np.isfinite(values)):
54
+ raise ValueError("values must be finite")
55
+ if not 0.0 < alpha < 1.0:
56
+ raise ValueError("alpha must be in (0, 1)")
57
+
58
+ a_lo = counts.copy()
59
+ a_lo[int(np.argmin(values))] += 1.0
60
+ a_hi = counts.copy()
61
+ a_hi[int(np.argmax(values))] += 1.0
62
+
63
+ lower = dirichlet_sum_ppf(a_lo, values, alpha / 2.0, xtol=tol)
64
+ upper = dirichlet_sum_ppf(a_hi, values, alpha / 2.0, upper=True, xtol=tol)
65
+
66
+ return {"lower": float(lower), "upper": float(upper)}
@@ -0,0 +1,372 @@
1
+ """Distribution of a weighted sum of Dirichlet coordinates.
2
+
3
+ Y = w^T P with P ~ Dirichlet(a), a_i > 0. This module gives the CDF,
4
+ the density and the quantile function of Y, with a small relative
5
+ error also far in the tails.
6
+
7
+ Reduction. With independent G_i ~ Gamma(a_i, 1), P = G / sum(G), so
8
+ P(Y <= y) = P(Z <= 0) with Z = sum_i lam_i G_i and lam_i = w_i - y.
9
+ The moment generating function of Z is
10
+
11
+ M(s) = E[exp(s Z)] = prod_i (1 - s lam_i)^(-a_i),
12
+
13
+ finite on the strip 1/min(lam) < Re s < 1/max(lam).
14
+
15
+ Inversion on a shifted line. For a real c in that strip,
16
+
17
+ P(Z <= 0) = -(1/pi) int_0^inf Re[ M(c + i t) / (c + i t) ] dt (c < 0),
18
+ P(Z > 0) = +(1/pi) int_0^inf Re[ M(c + i t) / (c + i t) ] dt (c > 0).
19
+
20
+ For c -> 0 this is the Gil-Pelaez formula. We take c at the saddle
21
+ point of log M (the root of K'(c) = 0, K = log M), on the side of the
22
+ smaller tail. On this line the integrand does not oscillate near
23
+ t = 0 and its size is exp(K(c)), the size of the tail. Thus the
24
+ error is small relative to the tail probability, not only in absolute
25
+ value. The density of Y follows from d/dy log M(s) = -s sum a_i /
26
+ (1 - s lam_i):
27
+
28
+ f(y) = (1/pi) int_0^inf Re[ M(c + i t) sum_i a_i / (1 - (c + i t) lam_i) ] dt.
29
+
30
+ Quadrature. We scale s by sd(Z) so the integrand varies on a scale
31
+ of order one. All singularities of the integrand (branch points of
32
+ M and the pole at s = 0) are on the imaginary axis of t. We cut the
33
+ half line at T, where the integrand is below e^-40 times its value at
34
+ t = 0, and we split [0, T] into panels [0, h0], [h0, 2 h0],
35
+ [2 h0, 4 h0], ... A point i b of the imaginary axis is at a distance
36
+ of at least c from the panel [c, 2 c], which is the panel length.
37
+ Thus a 12-point Gauss-Legendre rule converges at the same fast
38
+ geometric rate on each panel, for every position of the singularities
39
+ (y close to a value w_i, small parameters with slow decay, large
40
+ parameters with a narrow peak). The phase of the integrand can still
41
+ turn fast far from t = 0 when the parameters have very different sizes
42
+ (for example 1 and 10^4); we then split each panel so that the phase
43
+ turns by at most 3 radians on each half of a panel.
44
+
45
+ Quantile. Newton's method on log(tail) - log(q) as a function of
46
+ log(d), with d the distance from y to the end of the tail, and with
47
+ the density for the derivative. It runs inside a bracket that always
48
+ contains the root (bisection when a Newton step leaves the bracket).
49
+ The start point is the quantile of the Beta law with the same mean
50
+ and variance on [min w, max w]. Two special cases have closed forms:
51
+ one distinct value (Y is constant) and two distinct values (Y is an
52
+ affine image of a Beta variable).
53
+ """
54
+
55
+ from __future__ import annotations
56
+
57
+ import math
58
+
59
+ import numpy as np
60
+ from scipy.special import betainccinv, betaincinv
61
+
62
+ __all__ = ["dirichlet_sum_cdf", "dirichlet_sum_sf", "dirichlet_sum_pdf", "dirichlet_sum_ppf"]
63
+
64
+ _N_GL = 12
65
+ _gl_x, _gl_w = np.polynomial.legendre.leggauss(_N_GL)
66
+ _gl_t = 0.5 * (_gl_x + 1.0) # nodes on [0, 1]
67
+ _gl_w = 0.5 * _gl_w # weights on [0, 1]
68
+ _LOG_CUT = 40.0 # truncate the integral where the integrand < e^-40
69
+ _MAX_HALF_PHASE = 3.0 # max phase change on half a panel (radians)
70
+
71
+
72
+ def _reduce(a, w):
73
+ """Drop null parameters and merge equal values (sum of parameters).
74
+
75
+ The merge is exact: coordinates of a Dirichlet vector that share a
76
+ value can be added, and the sum is again Dirichlet (aggregation).
77
+ Returns the sorted distinct values and their parameters.
78
+ """
79
+ a = np.asarray(a, dtype=np.float64)
80
+ w = np.asarray(w, dtype=np.float64)
81
+ keep = a > 0
82
+ a, w = a[keep], w[keep]
83
+ if len(w) == 0:
84
+ raise ValueError("all Dirichlet parameters are zero")
85
+ wu, inv = np.unique(w, return_inverse=True)
86
+ if len(wu) < len(w):
87
+ a = np.bincount(inv, weights=a, minlength=len(wu))
88
+ else:
89
+ a = a[np.argsort(w, kind="stable")]
90
+ return a, wu
91
+
92
+
93
+ def _saddle(a, ls, z, bound, s0=None):
94
+ """Approximate root of K'(s) = sum a ls / (1 - s ls) between 0 and bound.
95
+
96
+ K' is increasing, with a pole at bound. Bracketed Newton; we stop
97
+ when |K'(s)| <= 0.1 sqrt(K''(s)): then the phase of the integrand
98
+ turns by less than 0.1 radian over the width of its peak. More
99
+ accuracy is not useful, since any c in the strip gives the exact
100
+ integral.
101
+ """
102
+ if z > 0:
103
+ b_lo, b_hi = bound, 0.0
104
+ else:
105
+ b_lo, b_hi = 0.0, bound
106
+ s = -z if s0 is None else s0 # -z is exact for a normal law
107
+ if not (b_lo < s < b_hi):
108
+ s = 0.5 * bound
109
+ g_prev = math.inf
110
+ for _ in range(100):
111
+ d = 1.0 / (1.0 - s * ls)
112
+ al = a * ls * d
113
+ g = float(al.sum())
114
+ dg = float(al @ (ls * d))
115
+ if g * g <= 0.01 * dg:
116
+ return s
117
+ if g > 0.0:
118
+ b_hi = s
119
+ else:
120
+ b_lo = s
121
+ s_new = s - g / dg
122
+ # bisection when Newton leaves the bracket or converges slowly
123
+ # (close to the pole, K' is far from linear)
124
+ if not (b_lo < s_new < b_hi) or abs(g) > 0.5 * g_prev:
125
+ s_new = 0.5 * (b_lo + b_hi)
126
+ g_prev = abs(g)
127
+ s = s_new
128
+ return s
129
+
130
+
131
+ def _cut_point(a, lp):
132
+ """T with 1/2 sum a log(1 + T^2 lp^2) ~= _LOG_CUT (Newton in log T)."""
133
+ a2 = lp * lp
134
+ t = math.sqrt(2.0 * _LOG_CUT / float(a @ a2)) # exact for large a
135
+ for _ in range(60):
136
+ x = t * t * a2
137
+ g = 0.5 * float(a @ np.log1p(x)) - _LOG_CUT
138
+ if -2.0 < g < 4.0: # e^-44 < |integrand| < e^-38
139
+ break
140
+ dg = float(a @ (x / (1.0 + x))) # d g / d log T
141
+ t *= math.exp(-max(min(g / dg, 3.0), -3.0))
142
+ return t
143
+
144
+
145
+ _POW2 = np.concatenate(([0.0], 2.0 ** np.arange(80)))
146
+
147
+
148
+ def _edges(t_max, t_sing):
149
+ """Panel edges 0, h0, 2 h0, ..., h0 2^(m-1), t_max.
150
+
151
+ t_sing is the distance from 0 to the nearest singularity.
152
+ """
153
+ h0 = min(t_max, 0.5 * t_sing, 1.0)
154
+ m = max(0, math.ceil(math.log2(t_max / h0) - 1e-9))
155
+ edges = np.empty(m + 2)
156
+ edges[:-1] = h0 * _POW2[: m + 1]
157
+ edges[-1] = t_max
158
+ return edges
159
+
160
+
161
+ def _nodes(edges):
162
+ """Gauss-Legendre nodes and weights on the panels."""
163
+ h = edges[1:] - edges[:-1]
164
+ t = (edges[:-1, None] + h[:, None] * _gl_t).ravel()
165
+ wt = (h[:, None] * _gl_w).ravel()
166
+ return t, wt, h
167
+
168
+
169
+ def _split(edges, h, dtheta):
170
+ """Split the panels on which the phase turns too fast.
171
+
172
+ dtheta is the derivative of the phase at the nodes. A panel of
173
+ length h with |dtheta| <= W has at most W h / 2 radians of phase on
174
+ each side of its center; we keep this below _MAX_HALF_PHASE, where
175
+ the 12-point rule integrates exp(i W t) with an error below 1e-14.
176
+ Returns None when no panel must be split.
177
+ """
178
+ w_max = np.abs(dtheta).reshape(len(h), _N_GL).max(axis=1)
179
+ parts = np.ceil(w_max * h / (2.0 * _MAX_HALF_PHASE))
180
+ if parts.max() <= 1.0:
181
+ return None
182
+ parts = np.maximum(parts, 1.0).astype(np.int64)
183
+ sub = np.repeat(h / parts, parts)
184
+ start = np.repeat(edges[:-1], parts)
185
+ idx = np.arange(len(sub)) - np.repeat(np.cumsum(parts) - parts, parts)
186
+ out = np.empty(len(sub) + 1)
187
+ out[:-1] = start + idx * sub
188
+ out[-1] = edges[-1]
189
+ return out
190
+
191
+
192
+ def _tail_pdf(a, w, y, need_pdf=True, s0=None):
193
+ """Smaller tail of Y at y, and the density.
194
+
195
+ y must be strictly inside (min w, max w). Returns
196
+ (upper, log_tail, log_pdf, s): upper is False when log_tail is
197
+ log P(Y <= y) and True when it is log P(Y > y); s is the saddle
198
+ point (a start point for the next call at a close y).
199
+ """
200
+ lam = w - y
201
+ sd = math.sqrt(float(a @ (lam * lam)))
202
+ ls = lam / sd
203
+ z = float(a @ ls) # E[Z] / sd(Z), > 0 when y is below the mean
204
+ upper = z < 0.0
205
+ bound = 1.0 / float(ls.max() if upper else ls.min()) # branch point
206
+ s = _saddle(a, ls, z, bound, s0)
207
+ c_min = min(1.0, 0.5 * abs(bound))
208
+ c = s if abs(s) >= c_min else math.copysign(c_min, bound)
209
+ p = 1.0 - c * ls # > 0 on the strip
210
+ lp = ls / p
211
+ k_c = -float(a @ np.log(p)) # K(c) = log M(c)
212
+ t_max = _cut_point(a, lp)
213
+ edges = _edges(t_max, min(abs(c), 1.0 / float(np.max(np.abs(lp)))))
214
+ t, wt, h = _nodes(edges)
215
+ x = np.multiply.outer(t, lp) # (nodes, k)
216
+ x2 = x * x
217
+ d = 1.0 / (1.0 + x2)
218
+ # The phase theta(t) = sum a atan(t lp) has derivative d @ (a lp).
219
+ # Its linear part is zero at the saddle point, but with parameters
220
+ # of very different sizes it can turn fast away from t = 0.
221
+ new_edges = _split(edges, h, d @ (a * lp))
222
+ if new_edges is not None:
223
+ t, wt, h = _nodes(new_edges)
224
+ x = np.multiply.outer(t, lp)
225
+ x2 = x * x
226
+ d = 1.0 / (1.0 + x2)
227
+ theta = np.arctan(x) @ a
228
+ r = np.exp(-0.5 * (np.log1p(x2) @ a))
229
+ cs, sn = np.cos(theta), np.sin(theta)
230
+ integral = float(wt @ (r * (c * cs + t * sn) / (c * c + t * t)))
231
+ tail = integral if upper else -integral
232
+ log_tail = k_c + math.log(tail / math.pi) if tail > 0.0 else -math.inf
233
+ if not need_pdf:
234
+ return upper, log_tail, None, s
235
+ ap = a / p
236
+ s_re = d @ ap
237
+ s_im = (x * d) @ ap
238
+ dens = float(wt @ (r * (cs * s_re - sn * s_im)))
239
+ log_pdf = k_c + math.log(dens / (math.pi * sd)) if dens > 0.0 else -math.inf
240
+ return upper, log_tail, log_pdf, s
241
+
242
+
243
+ def _log_tails(upper, log_tail):
244
+ """(log P(Y <= y), log P(Y > y)) from the smaller tail."""
245
+ other = math.log1p(-math.exp(log_tail)) if log_tail < 0.0 else -math.inf
246
+ return (other, log_tail) if upper else (log_tail, other)
247
+
248
+
249
+ def _cdf_sf(a, w, y):
250
+ a, w = _reduce(a, w)
251
+ y = float(y)
252
+ if len(w) == 1:
253
+ return (0.0, 1.0) if y < w[0] else (1.0, 0.0)
254
+ if y <= w[0]:
255
+ return 0.0, 1.0
256
+ if y >= w[-1]:
257
+ return 1.0, 0.0
258
+ lo, R = float(w[0]), float(w[-1] - w[0])
259
+ upper, lt, _, _ = _tail_pdf(a, (w - lo) / R, (y - lo) / R, need_pdf=False)
260
+ lf, ls = _log_tails(upper, lt)
261
+ return math.exp(lf), math.exp(ls)
262
+
263
+
264
+ def dirichlet_sum_cdf(a, w, y):
265
+ """P(w^T P <= y) for P ~ Dirichlet(a)."""
266
+ return _cdf_sf(a, w, y)[0]
267
+
268
+
269
+ def dirichlet_sum_sf(a, w, y):
270
+ """P(w^T P > y) for P ~ Dirichlet(a)."""
271
+ return _cdf_sf(a, w, y)[1]
272
+
273
+
274
+ def dirichlet_sum_pdf(a, w, y):
275
+ """Density of w^T P at y for P ~ Dirichlet(a), with 2+ distinct values."""
276
+ a, w = _reduce(a, w)
277
+ if len(w) < 2 or not (w[0] < y < w[-1]):
278
+ return 0.0
279
+ lo, R = float(w[0]), float(w[-1] - w[0])
280
+ return math.exp(_tail_pdf(a, (w - lo) / R, (y - lo) / R)[2]) / R
281
+
282
+
283
+ def dirichlet_sum_ppf(a, w, q, *, upper=False, xtol=1e-12, return_info=False):
284
+ """Quantile of Y = w^T P for P ~ Dirichlet(a).
285
+
286
+ Returns y with P(Y <= y) = q, or with P(Y > y) = q if upper is True
287
+ (use this form for upper quantiles with a small q: it keeps the
288
+ relative accuracy of q). xtol is the tolerance on the root,
289
+ relative to max(w) - min(w): the iteration stops when a Newton step
290
+ is smaller than xtol, or when 100 times the predicted error after
291
+ the step (from the curvature) is smaller than xtol.
292
+ """
293
+ a, w = _reduce(a, w)
294
+ info = {"evals": 0, "method": "const"}
295
+
296
+ def done(res):
297
+ return (float(res), info) if return_info else float(res)
298
+
299
+ if not upper and q > 0.5:
300
+ q, upper = 1.0 - q, True
301
+ elif upper and q > 0.5:
302
+ q, upper = 1.0 - q, False
303
+ lo, hi = float(w[0]), float(w[-1])
304
+ if len(w) == 1:
305
+ return done(lo)
306
+ if q <= 0.0:
307
+ return done(hi if upper else lo)
308
+ R = hi - lo
309
+ w01 = (w - lo) / R
310
+ w01[-1] = 1.0
311
+ if len(w) == 2:
312
+ # Y = lo + R * B with B ~ Beta(a_2, a_1)
313
+ info["method"] = "beta"
314
+ b = betainccinv(a[1], a[0], q) if upper else betaincinv(a[1], a[0], q)
315
+ return done(lo + R * float(b))
316
+
317
+ info["method"] = "newton"
318
+ A = float(a.sum())
319
+ m = float(a @ w01) / A
320
+ var = float(a @ (w01 - m) ** 2) / (A * (A + 1.0))
321
+ nu = m * (1.0 - m) / var - 1.0 # Beta(m nu, (1 - m) nu): same moments
322
+ y = float(betainccinv(m * nu, (1.0 - m) * nu, q) if upper
323
+ else betaincinv(m * nu, (1.0 - m) * nu, q))
324
+ if not (0.0 < y < 1.0):
325
+ y = m
326
+ # Work with the distance d to the end of the tail: d = y (lower
327
+ # tail) or d = 1 - y (upper tail). The tail is increasing in d and
328
+ # close to C d^a near d = 0, so Newton's method runs on
329
+ # log(tail) - log(q) as a function of log(d).
330
+ d = 1.0 - y if upper else y
331
+ log_q = math.log(q)
332
+ d_lo, d_hi = 0.0, 1.0 # the root is in (d_lo, d_hi)
333
+ s0 = None
334
+ u_prev = slope_prev = None
335
+ for _ in range(200):
336
+ up, lt, lpdf, s0 = _tail_pdf(a, w01, 1.0 - d if upper else d, s0=s0)
337
+ info["evals"] += 1
338
+ lf, ls = _log_tails(up, lt)
339
+ lt = ls if upper else lf
340
+ g = lt - log_q
341
+ if g == 0.0:
342
+ break
343
+ if g < 0.0:
344
+ d_lo = d
345
+ else:
346
+ d_hi = d
347
+ # Newton step in u = log(d): d g / d u = d * pdf / tail
348
+ u = math.log(d)
349
+ slope = d * math.exp(lpdf - lt) if lpdf > -math.inf else 0.0
350
+ du = -g / slope if slope > 0.0 else math.nan
351
+ d_new = d * math.exp(max(-50.0, min(50.0, du))) if math.isfinite(du) else math.inf
352
+ inside = d_lo <= d_new <= d_hi
353
+ astep = abs(d_new - d)
354
+ # Error after a Newton step: about |g''/(2 g')| du^2 (in u). We
355
+ # estimate g'' by the change of the slope since the last point
356
+ # and stop when 100 times this error is below xtol.
357
+ fast = False
358
+ if u_prev is not None and u != u_prev and inside:
359
+ curv = abs(slope - slope_prev) / abs(u - u_prev) / (2.0 * slope)
360
+ fast = 100.0 * d_new * curv * du * du <= xtol
361
+ if astep <= xtol or fast:
362
+ if inside:
363
+ d = d_new
364
+ break
365
+ u_prev, slope_prev = u, slope
366
+ if not inside or d_new in (d_lo, d_hi):
367
+ d_new = 0.5 * (d_lo + d_hi)
368
+ d = d_new
369
+ if d_hi - d_lo <= xtol:
370
+ break
371
+ y = 1.0 - d if upper else d
372
+ return done(lo + R * y)
@@ -0,0 +1,485 @@
1
+ """Tests for the Gaffke interval and the Dirichlet weighted-sum quantile.
2
+
3
+ References used here:
4
+ - exact CDF for integer Dirichlet parameters (residue formula, rational
5
+ arithmetic): Y = v^T P is a B-spline with knot v_i of multiplicity a_i;
6
+ - Beta law for two distinct values (mpmath, 40 digits);
7
+ - Gil-Pelaez integral in mpmath (40 digits) for large n;
8
+ - Monte Carlo with 2e6 Dirichlet samples;
9
+ - exact enumeration of the multinomial law for the coverage.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import itertools
15
+ import math
16
+ from fractions import Fraction
17
+ from math import comb
18
+
19
+ import mpmath as mp
20
+ import numpy as np
21
+ import pytest
22
+ from scipy.special import gammaln, xlogy
23
+
24
+ from gaffke import gaffke_ci
25
+ from gaffke.dirichlet_sum import (
26
+ dirichlet_sum_cdf,
27
+ dirichlet_sum_pdf,
28
+ dirichlet_sum_ppf,
29
+ dirichlet_sum_sf,
30
+ )
31
+
32
+ # ── Exact references ─────────────────────────────────────────────────────────
33
+
34
+
35
+ def _series_pow(d, e, L):
36
+ """Taylor coefficients of (d + s)^e at s = 0, up to s^(L-1)."""
37
+ out = []
38
+ for r in range(L):
39
+ if e >= 0:
40
+ c = comb(e, r) if r <= e else 0
41
+ else:
42
+ c = (-1) ** r * comb(-e + r - 1, r)
43
+ out.append(c * d ** (e - r) if c else Fraction(0))
44
+ return out
45
+
46
+
47
+ def _mul(a, b, L):
48
+ out = [Fraction(0)] * L
49
+ for i, x in enumerate(a):
50
+ if x:
51
+ for j in range(L - i):
52
+ out[i + j] += x * b[j]
53
+ return out
54
+
55
+
56
+ def exact_sf(a, v, y, power=None):
57
+ """P(v^T P > y), P ~ Dir(a), integer a, distinct v (exact rationals).
58
+
59
+ P(Y > y) = sum over v_j > y of Res_{t = v_j} (t - y)^m / prod_l (t - v_l)^a_l
60
+ with m = sum(a) - 1 (Hermite-Genocchi formula for the divided
61
+ difference of (t - y)_+^m). power = m - 1 gives the density / m.
62
+ """
63
+ a = [int(t) for t in a]
64
+ v = [Fraction(t) for t in v]
65
+ y = Fraction(y)
66
+ m = sum(a) - 1 if power is None else power
67
+ tot = Fraction(0)
68
+ for j, (aj, vj) in enumerate(zip(a, v)):
69
+ if vj <= y:
70
+ continue
71
+ s = _series_pow(vj - y, m, aj)
72
+ for l, (al, vl) in enumerate(zip(a, v)):
73
+ if l != j:
74
+ s = _mul(s, _series_pow(vj - vl, -al, aj), aj)
75
+ tot += s[aj - 1]
76
+ return tot
77
+
78
+
79
+ def exact_pdf(a, v, y):
80
+ m = sum(int(t) for t in a) - 1
81
+ return m * exact_sf(a, v, y, power=m - 1)
82
+
83
+
84
+ def mp_cdf(a, w, y, dps=40):
85
+ """P(w^T P <= y) by the Gil-Pelaez integral in mpmath."""
86
+ with mp.workdps(dps):
87
+ a = [mp.mpf(float(t)) for t in a]
88
+ lam = [mp.mpf(float(t)) - mp.mpf(float(y)) for t in w]
89
+ sd = mp.sqrt(sum(ai * li * li for ai, li in zip(a, lam)))
90
+ ls = [li / sd for li in lam]
91
+
92
+ def f(v):
93
+ th = sum(ai * mp.atan(v * li) for ai, li in zip(a, ls))
94
+ lr = -sum(ai * mp.log1p(v * v * li * li) for ai, li in zip(a, ls)) / 2
95
+ return mp.sin(th) * mp.exp(lr) / v
96
+
97
+ pts = [0] + [mp.mpf(2) ** j / 64 for j in range(40)]
98
+ return mp.mpf(1) / 2 - mp.quad(f, pts) / mp.pi
99
+
100
+
101
+ def _random_integer_case(rng, kmin=3, kmax=7, amax=8):
102
+ k = int(rng.integers(kmin, kmax + 1))
103
+ a = [int(t) for t in rng.integers(1, amax + 1, k)]
104
+ num = np.sort(rng.choice(np.arange(0, 50), k, replace=False))
105
+ v = [Fraction(int(t), 49) for t in num]
106
+ return a, v, np.array([float(t) for t in v])
107
+
108
+
109
+ # ── CDF, density and quantile against exact values ───────────────────────────
110
+
111
+
112
+ @pytest.mark.parametrize("seed", range(6))
113
+ def test_cdf_matches_exact_formula(seed):
114
+ rng = np.random.default_rng(seed)
115
+ for _ in range(40):
116
+ a, v, vf = _random_integer_case(rng)
117
+ ys = list(rng.uniform(vf[0], vf[-1], 3))
118
+ ys += [vf[1] + 1e-9, vf[1] - 1e-6, vf[0] + 1e-3, vf[-1] - 1e-3]
119
+ for y in ys:
120
+ sf = exact_sf(a, v, Fraction(y))
121
+ F, S = float(1 - sf), float(sf)
122
+ tail, got = (F, dirichlet_sum_cdf(a, vf, y)) if F < 0.5 else (S, dirichlet_sum_sf(a, vf, y))
123
+ # relative error on the smaller tail
124
+ assert abs(got - tail) <= 1e-10 * tail + 1e-300, (a, vf, y, tail, got)
125
+
126
+
127
+ @pytest.mark.parametrize("seed", range(3))
128
+ def test_pdf_matches_exact_formula(seed):
129
+ rng = np.random.default_rng(100 + seed)
130
+ for _ in range(30):
131
+ a, v, vf = _random_integer_case(rng)
132
+ for y in rng.uniform(vf[0], vf[-1], 3):
133
+ ref = float(exact_pdf(a, v, Fraction(y)))
134
+ got = dirichlet_sum_pdf(a, vf, y)
135
+ assert got == pytest.approx(ref, rel=1e-8, abs=1e-300)
136
+
137
+
138
+ @pytest.mark.parametrize("seed", range(4))
139
+ def test_quantile_error_below_1e12_of_range(seed):
140
+ """Error of the root, from the exact CDF and density at the root."""
141
+ rng = np.random.default_rng(200 + seed)
142
+ for _ in range(25):
143
+ a, v, vf = _random_integer_case(rng)
144
+ for q in [1e-10, 1e-6, 0.025, 0.3, 0.5]:
145
+ for upper in [False, True]:
146
+ y = dirichlet_sum_ppf(a, vf, q, upper=upper)
147
+ sf = exact_sf(a, v, Fraction(y))
148
+ target = Fraction(q)
149
+ g = (target - sf) if upper else (1 - sf - target)
150
+ err = float(g / exact_pdf(a, v, Fraction(y)))
151
+ assert abs(err) <= 1e-12 * (vf[-1] - vf[0]), (a, vf, q, upper, err)
152
+
153
+
154
+ # ── Two distinct values: Beta law ────────────────────────────────────────────
155
+
156
+
157
+ def _beta_tails(a, b, x, big):
158
+ """(P(B <= x), P(B > x), density) for B ~ Beta(a, b)."""
159
+ if not big:
160
+ with mp.workdps(40):
161
+ xm = mp.mpf(x)
162
+ lo = mp.betainc(a, b, 0, xm, regularized=True)
163
+ dens = xm ** (a - 1) * (1 - xm) ** (b - 1) / mp.beta(a, b)
164
+ return float(lo), float(1 - lo), float(dens)
165
+ from scipy.special import betainc, betaincc
166
+ from scipy.stats import beta as beta_law
167
+
168
+ return float(betainc(a, b, x)), float(betaincc(a, b, x)), float(beta_law.pdf(x, a, b))
169
+
170
+
171
+ @pytest.mark.parametrize(
172
+ "counts",
173
+ [[0, 3], [3, 0], [1, 1], [7, 2], [999, 1], [10**6, 3], [12345, 67890], [10**9, 10**9]],
174
+ )
175
+ @pytest.mark.parametrize("alpha", [0.2, 0.05, 1e-6, 1e-12])
176
+ def test_two_values_beta(counts, alpha):
177
+ """Reference: mpmath (40 digits) for counts <= 1000, else scipy betainc."""
178
+ v = [-1.5, 2.0]
179
+ r = gaffke_ci(counts, v, alpha)
180
+ R = v[1] - v[0]
181
+ big = max(counts) > 1000
182
+ c0, c1 = counts
183
+ # lower: P ~ Dir(c0 + 1, c1), Y = v0 + R B with B ~ Beta(c1, c0 + 1)
184
+ if c1 > 0:
185
+ F, _, dens = _beta_tails(c1, c0 + 1, (r["lower"] - v[0]) / R, big)
186
+ assert abs(F - alpha / 2) / dens <= 1e-12
187
+ else:
188
+ assert r["lower"] == v[0]
189
+ # upper: P ~ Dir(c0, c1 + 1), Y = v0 + R B with B ~ Beta(c1 + 1, c0)
190
+ if c0 > 0:
191
+ _, S, dens = _beta_tails(c1 + 1, c0, (r["upper"] - v[0]) / R, big)
192
+ assert abs(S - alpha / 2) / dens <= 1e-12
193
+ else:
194
+ assert r["upper"] == v[1]
195
+
196
+
197
+ # ── Large n: high-precision quadrature and Monte Carlo ───────────────────────
198
+
199
+
200
+ @pytest.mark.parametrize("n", [10**4, 10**6, 10**8])
201
+ @pytest.mark.parametrize("q", [5e-7, 0.025])
202
+ def test_large_n_against_mpmath(n, q):
203
+ w = np.array([1.0, 2.0, 3.0, 4.0, 5.0])
204
+ a = n * np.array([0.1, 0.1, 0.2, 0.3, 0.3])
205
+ a[0] += 1.0
206
+ y = dirichlet_sum_ppf(a, w, q)
207
+ F = mp_cdf(a, w, y)
208
+ err = float((F - q)) / dirichlet_sum_pdf(a, w, y)
209
+ assert abs(err) <= 1e-12 * (w[-1] - w[0])
210
+ # relative accuracy of the CDF itself in the tail
211
+ assert dirichlet_sum_cdf(a, w, y) == pytest.approx(float(F), rel=1e-9)
212
+
213
+
214
+ @pytest.mark.parametrize("seed", range(3))
215
+ def test_monte_carlo(seed):
216
+ rng = np.random.default_rng(300 + seed)
217
+ k = int(rng.integers(3, 12))
218
+ v = np.sort(rng.normal(size=k))
219
+ n = int(10 ** rng.uniform(0.5, 3))
220
+ x = rng.multinomial(n, rng.dirichlet(np.ones(k)))
221
+ a = x.astype(float)
222
+ a[0] += 1.0
223
+ m = 2_000_000
224
+ sample = rng.dirichlet(a + 1e-300, m) @ v # 1e-300: zero parameters
225
+ for q in [0.001, 0.025, 0.5]:
226
+ for upper in [False, True]:
227
+ y = dirichlet_sum_ppf(a, v, q, upper=upper)
228
+ frac = np.mean(sample > y) if upper else np.mean(sample <= y)
229
+ assert abs(frac - q) <= 5 * math.sqrt(q * (1 - q) / m) + 1e-6
230
+
231
+
232
+ # Hard cases found by random search: parameters of very different sizes
233
+ # (fast phase away from t = 0) and a saddle point close to the pole.
234
+ HARD_CASES = [
235
+ ([21342.0, 2.0, 1.0], [0.0, 0.2285115, 1.0], 5.693413709578831e-06, True),
236
+ ([11.0, 18.0, 35.0, 243.0, 124.0], [0.0, 1.0, 2.0, 3.0, 4.0], 7.867670246976742e-11, False),
237
+ ([1.0, 630.0, 11.0, 1.0, 2.0], [0.0, 0.07010751, 0.27765248, 0.60529453, 1.0], 2.562e-08, False),
238
+ ([1.0, 292.0, 16.0, 1.0], [0.0, 0.66917395, 0.67871415, 1.0], 2.868e-09, True),
239
+ ([366.0, 1.0, 5.0, 1.0], [0.0, 0.29750274, 0.37047708, 1.0], 3.184e-12, True),
240
+ ]
241
+
242
+
243
+ def _check_against_mpmath(a, w, q, upper):
244
+ a, w = np.asarray(a, float), np.asarray(w, float)
245
+ y = dirichlet_sum_ppf(a, w, q, upper=upper)
246
+ F = mp_cdf(a, w, y)
247
+ tail = float(1 - F) if upper else float(F)
248
+ got = dirichlet_sum_sf(a, w, y) if upper else dirichlet_sum_cdf(a, w, y)
249
+ assert got == pytest.approx(tail, rel=1e-9)
250
+ err = (tail - q) / dirichlet_sum_pdf(a, w, y)
251
+ assert abs(err) <= 1e-12 * (w.max() - w.min())
252
+
253
+
254
+ @pytest.mark.parametrize("case", HARD_CASES)
255
+ def test_hard_cases_against_mpmath(case):
256
+ _check_against_mpmath(*case)
257
+
258
+
259
+ @pytest.mark.parametrize("seed", range(20))
260
+ def test_random_skewed_cases_against_mpmath(seed):
261
+ rng = np.random.default_rng(900 + seed)
262
+ k = int(rng.integers(3, 8))
263
+ a = np.round(10 ** rng.uniform(0, 5, k))
264
+ a[rng.integers(k)] = 1.0
265
+ w = np.sort(rng.uniform(size=k))
266
+ q = 10 ** rng.uniform(-12, -0.5)
267
+ _check_against_mpmath(a, w, q, bool(rng.integers(2)))
268
+
269
+
270
+ # ── Invariances ──────────────────────────────────────────────────────────────
271
+
272
+
273
+ def _close(x, y, scale):
274
+ return abs(x - y) <= 1e-11 * scale
275
+
276
+
277
+ @pytest.mark.parametrize("seed", range(5))
278
+ def test_affine_invariance(seed):
279
+ rng = np.random.default_rng(400 + seed)
280
+ k = int(rng.integers(3, 15))
281
+ v = rng.normal(size=k)
282
+ x = rng.multinomial(int(rng.integers(1, 500)), rng.dirichlet(np.ones(k)))
283
+ r = gaffke_ci(x, v, 0.05)
284
+ R = v.max() - v.min()
285
+ for b, c in [(1e-9, 0.0), (1e9, 0.0), (3.0, 1e6), (2.5, -7.0)]:
286
+ s = gaffke_ci(x, b * v + c, 0.05)
287
+ # b * v + c is rounded: allow a few ulps of |c| on top of 1e-11 R
288
+ tol = b * R + 1e-4 * abs(c)
289
+ assert _close(s["lower"], b * r["lower"] + c, tol)
290
+ assert _close(s["upper"], b * r["upper"] + c, tol)
291
+ # a negative factor exchanges the two endpoints
292
+ s = gaffke_ci(x, -2.0 * v, 0.05)
293
+ assert _close(s["lower"], -2.0 * r["upper"], 2 * R)
294
+ assert _close(s["upper"], -2.0 * r["lower"], 2 * R)
295
+
296
+
297
+ @pytest.mark.parametrize("seed", range(5))
298
+ def test_permutation_invariance(seed):
299
+ rng = np.random.default_rng(500 + seed)
300
+ k = int(rng.integers(3, 15))
301
+ v = rng.uniform(size=k)
302
+ x = rng.multinomial(int(rng.integers(0, 300)), rng.dirichlet(np.ones(k)))
303
+ r = gaffke_ci(x, v, 0.01)
304
+ perm = rng.permutation(k)
305
+ s = gaffke_ci(x[perm], v[perm], 0.01)
306
+ assert s["lower"] == r["lower"] and s["upper"] == r["upper"]
307
+
308
+
309
+ @pytest.mark.parametrize("seed", range(5))
310
+ def test_split_category_with_equal_value(seed):
311
+ """Two categories with the same value act as one (Dirichlet aggregation)."""
312
+ rng = np.random.default_rng(600 + seed)
313
+ k = int(rng.integers(3, 10))
314
+ v = rng.uniform(size=k)
315
+ x = rng.multinomial(int(rng.integers(1, 300)), rng.dirichlet(np.ones(k)))
316
+ j = int(rng.integers(k))
317
+ part = int(rng.integers(0, x[j] + 1))
318
+ x2 = np.append(x, part)
319
+ x2[j] -= part
320
+ v2 = np.append(v, v[j])
321
+ r, s = gaffke_ci(x, v, 0.05), gaffke_ci(x2, v2, 0.05)
322
+ assert s == r
323
+
324
+
325
+ # ── Monotonicity ─────────────────────────────────────────────────────────────
326
+
327
+
328
+ @pytest.mark.parametrize("seed", range(4))
329
+ def test_monotone_in_alpha(seed):
330
+ rng = np.random.default_rng(700 + seed)
331
+ k = int(rng.integers(3, 12))
332
+ v = rng.uniform(size=k)
333
+ x = rng.multinomial(int(10 ** rng.uniform(0, 5)), rng.dirichlet(np.ones(k)))
334
+ alphas = [1e-12, 1e-8, 1e-6, 1e-4, 1e-3, 0.01, 0.05, 0.1, 0.2, 0.5, 0.9, 0.999]
335
+ rs = [gaffke_ci(x, v, al) for al in alphas]
336
+ lo = [r["lower"] for r in rs]
337
+ hi = [r["upper"] for r in rs]
338
+ assert all(b >= a for a, b in zip(lo, lo[1:]))
339
+ assert all(b <= a for a, b in zip(hi, hi[1:]))
340
+ assert all(a <= b for a, b in zip(lo, hi))
341
+ assert all(v.min() <= t <= v.max() for t in lo + hi)
342
+
343
+
344
+ @pytest.mark.parametrize("seed", range(4))
345
+ def test_monotone_in_counts(seed):
346
+ """Moving one count to a category with a larger value moves both endpoints up."""
347
+ rng = np.random.default_rng(800 + seed)
348
+ k = int(rng.integers(3, 10))
349
+ v = np.sort(rng.uniform(size=k))
350
+ x = rng.multinomial(int(rng.integers(2, 200)), rng.dirichlet(np.ones(k)))
351
+ r = gaffke_ci(x, v)
352
+ for i in range(k - 1):
353
+ if x[i] == 0:
354
+ continue
355
+ x2 = x.copy()
356
+ x2[i] -= 1
357
+ x2[i + 1] += 1
358
+ s = gaffke_ci(x2, v)
359
+ assert s["lower"] >= r["lower"] - 1e-12
360
+ assert s["upper"] >= r["upper"] - 1e-12
361
+
362
+
363
+ # ── Edge cases ───────────────────────────────────────────────────────────────
364
+
365
+
366
+ def test_no_data_gives_full_range():
367
+ assert gaffke_ci([0, 0, 0, 0], [1, 2, 3, 4]) == {"lower": 1.0, "upper": 4.0}
368
+
369
+
370
+ def test_single_category():
371
+ assert gaffke_ci([5], [2.5]) == {"lower": 2.5, "upper": 2.5}
372
+ assert gaffke_ci([0], [2.5]) == {"lower": 2.5, "upper": 2.5}
373
+
374
+
375
+ def test_all_values_equal():
376
+ assert gaffke_ci([3, 4, 5], [7.0, 7.0, 7.0]) == {"lower": 7.0, "upper": 7.0}
377
+
378
+
379
+ def test_one_observation():
380
+ # x = e_2: lower is a quantile of Dir(1, 1, 0) -> Beta; upper of Dir(0, 1, 1)
381
+ r = gaffke_ci([0, 1, 0], [0.0, 0.5, 1.0], 0.1)
382
+ assert r["lower"] == pytest.approx(0.5 * 0.05, rel=1e-12) # Uniform on [0, 0.5]
383
+ assert r["upper"] == pytest.approx(1.0 - 0.5 * 0.05, rel=1e-12)
384
+
385
+
386
+ def test_all_mass_on_one_inner_category():
387
+ n = 50
388
+ r = gaffke_ci([0, n, 0], [0.0, 0.5, 1.0], 0.05)
389
+ # lower: 0.5 * B, B ~ Beta(n, 1), quantile 0.025 is 0.025^(1/n)
390
+ assert r["lower"] == pytest.approx(0.5 * 0.025 ** (1 / n), rel=1e-12)
391
+ assert r["upper"] == pytest.approx(1.0 - 0.5 * 0.025 ** (1 / n), rel=1e-12)
392
+
393
+
394
+ def test_ties_at_the_extremes():
395
+ r = gaffke_ci([2, 3, 4, 1], [0.0, 0.0, 1.0, 1.0], 0.05)
396
+ s = gaffke_ci([5, 5], [0.0, 1.0], 0.05)
397
+ assert r == s
398
+
399
+
400
+ @pytest.mark.parametrize("n", [10**7, 10**9, 10**12])
401
+ def test_huge_n(n):
402
+ v = np.array([0.0, 0.2, 0.7, 1.0])
403
+ p = np.array([0.1, 0.4, 0.3, 0.2])
404
+ x = np.round(n * p)
405
+ r = gaffke_ci(x, v, 1e-6)
406
+ mu = float(p @ v)
407
+ sd = math.sqrt(float(p @ (v - mu) ** 2) / n)
408
+ assert r["lower"] < mu < r["upper"]
409
+ # normal limit: half width about 4.89 sd
410
+ assert (mu - r["lower"]) / sd == pytest.approx(4.89, rel=0.02)
411
+ assert (r["upper"] - mu) / sd == pytest.approx(4.89, rel=0.02)
412
+
413
+
414
+ @pytest.mark.parametrize("alpha", [1e-15, 1e-10, 0.5, 0.999])
415
+ def test_extreme_alpha(alpha):
416
+ x, v = [3, 0, 5, 2, 0, 1], [0.1, 0.3, 0.35, 0.6, 0.9, 1.0]
417
+ r = gaffke_ci(x, v, alpha)
418
+ assert 0.1 <= r["lower"] <= r["upper"] <= 1.0
419
+ a_lo = np.array(x, float)
420
+ a_lo[0] += 1
421
+ assert dirichlet_sum_cdf(a_lo, v, r["lower"]) == pytest.approx(alpha / 2, rel=1e-9)
422
+ a_hi = np.array(x, float)
423
+ a_hi[-1] += 1
424
+ assert dirichlet_sum_sf(a_hi, v, r["upper"]) == pytest.approx(alpha / 2, rel=1e-9)
425
+
426
+
427
+ def test_invalid_input():
428
+ with pytest.raises(ValueError):
429
+ gaffke_ci([1, 2], [1.0, 2.0, 3.0])
430
+ with pytest.raises(ValueError):
431
+ gaffke_ci([1, -2, 3], [1.0, 2.0, 3.0])
432
+ with pytest.raises(ValueError):
433
+ gaffke_ci([1, 2], [1.0, np.nan])
434
+ with pytest.raises(ValueError):
435
+ gaffke_ci([1, 2], [1.0, 2.0], alpha=0.0)
436
+
437
+
438
+ # ── Coverage by exact enumeration ────────────────────────────────────────────
439
+
440
+
441
+ def _compositions(n, k):
442
+ for c in itertools.combinations(range(n + k - 1), k - 1):
443
+ b = (-1,) + c + (n + k - 1,)
444
+ yield [b[i + 1] - b[i] - 1 for i in range(k)]
445
+
446
+
447
+ def _worst_one_sided_coverage(n, v, alpha, n_grid=60):
448
+ """Minimum over p of P(L <= mu) and of P(U >= mu), k = 3, v = (0, v1, 1).
449
+
450
+ The coverage of L is constant in p on {mu(p) in (L_(j), L_(j+1))}
451
+ except through P_p, so we scan the level sets mu(p) = t for t just
452
+ above and below each endpoint value, along the segment of the
453
+ simplex with that mean.
454
+ """
455
+ X = np.array(list(_compositions(n, 3)))
456
+ ci = [gaffke_ci(x, v, alpha) for x in X]
457
+ L = np.array([c["lower"] for c in ci])
458
+ U = np.array([c["upper"] for c in ci])
459
+ logc = gammaln(n + 1) - gammaln(X + 1).sum(1)
460
+ eps = 1e-9
461
+ mus = np.concatenate([L - eps, L + eps, U - eps, U + eps, np.linspace(0, 1, 41)])
462
+ mus = np.unique(np.clip(mus, 0.0, 1.0))
463
+ worst_lo = worst_hi = 1.0
464
+ v1 = v[1]
465
+ for mu in mus:
466
+ # p = (p0, p1, p2) with p1 v1 + p2 = mu, p0 + p1 + p2 = 1
467
+ p1_max = min(1.0, mu / v1 if v1 > 0 else 1.0, (1 - mu) / (1 - v1) if v1 < 1 else 1.0)
468
+ for p1 in np.linspace(0.0, p1_max, n_grid):
469
+ p2 = mu - p1 * v1
470
+ p0 = 1.0 - p1 - p2
471
+ p = np.clip([p0, p1, p2], 0.0, 1.0)
472
+ pr = np.exp(logc + xlogy(X, p).sum(1))
473
+ worst_lo = min(worst_lo, pr[L <= mu].sum())
474
+ worst_hi = min(worst_hi, pr[U >= mu].sum())
475
+ return worst_lo, worst_hi
476
+
477
+
478
+ @pytest.mark.parametrize("v1", [0.5, 0.1, 0.9])
479
+ @pytest.mark.parametrize("n", [1, 2, 3, 5, 8, 13])
480
+ @pytest.mark.parametrize("alpha", [0.05, 0.2])
481
+ def test_coverage_exact_enumeration(v1, n, alpha):
482
+ v = np.array([0.0, v1, 1.0])
483
+ lo, hi = _worst_one_sided_coverage(n, v, alpha)
484
+ assert lo >= 1 - alpha / 2 - 1e-9
485
+ assert hi >= 1 - alpha / 2 - 1e-9