wilson-interval 5.1.0 → 5.1.1
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.
- package/.github/workflows/npm-publish.yml +14 -6
- package/README.md +6 -0
- package/package.json +2 -2
- package/src/index.js +36 -19
- package/src/index.test.js +124 -32
|
@@ -1,5 +1,7 @@
|
|
|
1
|
-
#
|
|
2
|
-
#
|
|
1
|
+
# Runs the tests, then publishes the package to npm when a GitHub release is created.
|
|
2
|
+
# Authenticates with npm trusted publishing (OIDC), so no npm token secret is needed,
|
|
3
|
+
# and npm adds a provenance attestation automatically.
|
|
4
|
+
# See https://docs.npmjs.com/trusted-publishers
|
|
3
5
|
|
|
4
6
|
name: Node.js Package
|
|
5
7
|
|
|
@@ -7,6 +9,9 @@ on:
|
|
|
7
9
|
release:
|
|
8
10
|
types: [created]
|
|
9
11
|
|
|
12
|
+
permissions:
|
|
13
|
+
contents: read
|
|
14
|
+
|
|
10
15
|
jobs:
|
|
11
16
|
build:
|
|
12
17
|
runs-on: ubuntu-latest
|
|
@@ -14,20 +19,23 @@ jobs:
|
|
|
14
19
|
- uses: actions/checkout@v4
|
|
15
20
|
- uses: actions/setup-node@v4
|
|
16
21
|
with:
|
|
17
|
-
node-version:
|
|
22
|
+
node-version: 24
|
|
18
23
|
- run: npm ci
|
|
19
24
|
- run: npm test
|
|
20
25
|
|
|
21
26
|
publish-npm:
|
|
22
27
|
needs: build
|
|
23
28
|
runs-on: ubuntu-latest
|
|
29
|
+
permissions:
|
|
30
|
+
contents: read
|
|
31
|
+
id-token: write # lets npm exchange a GitHub OIDC token for publish rights
|
|
24
32
|
steps:
|
|
25
33
|
- uses: actions/checkout@v4
|
|
26
34
|
- uses: actions/setup-node@v4
|
|
27
35
|
with:
|
|
28
|
-
node-version:
|
|
36
|
+
node-version: 24
|
|
29
37
|
registry-url: https://registry.npmjs.org/
|
|
38
|
+
# Trusted publishing needs npm 11.5.1 or later
|
|
39
|
+
- run: npm install -g npm@latest
|
|
30
40
|
- run: npm ci
|
|
31
41
|
- run: npm publish
|
|
32
|
-
env:
|
|
33
|
-
NODE_AUTH_TOKEN: ${{secrets.npm_token}}
|
package/README.md
CHANGED
|
@@ -69,6 +69,12 @@ Uses a known, finite population size to inform the degree of uncertainty of the
|
|
|
69
69
|
1. Your sample size represents a significant portion of the population.
|
|
70
70
|
2. You have an imperfect original sample, from which you can only verify a subsample. The original sample can serve as a "population" to produce a verification interval to be combined with the first.<sup>[2]</sup>
|
|
71
71
|
|
|
72
|
+
**HOW IT'S CALCULATED:**
|
|
73
|
+
|
|
74
|
+
The observed proportion `p = observed / sample` is unchanged. The sample size used for the interval is divided by ν², where ν = √((N − n) / (N − 1)) is the finite population correction.<sup>[1]</sup> If `sample` equals `population`, the interval collapses to `p`.
|
|
75
|
+
|
|
76
|
+
> **Note:** The worked example in *Coping with imperfect data*<sup>[2]</sup> (5 of 100 from a population of 227, giving 0.0240–0.1011) divides n by ν instead of ν². This module follows the ν² adjustment described in [1], which matches the variance of sampling without replacement, so it returns 0.0264–0.0926 for that example.
|
|
77
|
+
|
|
72
78
|
## Sources
|
|
73
79
|
|
|
74
80
|
<sup>[1]</sup> [Wallis, Sean 2012. *Inferential Statistics — and other animals*. London: Survey of English Usage, UCL.](https://corplingstats.wordpress.com/2012/04/30/inferential-statistics/)
|
package/package.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "wilson-interval",
|
|
3
|
-
"version": "5.1.
|
|
3
|
+
"version": "5.1.1",
|
|
4
4
|
"author": "Erik Fox <eriktfox@gmail.com> (http://erikfox.dev)",
|
|
5
|
-
"description": "Used to calculate the high bound, low bound, and center of a Wilson score interval. Features support for
|
|
5
|
+
"description": "Used to calculate the high bound, low bound, and center of a Wilson score interval. Features support for Singleton's adjustment (finite population correction).",
|
|
6
6
|
"license": "MIT",
|
|
7
7
|
"homepage": "https://github.com/erikfox/wilson-interval",
|
|
8
8
|
"repository": {
|
package/src/index.js
CHANGED
|
@@ -1,36 +1,53 @@
|
|
|
1
1
|
export default function wilson(observed, sample, population = null, confidence = 0.95) {
|
|
2
|
-
|
|
3
|
-
sample = Number(sample);
|
|
4
|
-
confidence = Number(confidence);
|
|
5
|
-
|
|
6
|
-
if (observed < 0) {
|
|
2
|
+
if (!Number.isSafeInteger(observed) || observed < 0) {
|
|
7
3
|
throw new Error('Observed must be a non-negative whole number');
|
|
8
4
|
}
|
|
9
5
|
|
|
10
|
-
if (sample <= 0) {
|
|
6
|
+
if (!Number.isSafeInteger(sample) || sample <= 0) {
|
|
11
7
|
throw new Error('Sample must be a positive whole number');
|
|
12
8
|
}
|
|
13
9
|
|
|
14
|
-
if (
|
|
10
|
+
if (observed > sample) {
|
|
11
|
+
throw new Error('Observed must not exceed sample');
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
if (typeof confidence !== 'number' || Number.isNaN(confidence) || confidence <= 0 || confidence >= 1) {
|
|
15
15
|
throw new Error('Confidence must be a decimal between 0 and 1');
|
|
16
16
|
}
|
|
17
17
|
|
|
18
|
-
|
|
19
|
-
|
|
18
|
+
const p = observed / sample;
|
|
19
|
+
let n = sample;
|
|
20
|
+
|
|
21
|
+
if (population !== null) {
|
|
22
|
+
if (!Number.isSafeInteger(population) || population <= 0) {
|
|
20
23
|
throw new Error('Population must be a positive whole number');
|
|
21
24
|
}
|
|
22
|
-
|
|
25
|
+
if (sample > population) {
|
|
26
|
+
throw new Error('Sample must not exceed population');
|
|
27
|
+
}
|
|
28
|
+
// The whole population was observed, so there is no uncertainty
|
|
29
|
+
if (sample === population) {
|
|
30
|
+
return { high: p, center: p, low: p };
|
|
31
|
+
}
|
|
32
|
+
// Finite population correction: the standard deviation scales by
|
|
33
|
+
// ν = √((N − n) / (N − 1)), the exact hypergeometric factor, which is
|
|
34
|
+
// equivalent to dividing n by ν². p is unchanged.
|
|
35
|
+
// See Wallis (2012), "Inferential statistics — and other animals".
|
|
36
|
+
n = sample * (population - 1) / (population - sample);
|
|
23
37
|
}
|
|
24
38
|
|
|
25
|
-
|
|
39
|
+
// Computed from the lower tail so confidence near 1 keeps its precision
|
|
40
|
+
// (1 − (1 − confidence) / 2 can round to exactly 1 and give z = Infinity)
|
|
41
|
+
const z = -normalQuantile((1 - confidence) / 2);
|
|
26
42
|
|
|
27
|
-
const
|
|
28
|
-
const
|
|
29
|
-
const
|
|
43
|
+
const denominator = 1 + z * z / n;
|
|
44
|
+
const center = (p + z * z / (2 * n)) / denominator;
|
|
45
|
+
const margin = z * Math.sqrt(p * (1 - p) / n + z * z / (4 * n * n)) / denominator;
|
|
30
46
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
const
|
|
47
|
+
// The bounds are exactly 0 at p = 0 and exactly 1 at p = 1; elsewhere, clamp
|
|
48
|
+
// away floating-point drift so that 0 ≤ low ≤ p ≤ high ≤ 1 always holds
|
|
49
|
+
const low = observed === 0 ? 0 : Math.max(0, Math.min(center - margin, p));
|
|
50
|
+
const high = observed === sample ? 1 : Math.min(1, Math.max(center + margin, p));
|
|
34
51
|
|
|
35
52
|
return {
|
|
36
53
|
high,
|
|
@@ -41,8 +58,8 @@ export default function wilson(observed, sample, population = null, confidence =
|
|
|
41
58
|
|
|
42
59
|
// Returns the quantile (inverse CDF) for the standard normal distribution
|
|
43
60
|
export function normalQuantile(p) {
|
|
44
|
-
if (p < 0 || p > 1) {
|
|
45
|
-
throw new Error('
|
|
61
|
+
if (Number.isNaN(p) || p < 0 || p > 1) {
|
|
62
|
+
throw new Error('p must be a decimal between 0 and 1');
|
|
46
63
|
}
|
|
47
64
|
if (p === 0) return -Infinity;
|
|
48
65
|
if (p === 1) return Infinity;
|
package/src/index.test.js
CHANGED
|
@@ -3,9 +3,58 @@ import test from 'node:test';
|
|
|
3
3
|
import assert from 'node:assert';
|
|
4
4
|
import { describe } from 'node:test';
|
|
5
5
|
|
|
6
|
+
// normalQuantile() has ~1e-9 relative error, so compare with a tolerance
|
|
7
|
+
function assertInterval(actual, expected, tolerance = 1e-9) {
|
|
8
|
+
for (const key of ['low', 'center', 'high']) {
|
|
9
|
+
assert.ok(
|
|
10
|
+
Math.abs(actual[key] - expected[key]) < tolerance,
|
|
11
|
+
`${key}: expected ${expected[key]}, got ${actual[key]}`
|
|
12
|
+
);
|
|
13
|
+
}
|
|
14
|
+
assert.ok(actual.low <= actual.center && actual.center <= actual.high, 'low <= center <= high');
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
function assertBounds({ low, center, high }, p) {
|
|
18
|
+
assert.ok(0 <= low, `low ${low} < 0`);
|
|
19
|
+
assert.ok(low <= p && p <= high, `p ${p} not within [${low}, ${high}]`);
|
|
20
|
+
assert.ok(low <= center && center <= high, `center ${center} not within [${low}, ${high}]`);
|
|
21
|
+
assert.ok(high <= 1, `high ${high} > 1`);
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
describe('wilson() bounds', () => {
|
|
25
|
+
test('observed = 0 gives low exactly 0', () => {
|
|
26
|
+
assert.strictEqual(wilson(0, 1e6, 1000001).low, 0);
|
|
27
|
+
assert.strictEqual(wilson(0, 1, 10, 0.99).low, 0);
|
|
28
|
+
});
|
|
29
|
+
|
|
30
|
+
test('observed = sample gives high exactly 1', () => {
|
|
31
|
+
assert.strictEqual(wilson(100, 100, 101).high, 1);
|
|
32
|
+
assert.strictEqual(wilson(1e6, 1e6).high, 1);
|
|
33
|
+
assert.strictEqual(wilson(1, 1, null, 0.99).high, 1);
|
|
34
|
+
});
|
|
35
|
+
|
|
36
|
+
test('0 <= low <= p <= high <= 1 across a grid of inputs', () => {
|
|
37
|
+
const confidences = [0.5, 0.8, 0.9, 0.95, 0.99, 0.999];
|
|
38
|
+
for (let sample = 1; sample <= 120; sample++) {
|
|
39
|
+
for (const population of [null, sample, sample + 1, sample * 2, sample * 50]) {
|
|
40
|
+
for (const confidence of confidences) {
|
|
41
|
+
for (let observed = 0; observed <= sample; observed++) {
|
|
42
|
+
assertBounds(wilson(observed, sample, population, confidence), observed / sample);
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
});
|
|
48
|
+
|
|
49
|
+
test('very large sample stays within bounds', () => {
|
|
50
|
+
const sample = 2 ** 53 - 1;
|
|
51
|
+
assertBounds(wilson(sample - 1, sample), (sample - 1) / sample);
|
|
52
|
+
});
|
|
53
|
+
});
|
|
54
|
+
|
|
6
55
|
describe('wilson()', () => {
|
|
7
|
-
describe('handles
|
|
8
|
-
test('
|
|
56
|
+
describe('handles required args', () => {
|
|
57
|
+
test('good `observed` and `sample` input', () => {
|
|
9
58
|
const result = wilson(5, 100);
|
|
10
59
|
|
|
11
60
|
assert.deepEqual(result, {
|
|
@@ -15,96 +64,139 @@ describe('wilson()', () => {
|
|
|
15
64
|
});
|
|
16
65
|
});
|
|
17
66
|
|
|
18
|
-
test('
|
|
67
|
+
test('bad `observed` = -1 input', () => {
|
|
19
68
|
assert.throws(() => wilson(-1, 100), {
|
|
20
69
|
message: 'Observed must be a non-negative whole number'
|
|
21
70
|
});
|
|
22
71
|
});
|
|
23
72
|
|
|
24
|
-
test('
|
|
73
|
+
test('bad `sample` = 0 input', () => {
|
|
25
74
|
assert.throws(() => wilson(5, 0), {
|
|
26
75
|
message: 'Sample must be a positive whole number'
|
|
27
76
|
});
|
|
28
77
|
});
|
|
78
|
+
|
|
79
|
+
test('bad `observed` > `sample` input', () => {
|
|
80
|
+
assert.throws(() => wilson(11, 10), {
|
|
81
|
+
message: 'Observed must not exceed sample'
|
|
82
|
+
});
|
|
83
|
+
});
|
|
29
84
|
});
|
|
30
85
|
|
|
31
|
-
describe('handles population arg', () => {
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
center: 0.
|
|
37
|
-
high: 0.
|
|
38
|
-
low: 0.
|
|
86
|
+
describe('handles `population` arg', () => {
|
|
87
|
+
// Reference values from an independent Python implementation:
|
|
88
|
+
// p unchanged, effective n' = n / ν², ν² = (N − n) / (N − 1).
|
|
89
|
+
test('good `population` input', () => {
|
|
90
|
+
assertInterval(wilson(5, 100, 227), {
|
|
91
|
+
center: 0.05950886403022134,
|
|
92
|
+
high: 0.0925865290106502,
|
|
93
|
+
low: 0.026431199049792478
|
|
39
94
|
});
|
|
40
95
|
});
|
|
41
96
|
|
|
42
|
-
test('
|
|
97
|
+
test('`population` = `sample` + 1 with one draw is unadjusted', () => {
|
|
98
|
+
// Exact finite-population factor for n = 1 is 1, so n' = n
|
|
99
|
+
assertInterval(wilson(1, 1, 2), wilson(1, 1));
|
|
100
|
+
});
|
|
101
|
+
|
|
102
|
+
test('`sample` = `population` collapses the interval to p', () => {
|
|
103
|
+
assert.deepEqual(wilson(5, 100, 100), { high: 0.05, center: 0.05, low: 0.05 });
|
|
104
|
+
});
|
|
105
|
+
|
|
106
|
+
test('very large `population` matches no population', () => {
|
|
107
|
+
assertInterval(wilson(5, 100, 1e12), wilson(5, 100));
|
|
108
|
+
});
|
|
109
|
+
|
|
110
|
+
test('bad `population` = 0 input', () => {
|
|
43
111
|
assert.throws(() => wilson(5, 100, 0), {
|
|
44
112
|
message: 'Population must be a positive whole number'
|
|
45
113
|
});
|
|
46
114
|
});
|
|
115
|
+
|
|
116
|
+
test('bad `sample` > `population` input', () => {
|
|
117
|
+
assert.throws(() => wilson(5, 100, 50), {
|
|
118
|
+
message: 'Sample must not exceed population'
|
|
119
|
+
});
|
|
120
|
+
});
|
|
47
121
|
});
|
|
48
122
|
|
|
49
|
-
describe('handles confidence arg', () => {
|
|
50
|
-
test('
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
high: 0.0748286439672683,
|
|
56
|
-
low: 0.018320991828688626
|
|
123
|
+
describe('handles `confidence` arg', () => {
|
|
124
|
+
test('good `confidence` input', () => {
|
|
125
|
+
assertInterval(wilson(5, 100, 227, 0.9), {
|
|
126
|
+
center: 0.05673921186382623,
|
|
127
|
+
high: 0.084248814348019,
|
|
128
|
+
low: 0.02922960937963347
|
|
57
129
|
});
|
|
58
130
|
});
|
|
59
131
|
|
|
60
|
-
test('
|
|
132
|
+
test('`confidence` very close to 1 stays finite', () => {
|
|
133
|
+
const result = wilson(5, 100, null, 1 - 1e-16);
|
|
134
|
+
for (const key of ['low', 'center', 'high']) {
|
|
135
|
+
assert.ok(Number.isFinite(result[key]), `${key} is ${result[key]}`);
|
|
136
|
+
}
|
|
137
|
+
assertBounds(result, 0.05);
|
|
138
|
+
});
|
|
139
|
+
|
|
140
|
+
test('bad `confidence` = 1 input', () => {
|
|
61
141
|
assert.throws(() => wilson(5, 100, 227, 1), {
|
|
62
142
|
message: 'Confidence must be a decimal between 0 and 1'
|
|
63
143
|
});
|
|
64
144
|
});
|
|
145
|
+
|
|
146
|
+
test('bad `confidence` = 0 input', () => {
|
|
147
|
+
assert.throws(() => wilson(5, 100, 227, 0), {
|
|
148
|
+
message: 'Confidence must be a decimal between 0 and 1'
|
|
149
|
+
});
|
|
150
|
+
});
|
|
151
|
+
|
|
152
|
+
test('bad `confidence` = "0.9" (string) input', () => {
|
|
153
|
+
assert.throws(() => wilson(5, 100, null, '0.9'), {
|
|
154
|
+
message: 'Confidence must be a decimal between 0 and 1'
|
|
155
|
+
});
|
|
156
|
+
});
|
|
65
157
|
});
|
|
66
158
|
});
|
|
67
159
|
|
|
68
160
|
describe('normalQuantile()', () => {
|
|
69
|
-
describe('handles
|
|
70
|
-
test('
|
|
161
|
+
describe('handles basic usage', () => {
|
|
162
|
+
test('good `p` input', () => {
|
|
71
163
|
const result = normalQuantile(0.95);
|
|
72
164
|
assert.strictEqual(result, 1.644853625133699);
|
|
73
165
|
});
|
|
74
166
|
|
|
75
|
-
test('
|
|
167
|
+
test('low `p` input', () => {
|
|
76
168
|
const result = normalQuantile(0.01);
|
|
77
169
|
assert.strictEqual(result, -2.326347874388028);
|
|
78
170
|
});
|
|
79
171
|
|
|
80
|
-
test('
|
|
172
|
+
test('high `p` input', () => {
|
|
81
173
|
const result = normalQuantile(0.99);
|
|
82
174
|
assert.strictEqual(result, 2.326347874388028);
|
|
83
175
|
});
|
|
84
176
|
});
|
|
85
177
|
|
|
86
178
|
describe('handles edge cases', () => {
|
|
87
|
-
test('
|
|
179
|
+
test('`p` = 0 input', () => {
|
|
88
180
|
const result = normalQuantile(0);
|
|
89
181
|
assert.strictEqual(result, -Infinity);
|
|
90
182
|
});
|
|
91
183
|
|
|
92
|
-
test('
|
|
184
|
+
test('`p` = 1 input', () => {
|
|
93
185
|
const result = normalQuantile(1);
|
|
94
186
|
assert.strictEqual(result, Infinity);
|
|
95
187
|
});
|
|
96
188
|
});
|
|
97
189
|
|
|
98
190
|
describe('throws on invalid args', () => {
|
|
99
|
-
test('
|
|
191
|
+
test('bad `p` < 0 input', () => {
|
|
100
192
|
assert.throws(() => normalQuantile(-1), {
|
|
101
|
-
message: '
|
|
193
|
+
message: 'p must be a decimal between 0 and 1'
|
|
102
194
|
});
|
|
103
195
|
});
|
|
104
196
|
|
|
105
|
-
test('
|
|
197
|
+
test('bad `p` > 1 input', () => {
|
|
106
198
|
assert.throws(() => normalQuantile(2), {
|
|
107
|
-
message: '
|
|
199
|
+
message: 'p must be a decimal between 0 and 1'
|
|
108
200
|
});
|
|
109
201
|
});
|
|
110
202
|
});
|