@numero-uno-jpn/rstats 0.5.0 → 0.6.1

package/dist/htest/pairwise.d.ts

@@ -0,0 +1,64 @@
+import type { GroupLabel } from "./groups.js";
+import { type PAdjustMethod } from "./pAdjust.js";
+import { type Alternative, type Sample } from "./types.js";
+import { type WilcoxTestOptions } from "./wilcoxTest.js";
+/** Result of the pairwise comparisons (R's `pairwise.htest`). */
+export interface PairwiseResult {
+    /** Description of the tests (R's `method`). */
+    method: string;
+    /**
+     * Adjusted p-values as a lower-triangular table: row `r` compares group `rowNames[r]` with each group
+     * `colNames[c]`; entries above the diagonal are `NaN`.
+     */
+    pValue: number[][];
+    /** Labels of the rows (groups 2..k). */
+    rowNames: string[];
+    /** Labels of the columns (groups 1..k-1). */
+    colNames: string[];
+    /** Adjustment method. */
+    pAdjustMethod: PAdjustMethod | string;
+}
+/** Common options of the pairwise comparisons. */
+export interface PairwiseOptions {
+    /** p-value adjustment (see `pAdjust`). Default `"holm"`. */
+    pAdjustMethod?: PAdjustMethod | (string & {});
+    /** Alternative hypothesis for each comparison of row group against column group. Default `"two.sided"`. */
+    alternative?: Alternative | "two" | "l" | "g";
+}
+/** Options for {@link pairwiseTTest}. */
+export interface PairwiseTTestOptions extends PairwiseOptions {
+    /** Pool the standard deviation over all groups. Default `!paired`. */
+    poolSd?: boolean;
+    /** Paired t tests (groups matched by position). Default `false`. */
+    paired?: boolean;
+}
+/**
+ * Pairwise t tests between groups, with adjusted p-values. Equivalent to R's `pairwise.t.test()`.
+ *
+ * @param x Response values.
+ * @param g Group labels, parallel to `x`.
+ */
+export declare function pairwiseTTest(x: Sample, g: readonly GroupLabel[], options?: PairwiseTTestOptions): PairwiseResult;
+/** Options for {@link pairwiseWilcoxTest}: those of the comparisons themselves, as for `wilcoxTest`. */
+export interface PairwiseWilcoxTestOptions extends PairwiseOptions, Omit<WilcoxTestOptions, "alternative" | "confInt"> {
+}
+/**
+ * Pairwise Wilcoxon rank sum (or signed rank, with `paired`) tests between groups, with adjusted p-values. Equivalent
+ * to R's `pairwise.wilcox.test()`. `method` is that of the last comparison, as in R.
+ */
+export declare function pairwiseWilcoxTest(x: Sample, g: readonly GroupLabel[], options?: PairwiseWilcoxTestOptions): PairwiseResult;
+/** Options for {@link pairwisePropTest}. */
+export interface PairwisePropTestOptions {
+    /** p-value adjustment (see `pAdjust`). Default `"holm"`. */
+    pAdjustMethod?: PAdjustMethod | (string & {});
+    /** Continuity correction in each two-group test. Default `true`. */
+    correct?: boolean;
+}
+/**
+ * Pairwise two-group tests of equal proportions, with adjusted p-values. Equivalent to R's `pairwise.prop.test()`.
+ *
+ * @param x Numbers of successes per group.
+ * @param n Numbers of trials per group. Groups with `NaN` in `x` or `n` are dropped (the rows and columns are then
+ *   numbered over the groups kept, as in R).
+ */
+export declare function pairwisePropTest(x: readonly number[], n: readonly number[], options?: PairwisePropTestOptions): PairwiseResult;

package/dist/htest/pairwise.js

@@ -0,0 +1,152 @@
+// Pairwise comparisons between groups with adjusted p-values (R's pairwise.t.test, pairwise.wilcox.test and
+// pairwise.prop.test).
+//
+// Written for rStats.js (no ported code). Every pair of groups (i, j), i after j in the order of the sorted labels,
+// is compared, and the p-values of the lower triangle are adjusted together with pAdjust. The pooled-SD t tests use
+// the standard deviation pooled over all groups, s^2 = sum (n_i - 1) s_i^2 / sum (n_i - 1), with its degrees of
+// freedom; the other comparisons are the two-sample tests themselves.
+import { pt1 } from "../distributions/t.js";
+import { mean, variance } from "../internal/summary.js";
+import { pAdjust } from "./pAdjust.js";
+import { propTest } from "./propTest.js";
+import { tTest } from "./tTest.js";
+import { matchAlternative } from "./types.js";
+import { wilcoxTest } from "./wilcoxTest.js";
+/** Group a sample by labels: levels sorted (numbers numerically, strings in code-unit order), values in input order */
+function byLevel(x, g, dropNaN) {
+    const xs = Array.from(x);
+    if (xs.length !== g.length)
+        throw new RangeError("'x' and 'g' must have the same length");
+    const map = new Map();
+    for (let i = 0; i < xs.length; i++) {
+        const l = g[i];
+        if (typeof l === "number" && Number.isNaN(l))
+            continue;
+        if (dropNaN && Number.isNaN(xs[i]))
+            continue;
+        let arr = map.get(l);
+        if (arr === undefined)
+            map.set(l, (arr = []));
+        arr.push(xs[i]);
+    }
+    const levels = Array.from(map.keys()).sort((a, b) => typeof a === "number" && typeof b === "number" ? a - b : String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0);
+    return { levels, groups: levels.map((l) => map.get(l)) };
+}
+/** Lower-triangular table of compare(i, j) for i > j, adjusted together */
+function table(k, compare, method) {
+    const raw = [];
+    const pos = [];
+    for (let j = 0; j < k - 1; j++) {
+        for (let i = j + 1; i < k; i++) {
+            raw.push(compare(i, j));
+            pos.push([i - 1, j]);
+        }
+    }
+    const adj = pAdjust(raw, method);
+    const out = Array.from({ length: k - 1 }, () => new Array(k - 1).fill(NaN));
+    pos.forEach(([r, c], idx) => (out[r][c] = adj[idx]));
+    return out;
+}
+function result(method, levels, pValue, adjust) {
+    return {
+        method,
+        pValue,
+        rowNames: levels.slice(1).map(String),
+        colNames: levels.slice(0, -1).map(String),
+        pAdjustMethod: adjust,
+    };
+}
+/**
+ * Pairwise t tests between groups, with adjusted p-values. Equivalent to R's `pairwise.t.test()`.
+ *
+ * @param x Response values.
+ * @param g Group labels, parallel to `x`.
+ */
+export function pairwiseTTest(x, g, options = {}) {
+    const paired = options.paired ?? false;
+    const poolSd = options.poolSd ?? !paired;
+    if (paired && poolSd)
+        throw new RangeError("pooling of SD is incompatible with paired tests");
+    const alternative = matchAlternative(options.alternative);
+    const adjust = options.pAdjustMethod ?? "holm";
+    const { levels, groups } = byLevel(x, g, !paired);
+    const k = levels.length;
+    if (k < 2)
+        throw new RangeError("there must be at least two groups");
+    let compare;
+    let method;
+    if (poolSd) {
+        method = "t tests with pooled SD";
+        const n = groups.map((s) => s.length);
+        const means = groups.map((s) => (s.length > 0 ? mean(s) : NaN));
+        let ss = 0;
+        let df = 0;
+        groups.forEach((s) => {
+            if (s.length > 1) {
+                ss += variance(s) * (s.length - 1);
+                df += s.length - 1;
+            }
+        });
+        const sd = Math.sqrt(ss / df);
+        compare = (i, j) => {
+            const t = (means[i] - means[j]) / (sd * Math.sqrt(1 / n[i] + 1 / n[j]));
+            if (alternative === "less")
+                return pt1(t, df, true, false);
+            if (alternative === "greater")
+                return pt1(t, df, false, false);
+            return 2 * pt1(-Math.abs(t), df, true, false);
+        };
+    }
+    else {
+        method = paired ? "paired t tests" : "t tests with non-pooled SD";
+        compare = (i, j) => tTest(groups[i], groups[j], { paired, alternative }).pValue;
+    }
+    return result(method, levels, table(k, compare, adjust), adjust);
+}
+/**
+ * Pairwise Wilcoxon rank sum (or signed rank, with `paired`) tests between groups, with adjusted p-values. Equivalent
+ * to R's `pairwise.wilcox.test()`. `method` is that of the last comparison, as in R.
+ */
+export function pairwiseWilcoxTest(x, g, options = {}) {
+    const { pAdjustMethod, alternative, ...rest } = options;
+    const adjust = pAdjustMethod ?? "holm";
+    const { levels, groups } = byLevel(x, g, !(rest.paired ?? false));
+    const k = levels.length;
+    if (k < 2)
+        throw new RangeError("there must be at least two groups");
+    let method = "";
+    const pv = table(k, (i, j) => {
+        const r = wilcoxTest(groups[i], groups[j], { ...rest, ...(alternative === undefined ? {} : { alternative }) });
+        method = r.method;
+        return r.pValue;
+    }, adjust);
+    return result(method, levels, pv, adjust);
+}
+/**
+ * Pairwise two-group tests of equal proportions, with adjusted p-values. Equivalent to R's `pairwise.prop.test()`.
+ *
+ * @param x Numbers of successes per group.
+ * @param n Numbers of trials per group. Groups with `NaN` in `x` or `n` are dropped (the rows and columns are then
+ *   numbered over the groups kept, as in R).
+ */
+export function pairwisePropTest(x, n, options = {}) {
+    if (x.length !== n.length)
+        throw new RangeError("'x' and 'n' must have the same length");
+    // as in R, groups with a missing count are dropped and the rest numbered 1, 2, ... in their order
+    const xs = [];
+    const ns = [];
+    x.forEach((v, i) => {
+        if (Number.isNaN(v) || Number.isNaN(n[i]))
+            return;
+        xs.push(v);
+        ns.push(n[i]);
+    });
+    const k = xs.length;
+    if (k < 2)
+        throw new RangeError("too few groups");
+    const adjust = options.pAdjustMethod ?? "holm";
+    const correct = options.correct ?? true;
+    const pv = table(k, (i, j) => propTest([xs[i], xs[j]], [ns[i], ns[j]], { correct }).pValue, adjust);
+    const levels = Array.from({ length: k }, (_, i) => i + 1);
+    return result("Pairwise comparison of proportions", levels, pv, adjust);
+}

package/dist/htest/poissonTest.d.ts

@@ -0,0 +1,35 @@
+import { type Alternative, type HTest } from "./types.js";
+/** Options for {@link poissonTest}. */
+export interface PoissonTestOptions {
+    /** Time base(s): one per count, nonnegative. Default `1` (or `[1, 1]`). */
+    T?: number | readonly number[];
+    /** Hypothesized rate, or rate ratio for two samples (nonnegative). Default `1`. */
+    r?: number;
+    /** Alternative hypothesis (unambiguous abbreviations accepted). Default `"two.sided"`. */
+    alternative?: Alternative | "two" | "l" | "g";
+    /** Confidence level of the interval. Default `0.95`. */
+    confLevel?: number;
+}
+/** Result of {@link poissonTest}. */
+export interface PoissonTestResult extends HTest {
+    /** Time base (one sample) or expected first count under the null hypothesis (two samples). */
+    parameter: number;
+    confInt: [number, number];
+    confLevel: number;
+    /** Event rate (one sample) or rate ratio (two samples). */
+    estimate: number;
+    nullValue: number;
+}
+/**
+ * Exact test of a Poisson rate, or comparison of two Poisson rates. Equivalent to R's `poisson.test()`.
+ *
+ * @param x Number of events, or `[count1, count2]` to compare two rates.
+ * @param options See {@link PoissonTestOptions}.
+ *
+ * @example
+ * ```ts
+ * poissonTest(137, { T: 24.19893 }).pValue; // < 2.2e-16 (rate 1 against 5.66)
+ * poissonTest([11, 23], { T: [800, 3011] }).estimate; // rate ratio 1.80
+ * ```
+ */
+export declare function poissonTest(x: number | readonly number[], options?: PoissonTestOptions): PoissonTestResult;

package/dist/htest/poissonTest.js

@@ -0,0 +1,170 @@
+// Exact Poisson tests (R's poisson.test): a rate against a hypothesized value, or the ratio of two rates.
+//
+// Written for rStats.js from the textbook construction and R's documented behaviour. One sample: the two-sided p-value
+// adds the probabilities of all counts no more likely than the observed one (relative slack 1e-7, as in binomTest), the
+// tail on the far side of the mode being located by a search over integers, and the interval is the exact (Garwood
+// 1936) one from gamma quantiles. Two samples: conditionally on the total, the first count is binomial with
+// probability r T1 / (r T1 + T2), so the test is binomTest's and its interval for p maps to the rate ratio through
+// p / (1 - p) T2 / T1.
+import { dpois1, ppois1 } from "../distributions/poisson.js";
+import { qgamma1 } from "../distributions/gamma.js";
+import { binomTest } from "./binomTest.js";
+import { checkConfLevelOpen, matchAlternative } from "./types.js";
+const REL_ERR = 1 + 1e-7;
+function isCount(v) {
+    return Number.isFinite(v) && v >= 0 && Math.abs(v - Math.round(v)) <= 1e-7 * Math.max(1, Math.abs(v));
+}
+/**
+ * Two-sided p-value of the count x under Poisson(m): the total probability of the counts whose probability is at most
+ * (1 + 1e-7) times that of x. The density is unimodal (increasing up to floor(m), decreasing after), so the observed
+ * side contributes the tail through x and the other side the tail beyond the first qualifying count j past the mode,
+ * located by doubling the step away from the mode (right side) and bisecting on integers.
+ */
+function twoSidedP(x, m) {
+    if (m === 0)
+        return x === 0 ? 1 : 0;
+    if (x === m)
+        return 1;
+    const cut = dpois1(x, m, false) * REL_ERR;
+    const qualifies = (i) => dpois1(i, m, false) <= cut;
+    const mode = Math.floor(m);
+    if (x < m) {
+        // smallest j >= start with dpois(j) <= cut; densities decrease from the mode onwards (with m an integer, m - 1
+        // and m are equally likely, so starting at x + 1 picks up m when x = m - 1)
+        const start = Math.max(x + 1, mode);
+        let j = start;
+        if (!qualifies(start)) {
+            let fails = start; // largest count known not to qualify
+            let step = 1;
+            j = start + 1;
+            while (!qualifies(j)) {
+                fails = j;
+                step *= 2;
+                j = start + step;
+            }
+            while (j - fails > 1) {
+                const mid = fails + Math.floor((j - fails) / 2);
+                if (qualifies(mid))
+                    j = mid;
+                else
+                    fails = mid;
+            }
+        }
+        return Math.min(1, ppois1(x, m, true, false) + ppois1(j - 1, m, false, false));
+    }
+    // x > m: largest j <= end with dpois(j) <= cut; densities increase from 0 up to the mode (j = -1 when none does)
+    const end = Math.min(x - 1, mode);
+    let j;
+    if (!qualifies(0))
+        j = -1;
+    else if (qualifies(end))
+        j = end;
+    else {
+        j = 0;
+        let fails = end; // smallest count known not to qualify
+        while (fails - j > 1) {
+            const mid = j + Math.floor((fails - j) / 2);
+            if (qualifies(mid))
+                j = mid;
+            else
+                fails = mid;
+        }
+    }
+    return Math.min(1, ppois1(j, m, true, false) + ppois1(x - 1, m, false, false));
+}
+/**
+ * Exact test of a Poisson rate, or comparison of two Poisson rates. Equivalent to R's `poisson.test()`.
+ *
+ * @param x Number of events, or `[count1, count2]` to compare two rates.
+ * @param options See {@link PoissonTestOptions}.
+ *
+ * @example
+ * ```ts
+ * poissonTest(137, { T: 24.19893 }).pValue; // < 2.2e-16 (rate 1 against 5.66)
+ * poissonTest([11, 23], { T: [800, 3011] }).estimate; // rate ratio 1.80
+ * ```
+ */
+export function poissonTest(x, options = {}) {
+    const xs = typeof x === "number" ? [x] : Array.from(x);
+    if (xs.length < 1 || xs.length > 2)
+        throw new RangeError("incorrect length of 'x'");
+    if (!xs.every(isCount))
+        throw new RangeError("'x' must be finite, nonnegative, and integer");
+    const counts = xs.map(Math.round);
+    const k = counts.length;
+    const Traw = options.T ?? 1;
+    const T = typeof Traw === "number" ? new Array(k).fill(Traw) : Array.from(Traw);
+    if (T.length !== k)
+        throw new RangeError("'x' and 'T' have incompatible length");
+    // as in R, a time base or rate of 0 is accepted (the counts then have mean 0 under the null hypothesis)
+    if (!T.every((t) => Number.isFinite(t) && t >= 0))
+        throw new RangeError("'T' must be nonnegative");
+    const r = options.r ?? 1;
+    if (!(Number.isFinite(r) && r >= 0))
+        throw new RangeError("'r' must be a single positive number");
+    const alternative = matchAlternative(options.alternative);
+    const confLevel = options.confLevel ?? 0.95;
+    checkConfLevelOpen(confLevel);
+    if (k === 2) {
+        const [x1, x2] = counts;
+        const [T1, T2] = T;
+        const n = x1 + x2;
+        // NaN (rejected by binomTest, as in R) when both r T1 and T2 are 0. The [successes, failures] form also takes
+        // a total of 0 (p-value 1, interval [0, 1]), where binomTest(0, 0) is an error as in R
+        const p0 = (r * T1) / (r * T1 + T2);
+        const b = binomTest([x1, x2], { p: p0, alternative, confLevel });
+        const toRatio = (p) => (p / (1 - p)) * (T2 / T1);
+        return {
+            method: "Comparison of Poisson rates",
+            alternative,
+            statistic: x1,
+            statisticName: "count1",
+            // R reports sum(x) r T1 / (T1 + r T2) here (r on the other time base than in the binomial probability)
+            parameter: (n * r * T1) / (T1 + r * T2),
+            parameterName: "expected count1",
+            pValue: b.pValue,
+            confInt: [toRatio(b.confInt[0]), toRatio(b.confInt[1])],
+            confLevel,
+            estimate: x1 / T1 / (x2 / T2),
+            estimateNames: "rate ratio",
+            nullValue: r,
+            nullValueName: "rate ratio",
+        };
+    }
+    const xv = counts[0];
+    const Tv = T[0];
+    const m = r * Tv;
+    let pValue;
+    if (alternative === "less")
+        pValue = ppois1(xv, m, true, false);
+    else if (alternative === "greater")
+        pValue = ppois1(xv - 1, m, false, false);
+    else
+        pValue = twoSidedP(xv, m);
+    const lower = (alpha) => (xv === 0 ? 0 : qgamma1(alpha, xv, 1, true, false));
+    const upper = (alpha) => qgamma1(1 - alpha, xv + 1, 1, true, false);
+    let ci;
+    if (alternative === "less")
+        ci = [0, upper(1 - confLevel)];
+    else if (alternative === "greater")
+        ci = [lower(1 - confLevel), Infinity];
+    else {
+        const alpha = (1 - confLevel) / 2;
+        ci = [lower(alpha), upper(alpha)];
+    }
+    return {
+        method: "Exact Poisson test",
+        alternative,
+        statistic: xv,
+        statisticName: "number of events",
+        parameter: Tv,
+        parameterName: "time base",
+        pValue,
+        confInt: [ci[0] / Tv, ci[1] / Tv],
+        confLevel,
+        estimate: xv / Tv,
+        estimateNames: "event rate",
+        nullValue: r,
+        nullValueName: "event rate",
+    };
+}

package/dist/htest/propTest.d.ts

@@ -0,0 +1,37 @@
+import { type Alternative, type HTest } from "./types.js";
+/** Options for {@link propTest}. */
+export interface PropTestOptions {
+    /** Hypothesized proportion(s), one per group, each strictly between 0 and 1. Default: `0.5` for one group, and
+     *  equality of the proportions for several. */
+    p?: number | readonly number[];
+    /** Alternative hypothesis (one or two groups without `p`; otherwise only `"two.sided"`). Default `"two.sided"`. */
+    alternative?: Alternative | "two" | "l" | "g";
+    /** Confidence level of the interval. Default `0.95`. */
+    confLevel?: number;
+    /** Apply the continuity correction (one or two groups). Default `true`. */
+    correct?: boolean;
+}
+/** Result of {@link propTest}. */
+export interface PropTestResult extends Omit<HTest, "nullValue" | "nullValueName"> {
+    /** Degrees of freedom (`parameterName` is `"df"`). */
+    parameter: number;
+    /** The observed proportion(s). */
+    estimate: number | number[];
+    /** Hypothesized proportion(s), when given or for one group. */
+    nullValue?: number | number[];
+    nullValueName?: string | string[];
+}
+/**
+ * Test of equal or given proportions. Equivalent to R's `prop.test()`.
+ *
+ * @param x Numbers of successes, or a table of rows `[successes, failures]`.
+ * @param n Numbers of trials (omitted, and the options passed in its place, when `x` is a table).
+ * @param options See {@link PropTestOptions}.
+ *
+ * @example
+ * ```ts
+ * propTest([83, 90, 129, 70], [86, 93, 136, 82]).pValue; // equality of four proportions
+ * propTest(15, 20, { p: 0.5 }).confInt;
+ * ```
+ */
+export declare function propTest(x: number | readonly number[] | readonly (readonly number[])[], n?: number | readonly number[] | PropTestOptions, options?: PropTestOptions): PropTestResult;

package/dist/htest/propTest.js

@@ -0,0 +1,164 @@
+// Test of proportions (R's prop.test): one proportion against a hypothesized value, equality of k proportions, or k
+// proportions against given values.
+//
+// Written for rStats.js from the textbook construction and R's documented behaviour (groups with a missing count are
+// dropped; a given p has one value per group before dropping). The statistic is Pearson's chi-squared on the k x 2
+// table of successes and failures, with Yates' continuity correction (|O - E| - c) for k <= 2, where c = 1/2 is
+// reduced so as not to overshoot (to |x - n p| for one sample, and |p1 - p2| / (1/n1 + 1/n2) for two without p; the
+// statistic is then exactly 0). One-sided alternatives use the signed square root of the statistic as a normal
+// deviate. Intervals: the Wilson score interval (Wilson, JASA 22, 1927) with continuity correction for one proportion
+// (Newcombe, Statistics in Medicine 17, 1998, method 4), and the Wald interval with continuity correction for the
+// difference of two.
+import { pgamma1 } from "../distributions/gamma.js";
+import { pnorm, qnorm } from "../distributions/normal.js";
+import { checkConfLevelOpen, matchAlternative } from "./types.js";
+/**
+ * Test of equal or given proportions. Equivalent to R's `prop.test()`.
+ *
+ * @param x Numbers of successes, or a table of rows `[successes, failures]`.
+ * @param n Numbers of trials (omitted, and the options passed in its place, when `x` is a table).
+ * @param options See {@link PropTestOptions}.
+ *
+ * @example
+ * ```ts
+ * propTest([83, 90, 129, 70], [86, 93, 136, 82]).pValue; // equality of four proportions
+ * propTest(15, 20, { p: 0.5 }).confInt;
+ * ```
+ */
+export function propTest(x, n, options = {}) {
+    // ---- inputs: successes and trials per group ----
+    let xs;
+    let ns;
+    let opts = options;
+    if (typeof x !== "number" && x.length > 0 && Array.isArray(x[0])) {
+        const rows = x;
+        if (rows.some((r) => r.length !== 2))
+            throw new RangeError("'x' must have 2 columns");
+        xs = rows.map((r) => r[0]);
+        ns = rows.map((r) => r[0] + r[1]);
+        if (n !== undefined && typeof n === "object" && !Array.isArray(n))
+            opts = n;
+    }
+    else {
+        if (n === undefined || (typeof n === "object" && !Array.isArray(n)))
+            throw new RangeError("'n' must be given");
+        xs = typeof x === "number" ? [x] : Array.from(x);
+        ns = typeof n === "number" ? [n] : Array.from(n);
+    }
+    if (xs.length !== ns.length)
+        throw new RangeError("'x' and 'n' must have the same length");
+    const L = xs.length;
+    const kept = []; // 0-based positions of the groups without missing values
+    for (let i = 0; i < L; i++)
+        if (!Number.isNaN(xs[i]) && !Number.isNaN(ns[i]))
+            kept.push(i);
+    const k = kept.length;
+    if (k < 1)
+        throw new RangeError("not enough data");
+    xs = kept.map((i) => xs[i]);
+    ns = kept.map((i) => ns[i]);
+    if (ns.some((v) => !(v > 0)))
+        throw new RangeError("elements of 'n' must be positive");
+    if (xs.some((v) => !(v >= 0)))
+        throw new RangeError("elements of 'x' must be nonnegative");
+    if (xs.some((v, i) => v > ns[i]))
+        throw new RangeError("elements of 'x' must not be greater than those of 'n'");
+    let p;
+    if (opts.p !== undefined) {
+        const given = typeof opts.p === "number" ? [opts.p] : Array.from(opts.p);
+        if (given.length !== L)
+            throw new RangeError("'p' must have the same length as 'x' and 'n'");
+        p = kept.map((i) => given[i]);
+        if (p.some((v) => !(v > 0 && v < 1)))
+            throw new RangeError("elements of 'p' must be in (0,1)");
+    }
+    const pGiven = p !== undefined;
+    if (k === 1 && p === undefined)
+        p = [0.5];
+    const confLevel = opts.confLevel ?? 0.95;
+    checkConfLevelOpen(confLevel);
+    let alternative = matchAlternative(opts.alternative);
+    if (k > 2 || (k === 2 && pGiven))
+        alternative = "two.sided";
+    const phat = xs.map((v, i) => v / ns[i]);
+    const delta = k === 2 ? phat[0] - phat[1] : 0;
+    const invSum = k === 2 ? 1 / ns[0] + 1 / ns[1] : 0;
+    // ---- continuity correction, reduced so as not to overshoot |O - E| ----
+    let yates = (opts.correct ?? true) && k <= 2 ? 0.5 : 0;
+    let capped = false;
+    if (yates > 0 && k === 1) {
+        const gap = Math.abs(xs[0] - ns[0] * p[0]);
+        if (gap <= yates)
+            [yates, capped] = [gap, true];
+    }
+    else if (yates > 0 && k === 2 && !pGiven) {
+        const gap = Math.abs(delta) / invSum;
+        if (gap <= yates)
+            [yates, capped] = [gap, true];
+    }
+    // ---- Pearson's chi-squared on the k x 2 table of successes and failures ----
+    const pooled = xs.reduce((a, b) => a + b, 0) / ns.reduce((a, b) => a + b, 0);
+    let statistic = 0;
+    if (!capped) {
+        for (let i = 0; i < k; i++) {
+            const pi = p?.[i] ?? pooled;
+            const e1 = ns[i] * pi;
+            const e2 = ns[i] * (1 - pi);
+            statistic += (Math.abs(xs[i] - e1) - yates) ** 2 / e1;
+            statistic += (Math.abs(ns[i] - xs[i] - e2) - yates) ** 2 / e2;
+        }
+    }
+    const df = p !== undefined ? k : k - 1;
+    let pValue;
+    if (alternative === "two.sided")
+        pValue = pgamma1(statistic, df / 2, 2, false, false);
+    else {
+        const sign = Math.sign(k === 1 ? phat[0] - p[0] : delta);
+        pValue = pnorm(sign * Math.sqrt(statistic), { lowerTail: alternative === "less" });
+    }
+    // ---- confidence interval ----
+    let confInt;
+    if (k === 1 || (k === 2 && !pGiven)) {
+        const z = qnorm(alternative === "two.sided" ? (1 + confLevel) / 2 : confLevel);
+        if (k === 1) {
+            const nn = ns[0];
+            const z2 = z * z;
+            // Wilson score bound for the shifted proportion pc (Newcombe 1998, method 4)
+            const wilson = (pc, sgn) => (pc + z2 / (2 * nn) + sgn * z * Math.sqrt((pc * (1 - pc)) / nn + z2 / (4 * nn * nn))) / (1 + z2 / nn);
+            const pUp = phat[0] + yates / nn;
+            const pLo = phat[0] - yates / nn;
+            const upper = Math.min(1, Math.max(0, pUp >= 1 ? 1 : wilson(pUp, 1)));
+            const lower = Math.min(1, Math.max(0, pLo <= 0 ? 0 : wilson(pLo, -1)));
+            confInt = alternative === "two.sided" ? [lower, upper] : alternative === "greater" ? [lower, 1] : [0, upper];
+        }
+        else {
+            const se = Math.sqrt(phat.reduce((acc, v, i) => acc + (v * (1 - v)) / ns[i], 0));
+            const w = z * se + yates * invSum;
+            const lower = Math.max(-1, delta - w);
+            const upper = Math.min(1, delta + w);
+            confInt = alternative === "two.sided" ? [lower, upper] : alternative === "greater" ? [lower, 1] : [-1, upper];
+        }
+    }
+    const names = k === 1 ? "p" : kept.map((i) => `prop ${i + 1}`);
+    const kind = k === 1 ? "1-sample proportions test" : `${k}-sample test for ${pGiven ? "given proportions" : "equality of proportions"}`;
+    const result = {
+        method: `${kind} ${yates !== 0 ? "with" : "without"} continuity correction`,
+        alternative,
+        statistic,
+        statisticName: "X-squared",
+        parameter: df,
+        parameterName: "df",
+        pValue,
+        estimate: k === 1 ? phat[0] : phat,
+        estimateNames: names,
+    };
+    if (p !== undefined) {
+        result.nullValue = k === 1 ? p[0] : p;
+        result.nullValueName = names;
+    }
+    if (confInt !== undefined) {
+        result.confInt = confInt;
+        result.confLevel = confLevel;
+    }
+    return result;
+}

package/dist/htest/rankTests.d.ts

@@ -0,0 +1,52 @@
+import { type GroupLabel } from "./groups.js";
+import { type Alternative, type HTest, type Sample } from "./types.js";
+/** Result of a k-sample test with a chi-squared statistic. Has no `alternative`, as R returns none. */
+export interface ChisqStatTestResult extends Omit<HTest, "alternative"> {
+    /** Degrees of freedom (`parameterName` is `"df"`). */
+    parameter: number;
+}
+/**
+ * Kruskal-Wallis rank sum test. Equivalent to R's `kruskal.test()`.
+ *
+ * @param x An array of samples (each with at least one non-missing value, as R requires), or one sample with group
+ *   labels `g`.
+ * @param g Group labels, parallel to `x`.
+ */
+export declare function kruskalTest(x: Sample | readonly Sample[], g?: readonly GroupLabel[]): ChisqStatTestResult;
+/**
+ * Friedman rank sum test for an unreplicated complete block design. Equivalent to R's `friedman.test()` with a
+ * matrix.
+ *
+ * @param y Blocks as rows, treatments as columns. Rows with a missing value are dropped.
+ */
+export declare function friedmanTest(y: readonly (readonly number[])[]): ChisqStatTestResult;
+/** Result of {@link quadeTest}: an F statistic with two degrees of freedom. */
+export interface QuadeTestResult extends Omit<HTest, "alternative" | "parameter" | "parameterName"> {
+    /** `[num df, denom df]`. */
+    parameter: [number, number];
+    parameterName: [string, string];
+}
+/**
+ * Quade test for an unreplicated complete block design. Equivalent to R's `quade.test()` with a matrix.
+ *
+ * @param y Blocks as rows, treatments as columns. Rows with a missing value are dropped.
+ */
+export declare function quadeTest(y: readonly (readonly number[])[]): QuadeTestResult;
+/**
+ * Fligner-Killeen (median) test of homogeneity of variances. Equivalent to R's `fligner.test()`.
+ *
+ * @param x An array of samples (each with at least one non-missing value, as R requires), or one sample with group
+ *   labels `g`.
+ * @param g Group labels, parallel to `x`.
+ */
+export declare function flignerTest(x: Sample | readonly Sample[], g?: readonly GroupLabel[]): ChisqStatTestResult;
+/** Options for {@link moodTest}. */
+export interface MoodTestOptions {
+    /** Alternative hypothesis (unambiguous abbreviations accepted). Default `"two.sided"`. */
+    alternative?: Alternative | "two" | "l" | "g";
+}
+/**
+ * Mood's two-sample test of scale. Equivalent to R's `mood.test()`. `NaN` values are dropped; ties get the average
+ * of the scores of their positions.
+ */
+export declare function moodTest(x: Sample, y: Sample, options?: MoodTestOptions): HTest;