@numero-uno-jpn/rstats 0.5.0 → 0.6.1

package/dist/htest/rankTests.js

@@ -0,0 +1,234 @@
+// Rank-based k-sample and two-sample tests: R's kruskal.test, friedman.test, quade.test, fligner.test and mood.test.
+//
+// Written for rStats.js from the published statistics (no ported code), with ties handled by average ranks:
+// - Kruskal and Wallis (JASA 47, 1952): H = (12 / (N (N + 1)) sum R_i^2 / n_i - 3 (N + 1)) / (1 - sum (t^3 - t) /
+//   (N^3 - N)), chi-squared with k - 1 degrees of freedom.
+// - Friedman (JASA 32, 1937), ranks within blocks: 12 sum (R_j - n (k + 1) / 2)^2 / (n k (k + 1) - sum (t^3 - t) /
+//   (k - 1)), chi-squared with k - 1 degrees of freedom.
+// - Quade (JASA 74, 1979), as given by Conover (Practical Nonparametric Statistics, 1999, section 5.8): blocks ranked
+//   by their range, Q_i, S_ij = Q_i (R_ij - (k + 1) / 2), A = sum S_ij^2, B = sum_j (sum_i S_ij)^2 / b,
+//   F = (b - 1) B / (A - B) on (k - 1, (b - 1)(k - 1)) degrees of freedom; when A = B (all treatments tied within
+//   every block's order) the p-value is (1 / k!)^(b - 1), as Conover suggests.
+// - Fligner and Killeen (JASA 71, 1976), centred at the group medians: scores a = qnorm((1 + rank|x| / (N + 1)) / 2),
+//   statistic sum n_i (mean a_i - mean a)^2 / var(a), chi-squared with k - 1 degrees of freedom (the median-centred
+//   form of Conover, Johnson and Johnson, Technometrics 23, 1981).
+// - Mood (Ann. Math. Stat. 25, 1954): scores (i - (N + 1) / 2)^2 by position, averaged over tied positions (Mielke,
+//   Technometrics 9, 1967); the sum over the first sample is standardised with the exact mean and variance of a linear
+//   rank statistic, E = m mean(a), V = m n / (N (N - 1)) sum (a_i - mean(a))^2, and compared with the normal.
+import { pf1 } from "../distributions/f.js";
+import { pgamma1 } from "../distributions/gamma.js";
+import { pnorm, qnorm } from "../distributions/normal.js";
+import { rank, tieCounts, variance } from "../internal/summary.js";
+import { completeRows, median, toGroups } from "./groups.js";
+import { matchAlternative } from "./types.js";
+function chisqResult(method, name, statistic, df) {
+    return {
+        method,
+        statistic,
+        statisticName: name,
+        parameter: df,
+        parameterName: "df",
+        pValue: pgamma1(statistic, df / 2, 2, false, false),
+    };
+}
+function sumTies(x) {
+    let s = 0;
+    for (const t of tieCounts(x))
+        s += t * t * t - t;
+    return s;
+}
+/**
+ * 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 function kruskalTest(x, g) {
+    const groups = toGroups(x, g, "error");
+    const k = groups.length;
+    if (k < 2)
+        throw new RangeError("all observations are in the same group");
+    const all = groups.flat();
+    const n = all.length;
+    const r = rank(all);
+    let stat = 0;
+    let pos = 0;
+    for (const grp of groups) {
+        let s = 0;
+        for (let i = 0; i < grp.length; i++)
+            s += r[pos + i];
+        pos += grp.length;
+        stat += (s * s) / grp.length;
+    }
+    stat = ((12 * stat) / (n * (n + 1)) - 3 * (n + 1)) / (1 - sumTies(all) / (n * n * n - n));
+    return chisqResult("Kruskal-Wallis rank sum test", "Kruskal-Wallis chi-squared", stat, k - 1);
+}
+/**
+ * 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 function friedmanTest(y) {
+    const rows = completeRows(y);
+    const n = rows.length;
+    const k = y[0]?.length ?? 0;
+    // R needs two complete blocks (with one, its matrix of ranks collapses to a vector)
+    if (n < 2 || k < 2)
+        throw new RangeError("'y' must have at least two complete rows and two columns");
+    const colSums = new Array(k).fill(0);
+    let ties = 0;
+    for (const row of rows) {
+        const r = rank(row);
+        for (let j = 0; j < k; j++)
+            colSums[j] += r[j];
+        ties += sumTies(row);
+    }
+    let ss = 0;
+    for (const s of colSums)
+        ss += (s - (n * (k + 1)) / 2) ** 2;
+    const stat = (12 * ss) / (n * k * (k + 1) - ties / (k - 1));
+    return chisqResult("Friedman rank sum test", "Friedman chi-squared", stat, k - 1);
+}
+/**
+ * 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 function quadeTest(y) {
+    const rows = completeRows(y);
+    // as in R, b counts all blocks, including those dropped for a missing value
+    const b = y.length;
+    const k = y[0]?.length ?? 0;
+    if (rows.length < 2 || k < 2)
+        throw new RangeError("'y' must have at least two complete rows and two columns");
+    const q = rank(rows.map((r) => Math.max(...r) - Math.min(...r)));
+    const colS = new Array(k).fill(0);
+    let A = 0;
+    rows.forEach((row, i) => {
+        const r = rank(row);
+        for (let j = 0; j < k; j++) {
+            const s = q[i] * (r[j] - (k + 1) / 2);
+            A += s * s;
+            colS[j] += s;
+        }
+    });
+    let B = 0;
+    for (const s of colS)
+        B += s * s;
+    B /= b;
+    const df1 = k - 1;
+    const df2 = (b - 1) * (k - 1);
+    let statistic;
+    let pValue;
+    let parameter = [df1, df2];
+    if (A === B) {
+        statistic = NaN;
+        parameter = [NaN, NaN];
+        // log-gamma form of (k!)^(1 - b), which overflows directly for large b
+        let lf = 0;
+        for (let i = 2; i <= k; i++)
+            lf += Math.log(i);
+        pValue = Math.exp((1 - b) * lf);
+    }
+    else {
+        statistic = ((b - 1) * B) / (A - B);
+        pValue = pf1(statistic, df1, df2, false, false);
+    }
+    return {
+        method: "Quade test",
+        statistic,
+        statisticName: "Quade F",
+        parameter,
+        parameterName: ["num df", "denom df"],
+        pValue,
+    };
+}
+/**
+ * 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 function flignerTest(x, g) {
+    const groups = toGroups(x, g, "error");
+    const k = groups.length;
+    if (k < 2)
+        throw new RangeError("all observations are in the same group");
+    const centred = groups.flatMap((grp) => {
+        const m = median(grp);
+        return grp.map((v) => Math.abs(v - m));
+    });
+    const n = centred.length;
+    const r = rank(centred);
+    const a = r.map((v) => qnorm((1 + v / (n + 1)) / 2));
+    let total = 0;
+    for (const v of a)
+        total += v;
+    const abar = total / n;
+    // sum n_i (mean a_i - mean a)^2: the form sum S_i^2 / n_i - n mean(a)^2 cancels when the statistic is small
+    let stat = 0;
+    let pos = 0;
+    for (const grp of groups) {
+        let s = 0;
+        for (let i = 0; i < grp.length; i++)
+            s += a[pos + i];
+        pos += grp.length;
+        stat += grp.length * (s / grp.length - abar) ** 2;
+    }
+    stat /= variance(a);
+    return chisqResult("Fligner-Killeen test of homogeneity of variances", "Fligner-Killeen:med chi-squared", stat, k - 1);
+}
+/**
+ * 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 function moodTest(x, y, options = {}) {
+    // as in R, infinite values are dropped along with NaN
+    const xs = Array.from(x).filter(Number.isFinite);
+    const ys = Array.from(y).filter(Number.isFinite);
+    const alternative = matchAlternative(options.alternative);
+    const m = xs.length;
+    const n = ys.length;
+    const N = m + n;
+    if (N < 3)
+        throw new RangeError("not enough observations");
+    const z = xs.concat(ys);
+    // positions in sorted order; tied values share the mean of the scores of their positions
+    const order = Array.from({ length: N }, (_, i) => i).sort((p, q) => z[p] - z[q]);
+    const a = new Array(N);
+    let i = 0;
+    while (i < N) {
+        let j = i;
+        while (j + 1 < N && z[order[j + 1]] === z[order[i]])
+            j++;
+        let s = 0;
+        for (let t = i; t <= j; t++)
+            s += (t + 1 - (N + 1) / 2) ** 2;
+        s /= j - i + 1;
+        for (let t = i; t <= j; t++)
+            a[order[t]] = s;
+        i = j + 1;
+    }
+    let T = 0;
+    for (let t = 0; t < m; t++)
+        T += a[t];
+    let abar = 0;
+    for (const v of a)
+        abar += v;
+    abar /= N;
+    let ss = 0;
+    for (const v of a)
+        ss += (v - abar) ** 2;
+    const E = m * abar;
+    const V = ((m * n) / (N * (N - 1))) * ss;
+    const zstat = (T - E) / Math.sqrt(V);
+    const pValue = alternative === "less"
+        ? pnorm(zstat)
+        : alternative === "greater"
+            ? pnorm(zstat, { lowerTail: false })
+            : 2 * pnorm(-Math.abs(zstat));
+    return { method: "Mood two-sample test of scale", alternative, statistic: zstat, statisticName: "Z", pValue };
+}

package/dist/htest/types.d.ts

@@ -47,3 +47,5 @@ export interface HTest {
 export declare function matchAlternative(a: string | undefined): Alternative;
 /** Validate the confidence level (R's t.test also accepts exactly 0 and 1; with 1 the interval is ±Inf) */
 export declare function checkConfLevel(level: number): void;
+/** Validate the confidence level strictly inside (0, 1), as most of R's tests require */
+export declare function checkConfLevelOpen(level: number): void;

package/dist/htest/types.js

@@ -18,3 +18,9 @@ export function checkConfLevel(level) {
         throw new RangeError("confLevel must be a number between 0 and 1");
     }
 }
+/** Validate the confidence level strictly inside (0, 1), as most of R's tests require */
+export function checkConfLevelOpen(level) {
+    if (!(Number.isFinite(level) && level > 0 && level < 1)) {
+        throw new RangeError("'conf.level' must be a single number between 0 and 1");
+    }
+}

package/dist/htest/varTest.d.ts

@@ -0,0 +1,48 @@
+import { type Alternative, type HTest, type Sample } from "./types.js";
+/** Options for {@link varTest}. */
+export interface VarTestOptions {
+    /** Hypothesized ratio of the variances of `x` and `y`. Default `1`. */
+    ratio?: 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 varTest}. The F distribution has two degrees of freedom, so `parameter` is a pair. */
+export interface VarTestResult extends Omit<HTest, "parameter" | "parameterName"> {
+    /** `[num df, denom df]`. */
+    parameter: [number, number];
+    parameterName: [string, string];
+    confInt: [number, number];
+    confLevel: number;
+    /** Ratio of the sample variances. */
+    estimate: number;
+    nullValue: number;
+}
+/**
+ * F test that the variances of two normal samples have a given ratio. Equivalent to R's `var.test()`. `NaN` values
+ * are dropped.
+ *
+ * @example
+ * ```ts
+ * varTest([1, 3, 2, 5, 4], [2, 9, 4, 12, 7, 1]).statistic; // 0.2307692
+ * ```
+ */
+export declare function varTest(x: Sample, y: Sample, options?: VarTestOptions): VarTestResult;
+/** Result of {@link bartlettTest}. Has no `alternative`, as R's `bartlett.test()` returns none. */
+export interface BartlettTestResult extends Omit<HTest, "alternative"> {
+    /** Degrees of freedom (`parameterName` is `"df"`). */
+    parameter: number;
+}
+/**
+ * Bartlett's test that the variances of several normal samples are equal. Equivalent to R's `bartlett.test()` with
+ * a list of samples. `NaN` and infinite values are dropped, as in R.
+ *
+ * @param groups The samples (at least two), each with at least two finite values.
+ *
+ * @example
+ * ```ts
+ * bartlettTest([[1, 3, 2, 5], [2, 9, 4, 12, 7], [3, 3.5, 4, 2]]).statistic;
+ * ```
+ */
+export declare function bartlettTest(groups: readonly Sample[]): BartlettTestResult;

package/dist/htest/varTest.js

@@ -0,0 +1,118 @@
+// F test comparing two variances (R's var.test) and Bartlett's test of homogeneity of variances (R's bartlett.test).
+//
+// Written for rStats.js from the textbook formulas (no ported code). var.test: F = (s_x^2 / s_y^2) / ratio with
+// (n_x - 1, n_y - 1) degrees of freedom, and the interval for the ratio from F quantiles. Both tails of the p-value
+// are computed directly (not as 1 - P), so small p-values keep their relative accuracy. bartlett.test (Bartlett,
+// Proc. R. Soc. A 160, 1937): K^2 = (N log s_p^2 - sum n_i log s_i^2) / (1 + (sum 1/n_i - 1/N) / (3 (k - 1))), with
+// n_i = size - 1, N = sum n_i and s_p^2 the pooled variance; chi-squared with k - 1 degrees of freedom.
+import { pf1, qf1 } from "../distributions/f.js";
+import { pgamma1 } from "../distributions/gamma.js";
+import { variance } from "../internal/summary.js";
+import { checkConfLevelOpen, matchAlternative } from "./types.js";
+/**
+ * F test that the variances of two normal samples have a given ratio. Equivalent to R's `var.test()`. `NaN` values
+ * are dropped.
+ *
+ * @example
+ * ```ts
+ * varTest([1, 3, 2, 5, 4], [2, 9, 4, 12, 7, 1]).statistic; // 0.2307692
+ * ```
+ */
+export function varTest(x, y, options = {}) {
+    // as in R, infinite values are dropped along with NaN
+    const xs = Array.from(x).filter(Number.isFinite);
+    const ys = Array.from(y).filter(Number.isFinite);
+    const ratio = options.ratio ?? 1;
+    if (!(Number.isFinite(ratio) && ratio > 0))
+        throw new RangeError("'ratio' must be a single positive number");
+    const alternative = matchAlternative(options.alternative);
+    const confLevel = options.confLevel ?? 0.95;
+    checkConfLevelOpen(confLevel);
+    const dfx = xs.length - 1;
+    const dfy = ys.length - 1;
+    if (dfx < 1)
+        throw new Error("not enough 'x' observations");
+    if (dfy < 1)
+        throw new Error("not enough 'y' observations");
+    const estimate = variance(xs) / variance(ys);
+    const statistic = estimate / ratio;
+    const lower = pf1(statistic, dfx, dfy, true, false);
+    const upper = pf1(statistic, dfx, dfy, false, false);
+    let pValue;
+    let confInt;
+    if (alternative === "less") {
+        pValue = lower;
+        confInt = [0, estimate / qf1(1 - confLevel, dfx, dfy, true, false)];
+    }
+    else if (alternative === "greater") {
+        pValue = upper;
+        confInt = [estimate / qf1(confLevel, dfx, dfy, true, false), Infinity];
+    }
+    else {
+        pValue = Math.min(1, 2 * Math.min(lower, upper));
+        const beta = (1 - confLevel) / 2;
+        confInt = [estimate / qf1(1 - beta, dfx, dfy, true, false), estimate / qf1(beta, dfx, dfy, true, false)];
+    }
+    return {
+        method: "F test to compare two variances",
+        alternative,
+        statistic,
+        statisticName: "F",
+        parameter: [dfx, dfy],
+        parameterName: ["num df", "denom df"],
+        pValue,
+        confInt,
+        confLevel,
+        estimate,
+        estimateNames: "ratio of variances",
+        nullValue: ratio,
+        nullValueName: "ratio of variances",
+    };
+}
+/**
+ * Bartlett's test that the variances of several normal samples are equal. Equivalent to R's `bartlett.test()` with
+ * a list of samples. `NaN` and infinite values are dropped, as in R.
+ *
+ * @param groups The samples (at least two), each with at least two finite values.
+ *
+ * @example
+ * ```ts
+ * bartlettTest([[1, 3, 2, 5], [2, 9, 4, 12, 7], [3, 3.5, 4, 2]]).statistic;
+ * ```
+ */
+export function bartlettTest(groups) {
+    const k = groups.length;
+    if (k < 2)
+        throw new RangeError("'x' must be a list with at least 2 elements");
+    const n = [];
+    const v = [];
+    for (const g of groups) {
+        // as in R, infinite values are dropped along with NaN
+        const s = Array.from(g).filter(Number.isFinite);
+        if (s.length < 2)
+            throw new RangeError("there must be at least 2 observations in each group");
+        n.push(s.length - 1);
+        v.push(variance(s));
+    }
+    let N = 0;
+    let pooled = 0;
+    let sumLog = 0;
+    let sumInv = 0;
+    for (let i = 0; i < k; i++) {
+        N += n[i];
+        pooled += n[i] * v[i];
+        sumLog += n[i] * Math.log(v[i]);
+        sumInv += 1 / n[i];
+    }
+    pooled /= N;
+    const statistic = (N * Math.log(pooled) - sumLog) / (1 + (sumInv - 1 / N) / (3 * (k - 1)));
+    const df = k - 1;
+    return {
+        method: "Bartlett test of homogeneity of variances",
+        statistic,
+        statisticName: "Bartlett's K-squared",
+        parameter: df,
+        parameterName: "df",
+        pValue: pgamma1(statistic, df / 2, 2, false, false),
+    };
+}