@numero-uno-jpn/rstats 0.5.0 → 0.6.1

package/dist/models/lm.js

@@ -0,0 +1,187 @@
+// Linear models with a matrix interface: R's lm (with summary.lm's table), confint and predict.
+//
+// Written for rStats.js (no ported code). The fit is the QR decomposition of the model matrix (a column of ones
+// first unless `intercept` is false, rows scaled by sqrt(weights)) with R's LINPACK pivoting (src/linalg/qr.ts,
+// tolerance 1e-7): columns that are linear combinations of earlier ones are moved to the end and get NaN
+// coefficients ("aliased"), as in R. The summary follows summary.lm: residual variance rss / (n - rank),
+// covariance of the estimates sigma^2 (R'R)^-1 from the triangular factor, t tests on n - rank degrees of freedom,
+// R^2 from the (weighted) mean-corrected model sum of squares when there is an intercept, and the overall F test.
+// Rows of weight 0 are left out of the fit and of the counts of observations, but get fitted values (and residuals)
+// from the coefficients, as in R.
+import { pf1 } from "../distributions/f.js";
+import { pt1, qt1 } from "../distributions/t.js";
+import { chol2inv } from "../linalg/chol.js";
+import { qr, qrCoef, qrResid } from "../linalg/qr.js";
+/**
+ * Fit a linear model by least squares. Equivalent to R's `lm(y ~ x)` (or `y ~ x - 1` without intercept, with
+ * `weights` for weighted least squares) together with `summary()`; the predictors are given as a matrix instead of a
+ * formula. Rows with a missing value in `x`, `y` or the weights are dropped.
+ *
+ * @param x Predictors: a matrix (array of rows, one column per predictor) or a vector (one predictor).
+ * @param y Response.
+ *
+ * @example
+ * ```ts
+ * const fit = lm([1, 2, 3, 4, 5], [2.1, 3.9, 6.2, 7.8, 10.1]);
+ * fit.coefficients; // [intercept, slope]
+ * fit.rSquared;
+ * ```
+ */
+export function lm(x, y, options = {}) {
+    const intercept = options.intercept ?? true;
+    const xr = x.length > 0 && typeof x[0] !== "number" ? x.map((r) => Array.from(r)) : Array.from(x, (v) => [v]);
+    const ys = Array.from(y);
+    if (xr.length !== ys.length)
+        throw new RangeError("variable lengths differ (found for 'x')");
+    const wsAll = options.weights === undefined ? undefined : Array.from(options.weights);
+    if (wsAll !== undefined && wsAll.length !== ys.length)
+        throw new RangeError("variable lengths differ (found for '(weights)')");
+    if (wsAll?.some((w) => w < 0))
+        throw new RangeError("missing or negative weights not allowed");
+    const keep = ys.map((v, i) => !Number.isNaN(v) && xr[i].every((t) => !Number.isNaN(t)) && (wsAll === undefined || !Number.isNaN(wsAll[i])));
+    const Xall = xr.filter((_, i) => keep[i]).map((r) => (intercept ? [1, ...r] : r));
+    const Yall = ys.filter((_, i) => keep[i]);
+    const Wall = wsAll?.filter((_, i) => keep[i]);
+    if (Yall.length === 0)
+        throw new RangeError("0 (non-NA) cases");
+    // the fit uses the rows of non-zero weight only
+    const fitRow = Yall.map((_, i) => Wall === undefined || Wall[i] !== 0);
+    const X = Xall.filter((_, i) => fitRow[i]);
+    const Y = Yall.filter((_, i) => fitRow[i]);
+    const W = Wall?.filter((_, i) => fitRow[i]);
+    const n = Y.length;
+    if (n === 0)
+        throw new RangeError("all weights are zero");
+    const sw = W?.map(Math.sqrt);
+    const Xw = sw === undefined ? X : X.map((r, i) => r.map((v) => v * sw[i]));
+    const Yw = sw === undefined ? Y : Y.map((v, i) => v * sw[i]);
+    const q = qr(Xw);
+    const rank = q.rank;
+    const coefficients = qrCoef(q, Yw);
+    // residuals from Q (the part of Q'y beyond the rank), so a saturated model has residuals of exactly 0, as in R
+    const rw = qrResid(q, Yw);
+    const fitResiduals = sw === undefined ? rw : rw.map((v, i) => v / sw[i]);
+    // rows of weight 0: fitted values x'b (aliased coefficients count as 0), residuals y - fitted
+    const residuals = [];
+    const fittedValues = [];
+    let k = 0;
+    Yall.forEach((v, i) => {
+        if (fitRow[i]) {
+            residuals.push(fitResiduals[k]);
+            fittedValues.push(v - fitResiduals[k]);
+            k++;
+        }
+        else {
+            const fv = Xall[i].reduce((s, t, j) => (Number.isNaN(coefficients[j]) ? s : s + t * coefficients[j]), 0);
+            fittedValues.push(fv);
+            residuals.push(v - fv);
+        }
+    });
+    const fitted = fittedValues.filter((_, i) => fitRow[i]);
+    const dfResidual = n - rank;
+    const w = W ?? new Array(n).fill(1);
+    let rss = 0;
+    for (let i = 0; i < n; i++)
+        rss += w[i] * fitResiduals[i] ** 2;
+    const resvar = rss / dfResidual;
+    const sigma = Math.sqrt(resvar);
+    // (R'R)^-1 of the leading rank x rank block, in pivot order
+    const Rr = q.qr.slice(0, rank).map((row) => row.slice(0, rank));
+    const covUnscaled = rank > 0 ? chol2inv(Rr) : [];
+    const piv = q.pivot.slice(0, rank);
+    const order = piv.map((col, k) => [col, k]).sort((a, b) => a[0] - b[0]);
+    const estimate = order.map(([col]) => coefficients[col]);
+    const stdError = order.map(([, k]) => Math.sqrt(covUnscaled[k][k] * resvar));
+    const tValue = estimate.map((e, i) => e / stdError[i]);
+    const pValue = tValue.map((t) => 2 * pt1(-Math.abs(t), dfResidual, true, false));
+    const result = {
+        coefficients,
+        residuals,
+        fittedValues,
+        rank,
+        dfResidual,
+        coefTable: { estimate, stdError, tValue, pValue },
+        sigma,
+        rSquared: 0,
+        adjRSquared: 0,
+        intercept,
+        qr: q,
+    };
+    const dfInt = intercept ? 1 : 0;
+    const numdf = rank - dfInt;
+    // nothing beyond the intercept: R^2 = 0 and no F test, as in summary.lm
+    if (numdf === 0)
+        return result;
+    let mss = 0;
+    if (intercept) {
+        const sumw = w.reduce((a, b) => a + b, 0);
+        let m = 0;
+        for (let i = 0; i < n; i++)
+            m += (w[i] * fitted[i]) / sumw;
+        for (let i = 0; i < n; i++)
+            mss += w[i] * (fitted[i] - m) ** 2;
+    }
+    else
+        for (let i = 0; i < n; i++)
+            mss += w[i] * fitted[i] ** 2;
+    result.rSquared = mss / (mss + rss);
+    result.adjRSquared = 1 - (1 - result.rSquared) * ((n - dfInt) / dfResidual);
+    const fValue = mss / numdf / resvar;
+    result.fStatistic = { value: fValue, numdf, dendf: dfResidual };
+    result.fPValue = pf1(fValue, numdf, dfResidual, false, false);
+    return result;
+}
+/**
+ * Confidence intervals for the coefficients of a linear model (NaN for aliased columns). Equivalent to R's
+ * `confint()` for an `lm` fit.
+ */
+export function confint(fit, options = {}) {
+    const level = options.level ?? 0.95;
+    const t = qt1((1 + level) / 2, fit.dfResidual, true, false);
+    const { estimate, stdError } = fit.coefTable;
+    const lower = fit.coefficients.map(() => NaN);
+    const upper = fit.coefficients.map(() => NaN);
+    let k = 0;
+    fit.coefficients.forEach((c, j) => {
+        if (Number.isNaN(c))
+            return;
+        lower[j] = estimate[k] - t * stdError[k];
+        upper[j] = estimate[k] + t * stdError[k];
+        k++;
+    });
+    return { lower, upper };
+}
+/**
+ * Predictions of a linear model at new values of the predictors, with standard errors and optionally intervals.
+ * Equivalent to R's `predict()` for an `lm` fit (`se.fit = TRUE`). Aliased columns are left out, as R does.
+ *
+ * @param newdata New predictor values, with the columns of `x` (no column of ones).
+ */
+export function predict(fit, newdata, options = {}) {
+    const rows = newdata.length > 0 && typeof newdata[0] !== "number"
+        ? newdata.map((r) => Array.from(r))
+        : Array.from(newdata, (v) => [v]);
+    const X = rows.map((r) => (fit.intercept ? [1, ...r] : r));
+    const rank = fit.rank;
+    const piv = fit.qr.pivot.slice(0, rank);
+    const Rr = fit.qr.qr.slice(0, rank).map((row) => row.slice(0, rank));
+    const resvar = fit.sigma ** 2;
+    const values = X.map((r) => r.reduce((s, v, j) => (Number.isNaN(fit.coefficients[j]) ? s : s + v * fit.coefficients[j]), 0));
+    // se: || R^-T x_piv || sigma, by forward substitution with R^T
+    const seFit = X.map((r) => {
+        const z = new Array(rank).fill(0);
+        for (let i = 0; i < rank; i++) {
+            let s = r[piv[i]];
+            for (let k = 0; k < i; k++)
+                s -= Rr[k][i] * z[k];
+            z[i] = s / Rr[i][i];
+        }
+        return Math.sqrt(z.reduce((a, v) => a + v * v, 0) * resvar);
+    });
+    const interval = options.interval ?? "none";
+    if (interval === "none")
+        return { fit: values, seFit };
+    const t = qt1((1 + (options.level ?? 0.95)) / 2, fit.dfResidual, true, false);
+    const half = seFit.map((s) => t * Math.sqrt(s * s + (interval === "prediction" ? resvar : 0)));
+    return { fit: values, seFit, lwr: values.map((v, i) => v - half[i]), upr: values.map((v, i) => v + half[i]) };
+}

package/dist/numerics/deriv.d.ts

@@ -0,0 +1,37 @@
+/** Options for {@link grad}, {@link jacobian} and {@link hessian}. */
+export interface DerivOptions {
+    /** `"Richardson"` (default) or `"simple"` (forward difference; not for `hessian`). */
+    method?: "Richardson" | "simple";
+    /** Step for "simple", and for coordinates near 0 in "Richardson". Default `1e-4`. */
+    eps?: number;
+    /** Relative initial step of "Richardson". Default `1e-4` (`0.1` for `hessian`). */
+    d?: number;
+    /** Coordinates with |x| below this get the step `eps`. Default `sqrt(2.220446e-16 / 7e-7)`. */
+    zeroTol?: number;
+    /** Number of halvings of the step (Richardson iterations). Default `4`. */
+    r?: number;
+}
+/**
+ * Gradient of a scalar function of a vector. Equivalent to `numDeriv::grad(func, x, method)`.
+ *
+ * @example
+ * ```ts
+ * grad((x) => x[0]! ** 2 + Math.sin(x[1]!), [1, 0]); // ≈ [2, 1]
+ * ```
+ */
+export declare function grad(func: (x: number[]) => number, x: readonly number[], options?: DerivOptions): number[];
+/**
+ * Jacobian of a vector function of a vector: row i holds the derivatives of the i-th value. Equivalent to
+ * `numDeriv::jacobian(func, x, method)`.
+ */
+export declare function jacobian(func: (x: number[]) => readonly number[], x: readonly number[], options?: DerivOptions): number[][];
+/**
+ * Hessian matrix of a scalar function of a vector, by Richardson extrapolation (Bates and Watts). Equivalent to
+ * `numDeriv::hessian(func, x)`.
+ *
+ * @example
+ * ```ts
+ * hessian((x) => x[0]! ** 2 * x[1]!, [1, 2]); // ≈ [[4, 2], [2, 0]]
+ * ```
+ */
+export declare function hessian(func: (x: number[]) => number, x: readonly number[], options?: DerivOptions): number[][];

package/dist/numerics/deriv.js

@@ -0,0 +1,150 @@
+// Numerical derivatives: numDeriv's grad, jacobian and hessian (methods "Richardson" and "simple").
+//
+// Written for rStats.js from the textbook methods (no ported code); the defaults and the choice of steps follow
+// numDeriv's documentation so the results agree with it. Richardson: central differences with steps h, h/2, ...,
+// h/2^(r-1), h = d |x_i| (eps where |x_i| is below zeroTol), combined by Richardson extrapolation
+// A <- (4^m A(h/2) - A(h)) / (4^m - 1) for m = 1, ..., r - 1. The Hessian is that of Bates and Watts (1988): the
+// diagonal from second central differences, the off-diagonal entries from differences along e_i + e_j less the
+// diagonal terms, each extrapolated the same way (with d = 0.1). "simple" is the forward difference with step eps.
+// numDeriv's "complex" (complex-step) method needs a function of a complex argument and is not offered.
+function steps(x, options, d0) {
+    const eps = options.eps ?? 1e-4;
+    const d = options.d ?? d0;
+    const zeroTol = options.zeroTol ?? Math.sqrt(Number.EPSILON / 7e-7);
+    const r = options.r ?? 4;
+    if (!(Number.isInteger(r) && r >= 1))
+        throw new RangeError("'r' must be a positive integer");
+    return { eps, r, h0: x.map((v) => Math.abs(d * v) + (Math.abs(v) < zeroTol ? eps : 0)) };
+}
+/** Richardson extrapolation of approximations at steps h, h/2, h/4, ... (errors in even powers of h) */
+function extrapolate(a) {
+    const t = [...a];
+    for (let m = 1; m < t.length; m++) {
+        const p = 4 ** m;
+        for (let k = 0; k < t.length - m; k++)
+            t[k] = (t[k + 1] * p - t[k]) / (p - 1);
+    }
+    return t[0];
+}
+function shifted(x, i, h) {
+    const y = [...x];
+    y[i] = y[i] + h;
+    return y;
+}
+function method(options) {
+    const m = options.method ?? "Richardson";
+    if (m !== "Richardson" && m !== "simple")
+        throw new RangeError(`unknown method "${String(m)}" (expected "Richardson" or "simple")`);
+    return m;
+}
+/**
+ * Gradient of a scalar function of a vector. Equivalent to `numDeriv::grad(func, x, method)`.
+ *
+ * @example
+ * ```ts
+ * grad((x) => x[0]! ** 2 + Math.sin(x[1]!), [1, 0]); // ≈ [2, 1]
+ * ```
+ */
+export function grad(func, x, options = {}) {
+    const xs = [...x];
+    const n = xs.length;
+    if (method(options) === "simple") {
+        const eps = options.eps ?? 1e-4;
+        const f0 = func([...xs]);
+        return xs.map((_, i) => (func(shifted(xs, i, eps)) - f0) / eps);
+    }
+    const { r, h0 } = steps(xs, options, 1e-4);
+    const out = [];
+    for (let i = 0; i < n; i++) {
+        const a = [];
+        let h = h0[i];
+        for (let k = 0; k < r; k++) {
+            // a central difference below 1e-20 is taken as 0 at the smaller steps (functions unstable near 0), as numDeriv does
+            if (k > 0 && Math.abs(a[k - 1]) < 1e-20)
+                a.push(0);
+            else
+                a.push((func(shifted(xs, i, h)) - func(shifted(xs, i, -h))) / (2 * h));
+            if (Number.isNaN(a[k]))
+                throw new RangeError(`func returned NaN at step ${h} from x`);
+            h /= 2;
+        }
+        out.push(extrapolate(a));
+    }
+    return out;
+}
+/**
+ * Jacobian of a vector function of a vector: row i holds the derivatives of the i-th value. Equivalent to
+ * `numDeriv::jacobian(func, x, method)`.
+ */
+export function jacobian(func, x, options = {}) {
+    const xs = [...x];
+    const n = xs.length;
+    const f0 = Array.from(func([...xs]));
+    const J = f0.map(() => new Array(n).fill(NaN));
+    if (method(options) === "simple") {
+        const eps = options.eps ?? 1e-4;
+        for (let j = 0; j < n; j++) {
+            const f1 = func(shifted(xs, j, eps));
+            f0.forEach((v, i) => (J[i][j] = (f1[i] - v) / eps));
+        }
+        return J;
+    }
+    const { r, h0 } = steps(xs, options, 1e-4);
+    for (let j = 0; j < n; j++) {
+        const a = f0.map(() => []);
+        let h = h0[j];
+        for (let k = 0; k < r; k++) {
+            const fp = func(shifted(xs, j, h));
+            const fm = func(shifted(xs, j, -h));
+            f0.forEach((_, i) => a[i].push((fp[i] - fm[i]) / (2 * h)));
+            h /= 2;
+        }
+        f0.forEach((_, i) => (J[i][j] = extrapolate(a[i])));
+    }
+    return J;
+}
+/**
+ * Hessian matrix of a scalar function of a vector, by Richardson extrapolation (Bates and Watts). Equivalent to
+ * `numDeriv::hessian(func, x)`.
+ *
+ * @example
+ * ```ts
+ * hessian((x) => x[0]! ** 2 * x[1]!, [1, 2]); // ≈ [[4, 2], [2, 0]]
+ * ```
+ */
+export function hessian(func, x, options = {}) {
+    if ((options.method ?? "Richardson") !== "Richardson")
+        throw new RangeError('hessian supports only method "Richardson"');
+    const xs = [...x];
+    const n = xs.length;
+    const { r, h0 } = steps(xs, options, 0.1);
+    const f0 = func([...xs]);
+    const diag = [];
+    for (let i = 0; i < n; i++) {
+        const a = [];
+        let h = h0[i];
+        for (let k = 0; k < r; k++) {
+            a.push((func(shifted(xs, i, h)) - 2 * f0 + func(shifted(xs, i, -h))) / h ** 2);
+            h /= 2;
+        }
+        diag.push(extrapolate(a));
+    }
+    const H = xs.map(() => new Array(n).fill(NaN));
+    for (let i = 0; i < n; i++) {
+        H[i][i] = diag[i];
+        for (let j = 0; j < i; j++) {
+            const a = [];
+            let hi = h0[i];
+            let hj = h0[j];
+            for (let k = 0; k < r; k++) {
+                const up = shifted(shifted(xs, i, hi), j, hj);
+                const down = shifted(shifted(xs, i, -hi), j, -hj);
+                a.push((func(up) - 2 * f0 + func(down) - diag[i] * hi ** 2 - diag[j] * hj ** 2) / (2 * hi * hj));
+                hi /= 2;
+                hj /= 2;
+            }
+            H[i][j] = H[j][i] = extrapolate(a);
+        }
+    }
+    return H;
+}

package/dist/numerics/integrate.d.ts

@@ -0,0 +1,91 @@
+/** Options for {@link integrate}. */
+export interface IntegrateOptions {
+    /** Maximum number of subintervals. Default `100`. */
+    subdivisions?: number;
+    /** Relative accuracy requested. Default `eps^0.25` (about 1.2e-4). */
+    relTol?: number;
+    /** Absolute accuracy requested. Default `relTol`. */
+    absTol?: number;
+    /** Throw when QUADPACK reports a problem (default `true`); otherwise return the result with its code. */
+    stopOnError?: boolean;
+}
+/** Result of {@link integrate}. */
+export interface IntegrateResult {
+    value: number;
+    /** Estimate of the absolute error. */
+    absError: number;
+    /** Number of subintervals used. */
+    subdivisions: number;
+    /** QUADPACK's code: 0 OK, 1 maximum number of subdivisions reached, 2 roundoff error, 3 bad integrand
+     *  behaviour, 4 roundoff error in the extrapolation table, 5 probably divergent, 6 invalid input. */
+    ier: number;
+    /** R's message for `ier`. */
+    message: string;
+}
+/**
+ * Integral of a function of one variable over a finite or infinite range. Equivalent to R's `integrate()`.
+ *
+ * @example
+ * ```ts
+ * integrate((x) => Math.exp(-x * x / 2), -Infinity, Infinity).value; // 2.5066282746310002 (sqrt(2 pi))
+ * ```
+ */
+export declare function integrate(f: (x: number) => number, lower: number, upper: number, options?: IntegrateOptions): IntegrateResult;
+/** Options for {@link optimize}. */
+export interface OptimizeOptions {
+    /** Maximise instead of minimise. Default `false`. */
+    maximum?: boolean;
+    /** Accuracy. Default `eps^0.25`. */
+    tol?: number;
+}
+/**
+ * Minimum (or maximum) of a function of one variable on an interval, by Brent's golden-section and parabolic
+ * search. Equivalent to R's `optimize()`: `optimum` is the location (R's `minimum`/`maximum`) and `objective` the
+ * function there. `lower` must be less than `upper`, as in R.
+ *
+ * @example
+ * ```ts
+ * optimize((x) => (x - 1 / 3) ** 2, 0, 1).optimum; // 0.3333333333333333
+ * ```
+ */
+export declare function optimize(f: (x: number) => number, lower: number, upper: number, options?: OptimizeOptions): {
+    optimum: number;
+    objective: number;
+};
+/** Options for {@link uniroot}. */
+export interface UnirootOptions {
+    /** Accuracy. Default `eps^0.25`. */
+    tol?: number;
+    /** Maximum number of iterations. Default `1000`. */
+    maxiter?: number;
+    /**
+     * Extend the interval when f has the same sign at both ends: `"yes"` (both ways), `"downX"` (f decreasing),
+     * `"upX"` (f increasing) or `"no"` (default).
+     */
+    extendInt?: "no" | "yes" | "downX" | "upX";
+    /** f(lower), when already known. */
+    fLower?: number;
+    /** f(upper), when already known. */
+    fUpper?: number;
+}
+/** Result of {@link uniroot}. */
+export interface UnirootResult {
+    root: number;
+    /** f at the root. */
+    fRoot: number;
+    /** Iterations used (including those extending the interval). */
+    iter: number;
+    /** Iterations used to extend the interval (NaN when it was not extended). */
+    initIt: number;
+    /** Brent's estimate of the precision of the root. */
+    estimPrec: number;
+}
+/**
+ * A root of a function of one variable in an interval, by Brent's zeroin. Equivalent to R's `uniroot()`.
+ *
+ * @example
+ * ```ts
+ * uniroot((x) => x * x - 2, 0, 2, { tol: 1e-12 }).root; // 1.4142135623731364
+ * ```
+ */
+export declare function uniroot(f: (x: number) => number, lower: number, upper: number, options?: UnirootOptions): UnirootResult;