wilson-interval 6.0.0-rc.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 CHANGED
@@ -1,11 +1,10 @@
1
1
  # Wilson Interval
2
2
 
3
- [![license](https://img.shields.io/github/license/erikfox/wilson-interval.svg)](LICENSE)
3
+ [![CI](https://github.com/erikfox/wilson-interval/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/erikfox/wilson-interval/actions/workflows/ci.yml?query=branch%3Amaster)
4
4
  [![npm](https://img.shields.io/npm/v/wilson-interval.svg)](https://www.npmjs.com/package/wilson-interval)
5
- [![npm downloads](https://img.shields.io/npm/d18m/wilson-interval.svg?colorB=32CD32)](https://www.npmjs.com/package/wilson-interval)
5
+ [![npm downloads](https://img.shields.io/npm/dm/wilson-interval.svg)](https://www.npmjs.com/package/wilson-interval)
6
6
  [![codecov](https://codecov.io/github/erikfox/wilson-interval/graph/badge.svg?token=R0A2KJQWU6)](https://codecov.io/github/erikfox/wilson-interval)
7
- [![Pull Requests Welcome](https://img.shields.io/badge/pull_requests-welcome-FF69B4.svg)](CONTRIBUTING.md)
8
- [![issues](https://img.shields.io/github/issues-raw/erikfox/wilson-interval.svg?colorB=FF69B4)](https://github.com/erikfox/wilson-interval/issues)
7
+ [![license](https://img.shields.io/github/license/erikfox/wilson-interval.svg)](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
- > ![Singleton's adjustment](https://corplingstats.files.wordpress.com/2012/04/popsamp1.png?w=538)
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 same interval as R's `prop.test(x, n, correct = TRUE)`.
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.0-rc.0",
4
- "author": "Erik Fox <eriktfox@gmail.com> (http://erikfox.dev)",
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.com/erikfox/wilson-interval",
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 (((((c[0]*q + c[1])*q + c[2])*q + c[3])*q + c[4])*q + c[5]) /
154
- ((((d[0]*q + d[1])*q + d[2])*q + d[3])*q + 1);
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 -(((((c[0]*q + c[1])*q + c[2])*q + c[3])*q + c[4])*q + c[5]) /
159
- ((((d[0]*q + d[1])*q + d[2])*q + d[3])*q + 1);
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 (((((a[0]*r + a[1])*r + a[2])*r + a[3])*r + a[4])*r + a[5])*q /
165
- (((((b[0]*r + b[1])*r + b[2])*r + b[3])*r + b[4])*r + 1);
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
+ }