wilson-interval 6.0.0 → 6.0.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/README.md +21 -8
- package/package.json +8 -4
- package/src/index.d.ts +3 -6
- package/src/index.js +28 -12
package/README.md
CHANGED
|
@@ -1,11 +1,10 @@
|
|
|
1
1
|
# Wilson Interval
|
|
2
2
|
|
|
3
|
-
[](https://github.com/erikfox/wilson-interval/actions/workflows/ci.yml?query=branch%3Amaster)
|
|
4
4
|
[](https://www.npmjs.com/package/wilson-interval)
|
|
5
|
-
[](https://www.npmjs.com/package/wilson-interval)
|
|
6
6
|
[](https://codecov.io/github/erikfox/wilson-interval)
|
|
7
|
-
[](https://github.com/erikfox/wilson-interval/issues)
|
|
7
|
+
[](LICENSE)
|
|
9
8
|
|
|
10
9
|
Calculates the **low bound**, **center** and **high bound** of a **[Wilson score interval](https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval)** for a binomial proportion, with optional **finite population correction** (Singleton's adjustment) and **continuity correction**.
|
|
11
10
|
|
|
@@ -13,6 +12,8 @@ The low bound is a popular way to rank items by their share of positive votes, a
|
|
|
13
12
|
|
|
14
13
|
No dependencies, ES module only, TypeScript definitions included. Requires Node.js 22 or later.
|
|
15
14
|
|
|
15
|
+
**[Try it in your browser →](https://erikfox.github.io/wilson-interval/)**
|
|
16
|
+
|
|
16
17
|
## Install
|
|
17
18
|
|
|
18
19
|
```sh
|
|
@@ -120,7 +121,10 @@ console.log(ranked.map((item) => `${item.name} ${item.score.toFixed(3)}`));
|
|
|
120
121
|
|
|
121
122
|
Pass `population` when your sample is a significant part of a known, finite population. Observing more of the population leaves less uncertainty, so the interval narrows.
|
|
122
123
|
|
|
123
|
-
>
|
|
124
|
+
<picture>
|
|
125
|
+
<source media="(prefers-color-scheme: dark)" srcset="assets/finite-population-dark.svg">
|
|
126
|
+
<img src="assets/finite-population-light.svg" width="720" alt="Three cases side by side. Left: the sample is the whole population, so the interval around the observed proportion p has zero width. Middle: the sample is a large part of the population, so the interval is narrower. Right: the sample is a tiny part of the population, so the interval is the full Wilson interval.">
|
|
127
|
+
</picture>
|
|
124
128
|
|
|
125
129
|
> Descriptive statistics summarises the sample as if it were the entire population (left), whereas inferential statistics assumes the sample is a tiny subset of the population (right). If the sample is a large part of the population the confidence interval on observations is reduced (middle).<sup>[1]</sup>
|
|
126
130
|
|
|
@@ -145,7 +149,7 @@ console.log(wilson(5, 100, { population: 100 }));
|
|
|
145
149
|
|
|
146
150
|
### Continuity correction
|
|
147
151
|
|
|
148
|
-
The Wilson interval approximates a discrete distribution with a continuous one. The continuity correction compensates for this by computing the lower bound from `p − 1/(2n)` and the upper bound from `p + 1/(2n)` (clamped to [0, 1]), which makes the interval more conservative.<sup>[3][4]</sup> It is the
|
|
152
|
+
The Wilson interval approximates a discrete distribution with a continuous one. The continuity correction compensates for this by computing the lower bound from `p − 1/(2n)` and the upper bound from `p + 1/(2n)` (clamped to [0, 1]), which makes the interval more conservative.<sup>[3][4]</sup> It is the interval R's `prop.test(x, n, correct = TRUE)` reports, except when `observed` is exactly half of `sample` (see [Accuracy](#accuracy)).
|
|
149
153
|
|
|
150
154
|
- `center` is not changed by the correction.
|
|
151
155
|
- With `population`, the bounds use the population-adjusted sample size, and the `1/(2n)` shift uses the original sample size.<sup>[3]</sup> If `sample` equals `population`, the interval still collapses to `p`.
|
|
@@ -170,7 +174,7 @@ Calling v6 with the v5 arguments throws instead of silently returning a differen
|
|
|
170
174
|
wilson() takes an options object as its third argument since v6. Replace wilson(observed, sample, population, confidence) with wilson(observed, sample, { population, confidence }).
|
|
171
175
|
```
|
|
172
176
|
|
|
173
|
-
Other changes in v6:
|
|
177
|
+
Other changes in v6 (see the [changelog](CHANGELOG.md) for every release):
|
|
174
178
|
|
|
175
179
|
- Node.js 22 or later is required.
|
|
176
180
|
- New `continuityCorrection` option.
|
|
@@ -180,7 +184,7 @@ Other changes in v6:
|
|
|
180
184
|
|
|
181
185
|
## Also exported
|
|
182
186
|
|
|
183
|
-
`normalQuantile(p)` returns the quantile (inverse CDF) of the standard normal distribution, which `wilson()` uses for its critical value.
|
|
187
|
+
`normalQuantile(p)` returns the quantile (inverse CDF) of the standard normal distribution, which `wilson()` uses for its critical value. It uses Peter J. Acklam's rational approximation, which has a relative error below 1.15 × 10⁻⁹.<sup>[5]</sup>
|
|
184
188
|
|
|
185
189
|
```js
|
|
186
190
|
import { normalQuantile } from 'wilson-interval';
|
|
@@ -192,6 +196,13 @@ console.log(normalQuantile(0.975));
|
|
|
192
196
|
1.959963986120195
|
|
193
197
|
```
|
|
194
198
|
|
|
199
|
+
## Accuracy
|
|
200
|
+
|
|
201
|
+
- **Independent reference values.** Expected test values are not copied from this module's output. [`scripts/reference.py`](scripts/reference.py) computes them with Python's standard library: it solves the Wilson quadratic directly, takes the critical value from `statistics.NormalDist`, and checks the continuity correction against Newcombe's closed form and the worked examples in his Table I.<sup>[4]</sup> The [`reference` CI job](.github/workflows/ci.yml) fails if [`scripts/reference.json`](scripts/reference.json) is out of sync with the script.
|
|
202
|
+
- **Agrees with R.** Without `population`, the continuity-corrected interval matches R's [`prop.test(x, n, correct = TRUE)`](https://stat.ethz.ch/R-manual/R-devel/library/stats/html/prop.test.html) to about nine significant digits, the accuracy of `normalQuantile`. The one difference: `prop.test` only applies the correction when it doesn't exceed the distance from its null proportion (0.5 by default), so when `observed` is exactly half of `sample` it returns the uncorrected interval and this module doesn't.
|
|
203
|
+
- **100% coverage, enforced.** The [`coverage` CI job](.github/workflows/ci.yml) runs `npm run test:cc`, which fails if line, branch or function coverage drops below 100%.
|
|
204
|
+
- **Published with provenance.** Releases are published to npm from a [GitHub Actions workflow](.github/workflows/npm-publish.yml) using trusted publishing, so each version since 5.1.1 carries a [provenance attestation](https://docs.npmjs.com/generating-provenance-statements) linking it to the commit and workflow run that built it.
|
|
205
|
+
|
|
195
206
|
## Sources
|
|
196
207
|
|
|
197
208
|
<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/)
|
|
@@ -202,5 +213,7 @@ console.log(normalQuantile(0.975));
|
|
|
202
213
|
|
|
203
214
|
<sup>[4]</sup> [Newcombe, Robert G. 1998. *Two-sided confidence intervals for the single proportion: comparison of seven methods*. Statistics in Medicine 17(8): 857–872.](https://doi.org/10.1002/(SICI)1097-0258(19980430)17:8%3C857::AID-SIM777%3E3.0.CO;2-E)
|
|
204
215
|
|
|
216
|
+
<sup>[5]</sup> Acklam, Peter J. Rational approximation of the normal quantile function, originally published at `home.online.no/~pjacklam/notes/invnorm/`, which is no longer online. The algorithm, coefficients and error bound are reproduced in [*Acklam's Algorithm for the Inverse Normal CDF*](https://stackedboxes.org/2017/05/01/acklams-normal-quantile-function/), StackedBoxes.org, 2017.
|
|
217
|
+
|
|
205
218
|
___
|
|
206
219
|
*Special thanks to [Sean Wallis](https://profiles.ucl.ac.uk/21175-sean-wallis), Principal Research Fellow and Deputy Director of the Survey of English Usage, UCL, for his help transcribing equations, and for the blog posts that inspired many of this module's features.*
|
package/package.json
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "wilson-interval",
|
|
3
|
-
"version": "6.0.
|
|
4
|
-
"author": "Erik Fox <eriktfox@gmail.com> (
|
|
3
|
+
"version": "6.0.1",
|
|
4
|
+
"author": "Erik Fox <eriktfox@gmail.com> (https://erikfox.dev)",
|
|
5
5
|
"description": "Wilson score confidence interval for a binomial proportion, with optional finite population and continuity corrections. Zero dependencies, TypeScript types included.",
|
|
6
6
|
"license": "MIT",
|
|
7
|
-
"homepage": "https://github.
|
|
7
|
+
"homepage": "https://erikfox.github.io/wilson-interval/",
|
|
8
8
|
"repository": {
|
|
9
9
|
"type": "git",
|
|
10
10
|
"url": "git+https://github.com/erikfox/wilson-interval.git"
|
|
@@ -33,6 +33,7 @@
|
|
|
33
33
|
"node": ">=22"
|
|
34
34
|
},
|
|
35
35
|
"type": "module",
|
|
36
|
+
"sideEffects": false,
|
|
36
37
|
"main": "./src/index.js",
|
|
37
38
|
"types": "./src/index.d.ts",
|
|
38
39
|
"files": [
|
|
@@ -48,6 +49,9 @@
|
|
|
48
49
|
"scripts": {
|
|
49
50
|
"test": "node --test src/index.test.js",
|
|
50
51
|
"test:types": "npx -y -p typescript@7.0.2 tsc -p test/tsconfig.json",
|
|
51
|
-
"test:cc": "node --test --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=lcov.info src/index.test.js"
|
|
52
|
+
"test:cc": "node --test --experimental-test-coverage --test-coverage-lines=100 --test-coverage-branches=100 --test-coverage-functions=100 --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=lcov.info src/index.test.js",
|
|
53
|
+
"lint": "npx -y @biomejs/biome@2.6.8 ci . --error-on-warnings",
|
|
54
|
+
"format": "npx -y @biomejs/biome@2.6.8 format --write .",
|
|
55
|
+
"build:demo": "rm -rf _site && mkdir _site && cp demo/index.html demo/demo.css demo/demo.js _site/ && cp src/index.js _site/wilson-interval.js"
|
|
52
56
|
}
|
|
53
57
|
}
|
package/src/index.d.ts
CHANGED
|
@@ -48,14 +48,11 @@ export interface WilsonInterval {
|
|
|
48
48
|
*
|
|
49
49
|
* wilson(5, 100, { population: 227, confidence: 0.9 });
|
|
50
50
|
*/
|
|
51
|
-
export default function wilson(
|
|
52
|
-
observed: number,
|
|
53
|
-
sample: number,
|
|
54
|
-
options?: WilsonOptions
|
|
55
|
-
): WilsonInterval;
|
|
51
|
+
export default function wilson(observed: number, sample: number, options?: WilsonOptions): WilsonInterval;
|
|
56
52
|
|
|
57
53
|
/**
|
|
58
|
-
* Quantile (inverse CDF) of the standard normal distribution
|
|
54
|
+
* Quantile (inverse CDF) of the standard normal distribution, computed with
|
|
55
|
+
* Peter J. Acklam's rational approximation (relative error below 1.15e-9).
|
|
59
56
|
*
|
|
60
57
|
* @param p A probability from 0 to 1. Returns `-Infinity` at 0 and `Infinity` at 1.
|
|
61
58
|
* @throws {Error} If `p` is outside [0, 1] or NaN.
|
package/src/index.js
CHANGED
|
@@ -8,6 +8,7 @@ const MIGRATION_ERROR =
|
|
|
8
8
|
export default function wilson(observed, sample, options = {}) {
|
|
9
9
|
// v5 took population and confidence as positional arguments; catch those
|
|
10
10
|
// calls explicitly rather than misreading them
|
|
11
|
+
// biome-ignore lint/complexity/noArguments: counts surplus v5-style arguments without adding a parameter to the signature
|
|
11
12
|
if (arguments.length > 3 || typeof options === 'number' || options === null) {
|
|
12
13
|
throw new Error(MIGRATION_ERROR);
|
|
13
14
|
}
|
|
@@ -62,7 +63,7 @@ export default function wilson(observed, sample, options = {}) {
|
|
|
62
63
|
// ν = √((N − n) / (N − 1)), the exact hypergeometric factor, which is
|
|
63
64
|
// equivalent to dividing n by ν². p is unchanged.
|
|
64
65
|
// See Wallis (2012), "Inferential statistics — and other animals".
|
|
65
|
-
n = sample * (population - 1) / (population - sample);
|
|
66
|
+
n = (sample * (population - 1)) / (population - sample);
|
|
66
67
|
}
|
|
67
68
|
|
|
68
69
|
// Computed from the lower tail so confidence near 1 keeps its precision
|
|
@@ -97,13 +98,18 @@ export default function wilson(observed, sample, options = {}) {
|
|
|
97
98
|
|
|
98
99
|
// Wilson score interval for proportion p with sample size n and critical value z
|
|
99
100
|
function scoreInterval(p, n, z) {
|
|
100
|
-
const denominator = 1 + z * z / n;
|
|
101
|
-
const center = (p + z * z / (2 * n)) / denominator;
|
|
102
|
-
const margin = z * Math.sqrt(p * (1 - p) / n + z * z / (4 * n * n)) / denominator;
|
|
101
|
+
const denominator = 1 + (z * z) / n;
|
|
102
|
+
const center = (p + (z * z) / (2 * n)) / denominator;
|
|
103
|
+
const margin = (z * Math.sqrt((p * (1 - p)) / n + (z * z) / (4 * n * n))) / denominator;
|
|
103
104
|
return { center, low: center - margin, high: center + margin };
|
|
104
105
|
}
|
|
105
106
|
|
|
106
|
-
// Returns the quantile (inverse CDF) for the standard normal distribution
|
|
107
|
+
// Returns the quantile (inverse CDF) for the standard normal distribution,
|
|
108
|
+
// using Peter J. Acklam's rational approximation. Its relative error is below
|
|
109
|
+
// 1.15e-9 over the whole of (0, 1). Acklam's original note
|
|
110
|
+
// (http://home.online.no/~pjacklam/notes/invnorm/) is no longer online; this
|
|
111
|
+
// write-up gives the same algorithm and coefficients:
|
|
112
|
+
// https://stackedboxes.org/2017/05/01/acklams-normal-quantile-function/
|
|
107
113
|
export function normalQuantile(p) {
|
|
108
114
|
if (Number.isNaN(p) || p < 0 || p > 1) {
|
|
109
115
|
throw new Error('p must be a decimal between 0 and 1');
|
|
@@ -112,6 +118,7 @@ export function normalQuantile(p) {
|
|
|
112
118
|
if (p === 1) return Infinity;
|
|
113
119
|
|
|
114
120
|
// Coefficients in rational approximations
|
|
121
|
+
// biome-ignore format: coefficients aligned as published by Acklam
|
|
115
122
|
const a = [
|
|
116
123
|
-3.969683028665376e+01,
|
|
117
124
|
2.209460984245205e+02,
|
|
@@ -120,6 +127,7 @@ export function normalQuantile(p) {
|
|
|
120
127
|
-3.066479806614716e+01,
|
|
121
128
|
2.506628277459239e+00
|
|
122
129
|
];
|
|
130
|
+
// biome-ignore format: coefficients aligned as published by Acklam
|
|
123
131
|
const b = [
|
|
124
132
|
-5.447609879822406e+01,
|
|
125
133
|
1.615858368580409e+02,
|
|
@@ -127,6 +135,7 @@ export function normalQuantile(p) {
|
|
|
127
135
|
6.680131188771972e+01,
|
|
128
136
|
-1.328068155288572e+01
|
|
129
137
|
];
|
|
138
|
+
// biome-ignore format: coefficients aligned as published by Acklam
|
|
130
139
|
const c = [
|
|
131
140
|
-7.784894002430293e-03,
|
|
132
141
|
-3.223964580411365e-01,
|
|
@@ -135,6 +144,7 @@ export function normalQuantile(p) {
|
|
|
135
144
|
4.374664141464968e+00,
|
|
136
145
|
2.938163982698783e+00
|
|
137
146
|
];
|
|
147
|
+
// biome-ignore format: coefficients aligned as published by Acklam
|
|
138
148
|
const d = [
|
|
139
149
|
7.784695709041462e-03,
|
|
140
150
|
3.224671290700398e-01,
|
|
@@ -150,18 +160,24 @@ export function normalQuantile(p) {
|
|
|
150
160
|
if (p < plow) {
|
|
151
161
|
// Rational approximation for lower region
|
|
152
162
|
q = Math.sqrt(-2 * Math.log(p));
|
|
153
|
-
return (
|
|
154
|
-
|
|
163
|
+
return (
|
|
164
|
+
(((((c[0] * q + c[1]) * q + c[2]) * q + c[3]) * q + c[4]) * q + c[5]) /
|
|
165
|
+
((((d[0] * q + d[1]) * q + d[2]) * q + d[3]) * q + 1)
|
|
166
|
+
);
|
|
155
167
|
} else if (phigh < p) {
|
|
156
168
|
// Rational approximation for upper region
|
|
157
169
|
q = Math.sqrt(-2 * Math.log(1 - p));
|
|
158
|
-
return
|
|
159
|
-
|
|
170
|
+
return (
|
|
171
|
+
-(((((c[0] * q + c[1]) * q + c[2]) * q + c[3]) * q + c[4]) * q + c[5]) /
|
|
172
|
+
((((d[0] * q + d[1]) * q + d[2]) * q + d[3]) * q + 1)
|
|
173
|
+
);
|
|
160
174
|
} else {
|
|
161
175
|
// Rational approximation for central region
|
|
162
176
|
q = p - 0.5;
|
|
163
177
|
r = q * q;
|
|
164
|
-
return (
|
|
165
|
-
|
|
178
|
+
return (
|
|
179
|
+
((((((a[0] * r + a[1]) * r + a[2]) * r + a[3]) * r + a[4]) * r + a[5]) * q) /
|
|
180
|
+
(((((b[0] * r + b[1]) * r + b[2]) * r + b[3]) * r + b[4]) * r + 1)
|
|
181
|
+
);
|
|
166
182
|
}
|
|
167
|
-
}
|
|
183
|
+
}
|