gaffke 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.
- gaffke/__init__.py +28 -0
- gaffke/ci.py +66 -0
- gaffke/dirichlet_sum.py +372 -0
- gaffke-0.1.0.dist-info/METADATA +44 -0
- gaffke-0.1.0.dist-info/RECORD +7 -0
- gaffke-0.1.0.dist-info/WHEEL +4 -0
- gaffke-0.1.0.dist-info/licenses/LICENSE +21 -0
gaffke/__init__.py
ADDED
|
@@ -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
|
+
]
|
gaffke/ci.py
ADDED
|
@@ -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)}
|
gaffke/dirichlet_sum.py
ADDED
|
@@ -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,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.
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
gaffke/__init__.py,sha256=1QfL6ISdk1USAb3qUTRAxkgyL1Ao4EmW2LF5s1_ZWDE,710
|
|
2
|
+
gaffke/ci.py,sha256=SGUURZBtTjBapfFGXo3YcWAKopfoSyXfmkI-kkOdcfo,2364
|
|
3
|
+
gaffke/dirichlet_sum.py,sha256=7WPDu1bVHBAzSTBBMbFgMN3dAIXlUgw9CLHPmdOZm-I,13903
|
|
4
|
+
gaffke-0.1.0.dist-info/METADATA,sha256=OZW4TXftKfi762gZFR7788gIGkRw2ZZhGvHQ31-HJfI,1735
|
|
5
|
+
gaffke-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
6
|
+
gaffke-0.1.0.dist-info/licenses/LICENSE,sha256=VClhDPQfnDYOEtpi0Yg82619vRX84jyGTmuTM9qa978,1070
|
|
7
|
+
gaffke-0.1.0.dist-info/RECORD,,
|
|
@@ -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.
|