accuracy-claim-kit 0.0.0-stage → 0.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.
@@ -0,0 +1,141 @@
1
+ import { MAX_LABEL_LENGTH } from './text.js';
2
+ import { assertKnownKeys, assertPlainObject, readCount, readLength, requireRecord } from './validate.js';
3
+ /** Most distinct labels in one set of pairs. Agreement is about a handful of categories; this only keeps the label table from growing without bound. */
4
+ export const MAX_DISTINCT_LABELS = 1_000_000;
5
+ function readLabel(value, where) {
6
+ if (typeof value === 'string') {
7
+ // Equal-length strings over 16,383 characters collide in V8's Map hashing and make the tally quadratic.
8
+ if (value.length > MAX_LABEL_LENGTH) {
9
+ throw new RangeError(`${where} must be at most ${String(MAX_LABEL_LENGTH)} characters`);
10
+ }
11
+ return value;
12
+ }
13
+ if (typeof value === 'boolean')
14
+ return value;
15
+ if (typeof value === 'number') {
16
+ if (!Number.isFinite(value)) {
17
+ throw new RangeError(`${where} must be a finite number when numeric, got ${String(value)}`);
18
+ }
19
+ return value + 0; // -0 and 0 are the same label
20
+ }
21
+ throw new TypeError(`${where} must be a string, number or boolean`);
22
+ }
23
+ /** One indexed pass; every array element and tuple slot is read exactly once. */
24
+ function tally(pairs) {
25
+ if (!Array.isArray(pairs)) {
26
+ throw new TypeError('pairs must be an array of [labelA, labelB] pairs');
27
+ }
28
+ const length = readLength(pairs.length, 'pairs');
29
+ const byLabel = new Map();
30
+ let agreements = 0;
31
+ for (let i = 0; i < length; i++) {
32
+ const pair = pairs[i];
33
+ if (!Array.isArray(pair)) {
34
+ throw new TypeError(`pairs[${i}] must be a [labelA, labelB] array`);
35
+ }
36
+ const slots = pair;
37
+ if (readLength(slots.length, `pairs[${i}]`) !== 2) {
38
+ throw new RangeError(`pairs[${i}] must have exactly 2 labels`);
39
+ }
40
+ const a = readLabel(slots[0], `pairs[${i}][0]`);
41
+ const b = readLabel(slots[1], `pairs[${i}][1]`);
42
+ if (a === b)
43
+ agreements += 1;
44
+ const ca = byLabel.get(a);
45
+ if (ca === undefined)
46
+ byLabel.set(a, [1, 0]);
47
+ else
48
+ ca[0] += 1;
49
+ const cb = byLabel.get(b);
50
+ if (cb === undefined)
51
+ byLabel.set(b, [0, 1]);
52
+ else
53
+ cb[1] += 1;
54
+ if (byLabel.size > MAX_DISTINCT_LABELS) {
55
+ // before V8's own limit on a Map (about 16.7 million entries) turns this into a bare 'Map maximum size exceeded'
56
+ throw new RangeError(`pairs have more than ${String(MAX_DISTINCT_LABELS)} distinct labels; agreement is for a small set of categories`);
57
+ }
58
+ }
59
+ return { n: length, agreements, byLabel };
60
+ }
61
+ function undefinedResult(statistic, t, reason, categories) {
62
+ return { statistic, status: 'undefined', value: null, reason, n: t.n, agreements: t.agreements, categories };
63
+ }
64
+ function definedResult(statistic, t, value, categories) {
65
+ // Guard against a stray -0 and keep the range honest after the final division.
66
+ const v = Math.max(-1, Math.min(1, value)) + 0;
67
+ return { statistic, status: 'defined', value: v, n: t.n, agreements: t.agreements, categories };
68
+ }
69
+ /**
70
+ * Share of pairs where the two raters gave the same label: agreements / n.
71
+ * With no pairs the result is `undefined` with reason "no-pairs".
72
+ * Throws TypeError / RangeError for malformed pairs.
73
+ */
74
+ export function percentAgreement(pairs) {
75
+ const t = tally(pairs);
76
+ if (t.n === 0)
77
+ return undefinedResult('percent-agreement', t, 'no-pairs', 0);
78
+ return definedResult('percent-agreement', t, t.agreements / t.n, t.byLabel.size);
79
+ }
80
+ /**
81
+ * Cohen's kappa for two raters: (po - pe) / (1 - pe), with pe the chance
82
+ * agreement implied by each rater's own label frequencies. Computed from
83
+ * integer counts (BigInt), so there is no cancellation error.
84
+ * Undefined when pe is exactly 1, or when there are no pairs.
85
+ */
86
+ export function cohenKappa(pairs) {
87
+ const t = tally(pairs);
88
+ const categories = t.byLabel.size;
89
+ if (t.n === 0)
90
+ return undefinedResult('cohen-kappa', t, 'no-pairs', 0);
91
+ const n = BigInt(t.n);
92
+ let sumAB = 0n;
93
+ for (const [a, b] of t.byLabel.values())
94
+ sumAB += BigInt(a) * BigInt(b);
95
+ const den = n * n - sumAB; // n^2 (1 - pe)
96
+ if (den === 0n)
97
+ return undefinedResult('cohen-kappa', t, 'expected-agreement-is-1', categories);
98
+ const num = n * BigInt(t.agreements) - sumAB; // n^2 (po - pe)
99
+ return definedResult('cohen-kappa', t, Number(num) / Number(den), categories);
100
+ }
101
+ /**
102
+ * Gwet's AC1 for two raters: (po - pe) / (1 - pe) with
103
+ * pe = sum_k pi_k (1 - pi_k) / (Q - 1) and pi_k the mean share of label k
104
+ * across both raters. Computed from integer counts (BigInt).
105
+ * Undefined with fewer than two categories (Q < 2) or no pairs.
106
+ * Throws RangeError if options.categories is below the number of labels seen.
107
+ */
108
+ export function gwetAC1(pairs, options) {
109
+ if (options !== undefined) {
110
+ const record = requireRecord(options, 'options');
111
+ assertPlainObject(record, 'options');
112
+ assertKnownKeys(record, ['categories'], 'options');
113
+ }
114
+ const declared = options === undefined ? undefined : options.categories;
115
+ const t = tally(pairs);
116
+ const seen = t.byLabel.size;
117
+ let q = seen;
118
+ if (declared !== undefined) {
119
+ q = readCount(declared, 'options.categories', 1);
120
+ if (q < seen) {
121
+ throw new RangeError(`options.categories (${String(q)}) is below the ${String(seen)} labels seen`);
122
+ }
123
+ }
124
+ if (t.n === 0)
125
+ return undefinedResult('gwet-ac1', t, 'no-pairs', q);
126
+ if (q < 2)
127
+ return undefinedResult('gwet-ac1', t, 'single-category', q);
128
+ const n = BigInt(t.n);
129
+ const qm1 = BigInt(q - 1);
130
+ let s = 0n; // sum_k c_k (2n - c_k), c_k = count of k across both raters
131
+ for (const [a, b] of t.byLabel.values()) {
132
+ const c = BigInt(a + b);
133
+ s += c * (2n * n - c);
134
+ }
135
+ const den = 4n * n * n * qm1 - s;
136
+ if (den <= 0n)
137
+ return undefinedResult('gwet-ac1', t, 'single-category', q);
138
+ const num = 4n * n * BigInt(t.agreements) * qm1 - s;
139
+ return definedResult('gwet-ac1', t, Number(num) / Number(den), q);
140
+ }
141
+ //# sourceMappingURL=agreement.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agreement.js","sourceRoot":"","sources":["../src/agreement.ts"],"names":[],"mappings":"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","sourcesContent":["import { MAX_LABEL_LENGTH } from './text.js'\nimport { assertKnownKeys, assertPlainObject, readCount, readLength, requireRecord } from './validate.js'\n\n/** A categorical label. Compared exactly: 1 and \"1\" are different labels. */\nexport type Label = string | number | boolean\n\nexport type AgreementStatistic = 'percent-agreement' | 'cohen-kappa' | 'gwet-ac1'\n\nexport type UndefinedAgreementReason =\n /** The list of pairs was empty. */\n | 'no-pairs'\n /** Cohen's kappa: chance agreement is exactly 1 (both raters used one and the same single label for every item). */\n | 'expected-agreement-is-1'\n /** Gwet's AC1: fewer than two categories, so the chance model has nothing to spread over. */\n | 'single-category'\n\ninterface AgreementBase {\n statistic: AgreementStatistic\n /** Number of pairs used. */\n n: number\n /** Pairs where the two labels are equal. */\n agreements: number\n /** Distinct labels seen across both raters; for gwetAC1 the category count Q actually used. */\n categories: number\n}\n\nexport interface DefinedAgreement extends AgreementBase {\n status: 'defined'\n value: number\n}\n\nexport interface UndefinedAgreement extends AgreementBase {\n status: 'undefined'\n value: null\n reason: UndefinedAgreementReason\n}\n\nexport type AgreementResult = DefinedAgreement | UndefinedAgreement\n\nexport interface GwetOptions {\n /**\n * Number of categories the label scale allows (Q in Gwet's formula), when\n * some categories may be unused in the sample. Must be a whole number at\n * least as large as the number of distinct labels seen. Default: the\n * number of distinct labels seen.\n */\n categories?: number | undefined\n}\n\ninterface Tally {\n n: number\n agreements: number\n /** label -> [count for rater A, count for rater B] */\n byLabel: Map<Label, [number, number]>\n}\n\n/** Most distinct labels in one set of pairs. Agreement is about a handful of categories; this only keeps the label table from growing without bound. */\nexport const MAX_DISTINCT_LABELS = 1_000_000\n\nfunction readLabel(value: unknown, where: string): Label {\n if (typeof value === 'string') {\n // Equal-length strings over 16,383 characters collide in V8's Map hashing and make the tally quadratic.\n if (value.length > MAX_LABEL_LENGTH) {\n throw new RangeError(`${where} must be at most ${String(MAX_LABEL_LENGTH)} characters`)\n }\n return value\n }\n if (typeof value === 'boolean') return value\n if (typeof value === 'number') {\n if (!Number.isFinite(value)) {\n throw new RangeError(`${where} must be a finite number when numeric, got ${String(value)}`)\n }\n return value + 0 // -0 and 0 are the same label\n }\n throw new TypeError(`${where} must be a string, number or boolean`)\n}\n\n/** One indexed pass; every array element and tuple slot is read exactly once. */\nfunction tally(pairs: unknown): Tally {\n if (!Array.isArray(pairs)) {\n throw new TypeError('pairs must be an array of [labelA, labelB] pairs')\n }\n const length = readLength((pairs as unknown[]).length, 'pairs')\n const byLabel = new Map<Label, [number, number]>()\n let agreements = 0\n for (let i = 0; i < length; i++) {\n const pair: unknown = (pairs as unknown[])[i]\n if (!Array.isArray(pair)) {\n throw new TypeError(`pairs[${i}] must be a [labelA, labelB] array`)\n }\n const slots = pair as unknown[]\n if (readLength(slots.length, `pairs[${i}]`) !== 2) {\n throw new RangeError(`pairs[${i}] must have exactly 2 labels`)\n }\n const a = readLabel(slots[0], `pairs[${i}][0]`)\n const b = readLabel(slots[1], `pairs[${i}][1]`)\n if (a === b) agreements += 1\n const ca = byLabel.get(a)\n if (ca === undefined) byLabel.set(a, [1, 0])\n else ca[0] += 1\n const cb = byLabel.get(b)\n if (cb === undefined) byLabel.set(b, [0, 1])\n else cb[1] += 1\n if (byLabel.size > MAX_DISTINCT_LABELS) {\n // before V8's own limit on a Map (about 16.7 million entries) turns this into a bare 'Map maximum size exceeded'\n throw new RangeError(`pairs have more than ${String(MAX_DISTINCT_LABELS)} distinct labels; agreement is for a small set of categories`)\n }\n }\n return { n: length, agreements, byLabel }\n}\n\nfunction undefinedResult(\n statistic: AgreementStatistic,\n t: Tally,\n reason: UndefinedAgreementReason,\n categories: number,\n): UndefinedAgreement {\n return { statistic, status: 'undefined', value: null, reason, n: t.n, agreements: t.agreements, categories }\n}\n\nfunction definedResult(\n statistic: AgreementStatistic,\n t: Tally,\n value: number,\n categories: number,\n): DefinedAgreement {\n // Guard against a stray -0 and keep the range honest after the final division.\n const v = Math.max(-1, Math.min(1, value)) + 0\n return { statistic, status: 'defined', value: v, n: t.n, agreements: t.agreements, categories }\n}\n\n/**\n * Share of pairs where the two raters gave the same label: agreements / n.\n * With no pairs the result is `undefined` with reason \"no-pairs\".\n * Throws TypeError / RangeError for malformed pairs.\n */\nexport function percentAgreement(pairs: readonly (readonly [Label, Label])[]): AgreementResult {\n const t = tally(pairs)\n if (t.n === 0) return undefinedResult('percent-agreement', t, 'no-pairs', 0)\n return definedResult('percent-agreement', t, t.agreements / t.n, t.byLabel.size)\n}\n\n/**\n * Cohen's kappa for two raters: (po - pe) / (1 - pe), with pe the chance\n * agreement implied by each rater's own label frequencies. Computed from\n * integer counts (BigInt), so there is no cancellation error.\n * Undefined when pe is exactly 1, or when there are no pairs.\n */\nexport function cohenKappa(pairs: readonly (readonly [Label, Label])[]): AgreementResult {\n const t = tally(pairs)\n const categories = t.byLabel.size\n if (t.n === 0) return undefinedResult('cohen-kappa', t, 'no-pairs', 0)\n const n = BigInt(t.n)\n let sumAB = 0n\n for (const [a, b] of t.byLabel.values()) sumAB += BigInt(a) * BigInt(b)\n const den = n * n - sumAB // n^2 (1 - pe)\n if (den === 0n) return undefinedResult('cohen-kappa', t, 'expected-agreement-is-1', categories)\n const num = n * BigInt(t.agreements) - sumAB // n^2 (po - pe)\n return definedResult('cohen-kappa', t, Number(num) / Number(den), categories)\n}\n\n/**\n * Gwet's AC1 for two raters: (po - pe) / (1 - pe) with\n * pe = sum_k pi_k (1 - pi_k) / (Q - 1) and pi_k the mean share of label k\n * across both raters. Computed from integer counts (BigInt).\n * Undefined with fewer than two categories (Q < 2) or no pairs.\n * Throws RangeError if options.categories is below the number of labels seen.\n */\nexport function gwetAC1(\n pairs: readonly (readonly [Label, Label])[],\n options?: GwetOptions,\n): AgreementResult {\n if (options !== undefined) {\n const record = requireRecord(options, 'options')\n assertPlainObject(record, 'options')\n assertKnownKeys(record, ['categories'], 'options')\n }\n const declared = options === undefined ? undefined : options.categories\n const t = tally(pairs)\n const seen = t.byLabel.size\n let q = seen\n if (declared !== undefined) {\n q = readCount(declared, 'options.categories', 1)\n if (q < seen) {\n throw new RangeError(`options.categories (${String(q)}) is below the ${String(seen)} labels seen`)\n }\n }\n if (t.n === 0) return undefinedResult('gwet-ac1', t, 'no-pairs', q)\n if (q < 2) return undefinedResult('gwet-ac1', t, 'single-category', q)\n const n = BigInt(t.n)\n const qm1 = BigInt(q - 1)\n let s = 0n // sum_k c_k (2n - c_k), c_k = count of k across both raters\n for (const [a, b] of t.byLabel.values()) {\n const c = BigInt(a + b)\n s += c * (2n * n - c)\n }\n const den = 4n * n * n * qm1 - s\n if (den <= 0n) return undefinedResult('gwet-ac1', t, 'single-category', q)\n const num = 4n * n * BigInt(t.agreements) * qm1 - s\n return definedResult('gwet-ac1', t, Number(num) / Number(den), q)\n}\n"]}
@@ -0,0 +1,36 @@
1
+ import type { AccuracyAssessment, AccuracyClaimInput, AssessOptions } from './types.js';
2
+ /** Smallest sample that gets a verdict unless options.minN says otherwise. */
3
+ export declare const DEFAULT_MIN_N = 30;
4
+ /**
5
+ * Absolute tolerance, as a proportion, when a claim is compared with an
6
+ * interval limit. A claim within this distance of a limit counts as being at
7
+ * the limit, on the claimant's side. It exists only to absorb binary
8
+ * floating-point noise (a claim of exactly 0.98 against a limit that
9
+ * computes to 0.98000000000000001). It is far below the width of any
10
+ * interval met in practice; it can only matter for samples above about 4e12
11
+ * items with a rate within about 1e-12 of 0 or 1, where the interval itself
12
+ * is narrower than the tolerance. A claim of exactly 0 or 1 is absolute and
13
+ * never uses it.
14
+ */
15
+ export declare const COMPARISON_TOLERANCE = 1e-12;
16
+ /**
17
+ * Does this accuracy or error-rate claim have the evidence to carry it?
18
+ *
19
+ * Pure statistics on the counts you pass in. It never judges whether the
20
+ * labels are right and cannot see how the sample was really drawn; it takes
21
+ * your `provenance` and `sampling` declarations at their word and refuses
22
+ * when they do not support a figure.
23
+ *
24
+ * Verdicts:
25
+ * - refused: a precondition failed. This means "cannot tell", not "false".
26
+ * - contradicted: the claim is more favorable than the interval's best end.
27
+ * - overstated: inside the interval but more favorable than the observed
28
+ * rate (or, with options.conservative, than the conservative end), or
29
+ * printed with finer precision than the interval allows.
30
+ * - supported: no more favorable than the conservative end, or an honest
31
+ * report of the observed rate to its printed precision.
32
+ *
33
+ * Malformed input throws (TypeError for a wrong type, RangeError for a wrong
34
+ * value); it never returns a verdict. Every input property is read once.
35
+ */
36
+ export declare function assessAccuracyClaim(input: AccuracyClaimInput, options?: AssessOptions): AccuracyAssessment;