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.
@@ -1,5 +1,7 @@
1
- # This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
2
- # For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
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: 20
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: 20
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.0",
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 continuity correction and Singleton's adjustment.",
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
- observed = Number(observed);
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 (confidence <= 0 || confidence >= 1) {
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
- if (Number.isSafeInteger(population)) {
19
- if (population <= 0) {
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
- sample = sample / Math.sqrt(1 - sample / population);
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
- const zScore = normalQuantile(1 - (1 - confidence) / 2);
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 p = observed / sample;
28
- const n = sample;
29
- const z = zScore;
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
- const high = ((p + z * z / (2 * n) + z * Math.sqrt(p * (1 - p) / n + z * z / (4 * n * n))) / (1 + z * z / n));
32
- const low = ((p + z * z / (2 * n) - z * Math.sqrt(p * (1 - p) / n + z * z / (4 * n * n))) / (1 + z * z / n));
33
- const center = ((p + z * z / (2 * n)) / (1 + z * z / n));
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('The probability p must be between 0 and 1');
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 base args', () => {
8
- test('wilson(5, 100)', () => {
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('wilson(-1, 100)', () => {
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('wilson(5, 0)', () => {
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
- test('wilson(5, 100, 227)', () => {
33
- const result = wilson(5, 100, 227);
34
-
35
- assert.deepEqual(result, {
36
- center: 0.050319696641804315,
37
- high: 0.08456089359579015,
38
- low: 0.016078499687818482
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('wilson(5, 100, 0)', () => {
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('wilson(5, 100, 227, 0.9)', () => {
51
- const result = wilson(5, 100, 227, 0.9);
52
-
53
- assert.deepEqual(result, {
54
- center: 0.04657481789797846,
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('wilson(5, 100, 227, 1)', () => {
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 base args', () => {
70
- test('normalQuantile(0.95)', () => {
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('normalQuantile(0.01)', () => {
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('normalQuantile(0.99)', () => {
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('normalQuantile(0)', () => {
179
+ test('`p` = 0 input', () => {
88
180
  const result = normalQuantile(0);
89
181
  assert.strictEqual(result, -Infinity);
90
182
  });
91
183
 
92
- test('normalQuantile(1)', () => {
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('normalQuantile(-1)', () => {
191
+ test('bad `p` < 0 input', () => {
100
192
  assert.throws(() => normalQuantile(-1), {
101
- message: 'The probability p must be between 0 and 1'
193
+ message: 'p must be a decimal between 0 and 1'
102
194
  });
103
195
  });
104
196
 
105
- test('normalQuantile(2)', () => {
197
+ test('bad `p` > 1 input', () => {
106
198
  assert.throws(() => normalQuantile(2), {
107
- message: 'The probability p must be between 0 and 1'
199
+ message: 'p must be a decimal between 0 and 1'
108
200
  });
109
201
  });
110
202
  });