@numero-uno-jpn/rstats 0.5.0 → 0.6.1

package/dist/special/choose.js

@@ -0,0 +1,233 @@
+// Binomial coefficients and factorials: choose, lchoose, factorial, lfactorial.
+//
+// Written for rStats.js from the definitions (no ported code):
+//   choose(n, k) = n (n - 1) ... (n - k + 1) / k!   for integer k >= 1, 1 for k = 0, 0 for k < 0,
+// with n any real number. For small k the product is formed in double-double. For larger k it is
+//   choose(n, k) = 1 / ((n + 1) B(n - k + 1, k + 1))                         (n >= k - 1)
+//   choose(n, k) = (-1)^(k+1) sin(pi n) / pi * B(n + 1, k - n)              (0 <= n < k - 1, n not an integer)
+//   choose(n, k) = (-1)^k / ((k - n) B(-n, k + 1))                         (n < 0)
+// where the second line follows from the reflection formula Gamma(z) Gamma(1 - z) = pi / sin(pi z).
+// log B is taken from lbetaDD (double-double), since its value can be in the hundreds and exp would turn the
+// rounding of a double log into a relative error of 1e-13.
+import { nonInt, roundHalfEven } from "../internal/integer.js";
+import { lbeta, lbetaDD } from "./beta.js";
+import { ddAdd, ddDiv, ddLog, ddMul, twoSum } from "./dd.js";
+import { gamma, lgamma, lgamma1p, sinpi } from "./gamma.js";
+import { digamma } from "./psigamma.js";
+/** Below this k, choose is the product n (n-1) ... (n-k+1) / k! */
+const K_SMALL = 30;
+function isInt(x) {
+    return x === Math.floor(x);
+}
+/**
+ * The n that R uses in choose (k >= K_SMALL) and lchoose (k >= 2): R reflects n < 0 to k - 1 - n before
+ * testing for an integer, so there the tolerance is relative to k - 1 - n. Returns n unchanged when R
+ * keeps it; a snapped value of -0 stands for the reflected n rounding to k - 1 (choose is then ±0).
+ */
+function rSnap(n, k) {
+    if (isInt(n))
+        return n;
+    if (n >= 0)
+        return nonInt(n) ? n : roundHalfEven(n);
+    const m = k - 1 - n;
+    return nonInt(m) ? n : k - 1 - roundHalfEven(m) || -0;
+}
+/** n (n-1) ... (n-k+1) / k! in double-double (1 <= k < K_SMALL) */
+function fallingRatio(n, k) {
+    let r = [1, 0];
+    for (let j = 0; j < k; j++)
+        r = ddDiv(ddMul(r, twoSum(n, -j)), [j + 1, 0]);
+    return r;
+}
+/** log B(a, b) (a, b > 0): double-double where lbetaDD is accurate, else lbeta (whose value is then large) */
+function logBeta(a, b) {
+    return Math.min(a, b) >= 1 && Math.max(a, b) < 2 ** 52 ? lbetaDD(a, b) : [lbeta(a, b), 0];
+}
+/**
+ * log|choose(n, k)| in double-double and the sign, for k >= K_SMALL and choose(n, k) != 0.
+ * Returns undefined when choose(n, k) is 0 (integer n with 0 <= n < k)
+ */
+function logChooseLarge(n, k) {
+    if (n < 0) {
+        // choose(n, k) = (-1)^k choose(k - n - 1, k) = (-1)^k / ((k - n) B(-n, k + 1)). Forming k - n - 1 would round
+        // away the digits of a small n (4e-4 relative at n = -1e-10, k = 1000)
+        const l = ddAdd(ddLog(twoSum(k, -n)), logBeta(-n, k + 1));
+        return { log: [-l[0], -l[1]], sign: k % 2 === 0 ? 1 : -1 };
+    }
+    if (isInt(n) && n < k)
+        return undefined;
+    if (n >= k - 1) {
+        // -log(n + 1) - log B(n - k + 1, k + 1); n - k + 1 is exact for n in [k - 1, 2 (k - 1)]
+        const l = ddAdd(ddLog(twoSum(n, 1)), logBeta(n - k + 1, k + 1));
+        return { log: [-l[0], -l[1]], sign: 1 };
+    }
+    // 0 <= n < k - 1, n not an integer: (-1)^(k+1) sin(pi n) / pi * B(n + 1, k - n). n + 1 and k - n round when they
+    // lie in a higher binade than n (1.4e-14 at n = 191.38, k = 503; 3.9e-14 at n = 255.9, k = 1001): put the roundings
+    // back to first order, d/da log B(a, b) = psi(a) - psi(a + b)
+    const s = sinpi(n);
+    const [ah, al] = twoSum(n, 1);
+    const [bh, bl] = twoSum(k, -n);
+    const dab = al === 0 && bl === 0 ? 0 : digamma(ah + bh);
+    const corr = (al === 0 ? 0 : al * (digamma(ah) - dab)) + (bl === 0 ? 0 : bl * (digamma(bh) - dab));
+    const l = ddAdd(logBeta(ah, bh), [Math.log(Math.abs(s) / Math.PI) + corr, 0]);
+    return { log: l, sign: (k % 2 === 0 ? -1 : 1) * Math.sign(s) };
+}
+/**
+ * Binomial coefficient. Equivalent to R's `choose(n, k)` for single numbers.
+ *
+ * `n` may be any real number. `k` is rounded to the nearest integer (as R does, which also warns
+ * when `k` is not close to an integer); `choose(n, k)` is 0 for `k < 0` and 1 for `k = 0`.
+ * For integer `n` the result is an integer (exact up to 2^53).
+ *
+ * Edge cases where R differs from the mathematical value, followed by default (`rCompatible: false`
+ * returns the mathematical value instead):
+ * - `n` within 1e-9 max(1, |n|) of an integer is treated as that integer, so `choose(1e-10, 2)` is 0
+ *   (mathematically -5e-11); for `n < 0` and `k >= 30` the tolerance is relative to `k - 1 - n`;
+ * - `choose(n, Infinity)` is 0 for `n >= 0` (otherwise `NaN`);
+ * - `choose(±Infinity, k)` is `NaN` for `k >= 30` (`±Infinity` below).
+ *
+ * @param n - Number of items (any real number).
+ * @param k - Number chosen (rounded to an integer).
+ * @param options - `rCompatible` (default `true`).
+ * @returns The binomial coefficient.
+ *
+ * @example
+ * ```ts
+ * choose(5, 2);    // 10
+ * choose(0.5, 3);  // 0.0625
+ * choose(-2, 3);   // -4
+ * ```
+ */
+export function choose(n, k, options) {
+    if (Number.isNaN(n) || Number.isNaN(k))
+        return NaN;
+    const rc = options?.rCompatible ?? true;
+    k = roundHalfEven(k);
+    if (k < 0)
+        return 0;
+    if (k === 0)
+        return 1;
+    if (!Number.isFinite(k))
+        return rc && n >= 0 && n < Infinity ? 0 : NaN;
+    if (!Number.isFinite(n))
+        return rc && k >= K_SMALL ? NaN : n > 0 || k % 2 === 0 ? Infinity : -Infinity;
+    if (k < K_SMALL) {
+        // R treats n within 1e-9 max(1, |n|) of an integer as an integer (src/internal/integer.ts)
+        const snap = rc && !isInt(n) && !nonInt(n);
+        // R keeps n in the product and rounds the result (choose(1e15 + 0.125, 2) is not choose(1e15, 2))
+        if (snap && n >= 0 && roundHalfEven(n) < k)
+            return 0;
+        const r = fallingRatio(n, k);
+        const v = r[0] + r[1];
+        if (Number.isFinite(v))
+            return isInt(n) || snap ? Math.round(v) : v;
+        // Overflow (the double-double steps then give NaN): the plain product overflows too
+        let p = 1;
+        for (let j = 0; j < k; j++)
+            p = (p * (n - j)) / (j + 1);
+        return p;
+    }
+    if (rc) {
+        n = rSnap(n, k);
+        // R reflects n < 0 that rounds to -0 into choose(k - 1, k) = 0, with the sign (-1)^k
+        if (Object.is(n, -0))
+            return k % 2 === 0 ? 0 : -0;
+    }
+    const r = logChooseLarge(n, k);
+    if (r === undefined)
+        return 0;
+    const v = r.sign * Math.exp(r.log[0]) * (1 + r.log[1]);
+    return isInt(n) && Number.isFinite(v) ? Math.round(v) : v;
+}
+/**
+ * Logarithm of the absolute value of the binomial coefficient. Equivalent to R's `lchoose(n, k)`
+ * for single numbers: `log(abs(choose(n, k)))`, computed without overflow.
+ *
+ * Edge cases where R differs from the mathematical value, followed by default (`rCompatible: false`
+ * returns the mathematical value instead): `n` within 1e-9 max(1, |n|) of an integer is treated as that
+ * integer (for `k >= 2`; for `n < 0` the tolerance is relative to `k - 1 - n`); `lchoose(n, Infinity)` is `-Infinity` for `n >= 0` (otherwise `NaN`); `lchoose(±Infinity, k)`
+ * is `NaN` for `k >= 2` (`Infinity` for `k = 1`).
+ *
+ * @param n - Number of items (any real number).
+ * @param k - Number chosen (rounded to an integer).
+ * @param options - `rCompatible` (default `true`).
+ * @returns log|choose(n, k)| (`-Infinity` where `choose(n, k)` is 0).
+ *
+ * @example
+ * ```ts
+ * lchoose(1000, 500);  // 689.4672615678512
+ * ```
+ */
+export function lchoose(n, k, options) {
+    if (Number.isNaN(n) || Number.isNaN(k))
+        return NaN;
+    const rc = options?.rCompatible ?? true;
+    k = roundHalfEven(k);
+    if (k < 0)
+        return -Infinity;
+    if (k === 0)
+        return 0;
+    if (!Number.isFinite(k))
+        return rc && n >= 0 && n < Infinity ? -Infinity : NaN;
+    if (!Number.isFinite(n))
+        return rc && k >= 2 ? NaN : Infinity;
+    // R's lchoose(n, 1) is log|n| without rounding n; for k >= 2 it rounds n itself (unlike choose for k < 30)
+    if (rc && k >= 2)
+        n = rSnap(n, k);
+    if (k < K_SMALL) {
+        const r = fallingRatio(n, k);
+        const v = Math.abs(r[0] + r[1]);
+        if (v > 1e-300 && v < 1e300) {
+            // log of a double-double value
+            const l = ddLog(r[0] < 0 ? [-r[0], -r[1]] : r);
+            return l[0] + l[1];
+        }
+        if (v === 0)
+            return -Infinity;
+        // Out of range: sum of logs (the result is large in magnitude, so its rounding is relatively small)
+        let s = -lgamma(k + 1);
+        for (let j = 0; j < k; j++)
+            s += Math.log(Math.abs(n - j));
+        return s;
+    }
+    const r = logChooseLarge(n, k);
+    if (r === undefined)
+        return -Infinity;
+    // For integer n the coefficient is an integer; below 2^53 take the log of the exact value (so that lchoose(n, n) is 0)
+    if (isInt(n) && r.log[0] < 36)
+        return Math.log(Math.round(Math.exp(r.log[0]) * (1 + r.log[1])));
+    return r.log[0] + r.log[1];
+}
+/**
+ * Factorial. Equivalent to R's `factorial(x)` for a single number: `gamma(x + 1)`, defined for
+ * any real `x` that is not a negative integer.
+ *
+ * @param x - Argument.
+ * @returns x! = Gamma(x + 1) (`NaN` at negative integers, `Infinity` on overflow).
+ *
+ * @example
+ * ```ts
+ * factorial(5);    // 120
+ * factorial(0.5);  // 0.8862269254527579
+ * ```
+ */
+export function factorial(x) {
+    return gamma(x + 1);
+}
+/**
+ * Logarithm of the factorial. Equivalent to R's `lfactorial(x)` for a single number:
+ * `lgamma(x + 1)`, computed without forming `x + 1` near 0 so that small `x` keep their accuracy.
+ *
+ * @param x - Argument.
+ * @returns log|x!| = log|Gamma(x + 1)| (`Infinity` at negative integers).
+ *
+ * @example
+ * ```ts
+ * lfactorial(100);  // 363.73937555556347
+ * ```
+ */
+export function lfactorial(x) {
+    if (Math.abs(x) <= 0.2)
+        return lgamma1p(x);
+    return lgamma(x + 1);
+}

package/dist/special/erf.d.ts

@@ -1,6 +1,32 @@
-/** Error function erf(x). */
+/**
+ * Error function, erf(x) = 2 / sqrt(pi) * integral from 0 to x of exp(-t^2) dt. Not part of R (where it is written
+ * `2 * pnorm(x * sqrt(2)) - 1`, which loses the relative accuracy of small x).
+ *
+ * @param x - Argument.
+ * @returns erf(x).
+ *
+ * @example
+ * ```ts
+ * erf(0.5);    // 0.5204998778130465
+ * erf(1e-10);  // 1.1283791670955126e-10
+ * ```
+ */
 export declare function erf(x: number): number;
-/** Complementary error function erfc(x) = 1 - erf(x). */
+/**
+ * Complementary error function, erfc(x) = 1 - erf(x), accurate in the upper tail (down to the subnormal range near
+ * x = 27). Not part of R (where it is written `2 * pnorm(x * sqrt(2), lower.tail = FALSE)`).
+ *
+ * @param a - Argument.
+ * @returns erfc(a).
+ *
+ * @example
+ * ```ts
+ * erfc(5);  // 1.537459794428035e-12
+ * ```
+ *
+ * Changes from xsf: exp(-x^2) is formed from x^2 = hi + lo exact (the rounding of x^2 is 33 ε relative at x = 5.7),
+ * and below the normal range exp(-700) is applied last so that subnormal results (x up to 27.2) are not flushed to 0.
+ */
 export declare function erfc(a: number): number;
 /**
  * Scaled complementary error function erfcx(x) = exp(x^2) erfc(x) (x >= 0).

package/dist/special/erf.js

@@ -7,6 +7,7 @@
 // approximations directly. This gives the tail value before multiplying by exp(-x^2), usable for computations
 // that take the log (logP in pnorm) or that recompute exp(-x^2) accurately.
 import { p1evl, polevl } from "./polevl.js";
+import { twoProd } from "./dd.js";
 const P = [
     2.46196981473530512524e-10, 5.64189564831068821977e-1, 7.46321056442269912687e0,
     4.86371970985681366614e1, 1.96520832956077098242e2, 5.26445194995477358631e2,
@@ -37,7 +38,19 @@ const U = [
 const MAXLOG = 7.097827128933839730962063185871e2;
 /** 1/sqrt(pi) */
 const INV_SQRT_PI = 0.5641895835477562869;
-/** Error function erf(x). */
+/**
+ * Error function, erf(x) = 2 / sqrt(pi) * integral from 0 to x of exp(-t^2) dt. Not part of R (where it is written
+ * `2 * pnorm(x * sqrt(2)) - 1`, which loses the relative accuracy of small x).
+ *
+ * @param x - Argument.
+ * @returns erf(x).
+ *
+ * @example
+ * ```ts
+ * erf(0.5);    // 0.5204998778130465
+ * erf(1e-10);  // 1.1283791670955126e-10
+ * ```
+ */
 export function erf(x) {
     if (Number.isNaN(x))
         return NaN;
@@ -48,22 +61,36 @@ export function erf(x) {
     const z = x * x;
     return (x * polevl(z, T)) / p1evl(z, U);
 }
-/** Complementary error function erfc(x) = 1 - erf(x). */
+/**
+ * Complementary error function, erfc(x) = 1 - erf(x), accurate in the upper tail (down to the subnormal range near
+ * x = 27). Not part of R (where it is written `2 * pnorm(x * sqrt(2), lower.tail = FALSE)`).
+ *
+ * @param a - Argument.
+ * @returns erfc(a).
+ *
+ * @example
+ * ```ts
+ * erfc(5);  // 1.537459794428035e-12
+ * ```
+ *
+ * Changes from xsf: exp(-x^2) is formed from x^2 = hi + lo exact (the rounding of x^2 is 33 ε relative at x = 5.7),
+ * and below the normal range exp(-700) is applied last so that subnormal results (x up to 27.2) are not flushed to 0.
+ */
 export function erfc(a) {
     if (Number.isNaN(a))
         return NaN;
     const x = Math.abs(a);
     if (x < 1)
         return 1 - erf(a);
-    const z = -a * a;
-    if (z < -MAXLOG)
-        return a < 0 ? 2 : 0;
-    let y = Math.exp(z) * erfcxRational(x);
     if (a < 0)
-        y = 2 - y;
-    if (y === 0)
-        return a < 0 ? 2 : 0;
-    return y;
+        return 2 - erfc(x);
+    const [hi, lo] = twoProd(x, x);
+    if (hi > MAXLOG + 40)
+        return 0;
+    const r = erfcxRational(x) * (1 - lo);
+    if (hi < 700)
+        return Math.exp(-hi) * r;
+    return Math.exp(700 - hi) * r * Math.exp(-700);
 }
 /**
  * Scaled complementary error function erfcx(x) = exp(x^2) erfc(x) (x >= 0).

package/dist/special/extra.d.ts

@@ -0,0 +1,47 @@
+/** Result of {@link gammainc}. */
+export interface GammaincResult {
+    /** Lower incomplete gamma function gamma(a, x) = integral from 0 to x of t^(a-1) e^-t dt. */
+    lower: number;
+    /** Upper incomplete gamma function Gamma(a, x) = integral from x to Inf of t^(a-1) e^-t dt. */
+    upper: number;
+    /** log of `lower` (finite where `lower` overflows). */
+    logLower: number;
+    /** log of `upper`. */
+    logUpper: number;
+}
+/**
+ * The non-regularized incomplete gamma functions gamma(a, x) and Gamma(a, x) and their logs. As
+ * `pracma::gammainc(x, a)` (`lowinc`, `uppinc`), or R's `pgamma(x, a) * gamma(a)` and
+ * `pgamma(x, a, lower.tail = FALSE) * gamma(a)`.
+ *
+ * @example
+ * ```ts
+ * gammainc(2, 3).lower; // 0.6466471676338731 = 2 - 10 e^-2
+ * ```
+ */
+export declare function gammainc(x: number, a: number): GammaincResult;
+/**
+ * Inverse of the complementary error function: the x with erfc(x) = z, for 0 <= z <= 2 (NaN outside). As
+ * `pracma::erfcinv`.
+ */
+export declare function erfcinv(z: number): number;
+/**
+ * Inverse of the error function: the x with erf(x) = y, for -1 <= y <= 1 (NaN outside). As `pracma::erfinv`, but
+ * accurate for small |y| (pracma's `qnorm((1 + y) / 2)` loses it: `erfinv(1e-300)` is -0 there).
+ *
+ * @example
+ * ```ts
+ * erfinv(0.5); // 0.4769362762044699
+ * ```
+ */
+export declare function erfinv(y: number): number;
+/**
+ * Number of ordered selections of k items from n: n! / (n - k)!, defined for real n >= 0 as
+ * Gamma(n + 1) / Gamma(n - k + 1) (0 for an integer n < k). jStat's `permutation`. Negative arguments give NaN.
+ *
+ * @example
+ * ```ts
+ * perm(5, 2); // 20
+ * ```
+ */
+export declare function perm(n: number, k: number): number;

package/dist/special/extra.js

@@ -0,0 +1,220 @@
+// The non-regularized incomplete gamma functions, the inverse error functions and the number of permutations:
+// gammainc, erfinv, erfcinv, perm.
+//
+// Written for rStats.js from the definitions (no ported code).
+// - gammainc: gamma(a) times the regularized P(a, x) and Q(a, x) of src/special/igam.ts. Where the product over- or
+//   underflows but the value does not (a above 171.6), the smaller tail is x^a e^-x times the series (x < a) or the
+//   continued fraction (x > a) of igam.ts, with the exponent a log x - x in double-double (exp(lgamma(a) + log P)
+//   turned the rounding of its terms, up to 1e5 in size, into a relative error of 1e-12).
+// - erfcinv(z) = -qnorm(z / 2) / sqrt(2) (exact halving; qnorm is accurate in both tails); erfinv(y) = erfcinv(1 - y)
+//   for |y| >= 1/2 (1 - |y| is exact there), and for smaller |y| that value refined by Newton steps on erf (the
+//   form through qnorm((1 + y) / 2) loses the relative accuracy of a small y).
+// - perm(n, k) = n (n - 1) ... (n - k + 1) = Gamma(n + 1) / Gamma(n - k + 1): the product formed in double-double
+//   for integer k up to 1000 (+-Infinity once it overflows), otherwise the ratio of gamma functions with its log in
+//   double-double: for n - k >= 15 from Stirling's formula through Loader's stirlerr and bd0 (src/special/loader.ts),
+//   which does not cancel as lgamma(n + 1) - lgamma(n - k + 1) does, and for n - k + 1 <= 0 by the reflection formula.
+import { qnorm } from "../distributions/normal.js";
+import { ddAdd, ddLog, ddMul, ddMulNum, ddSub, twoSum } from "./dd.js";
+import { erf } from "./erf.js";
+import { gamma, lgamma, lgammaSign, sinpi } from "./gamma.js";
+import { gammaInc, igamcContinuedFractionValue, igamSeriesSum } from "./igam.js";
+import { bd0dd, stirlerr } from "./loader.js";
+import { digamma } from "./psigamma.js";
+/**
+ * The non-regularized incomplete gamma functions gamma(a, x) and Gamma(a, x) and their logs. As
+ * `pracma::gammainc(x, a)` (`lowinc`, `uppinc`), or R's `pgamma(x, a) * gamma(a)` and
+ * `pgamma(x, a, lower.tail = FALSE) * gamma(a)`.
+ *
+ * @example
+ * ```ts
+ * gammainc(2, 3).lower; // 0.6466471676338731 = 2 - 10 e^-2
+ * ```
+ */
+export function gammainc(x, a) {
+    if (Number.isNaN(x) || Number.isNaN(a) || x < 0 || !(a > 0))
+        return { lower: NaN, upper: NaN, logLower: NaN, logUpper: NaN };
+    const lg = lgamma(a);
+    const g = gamma(a);
+    const tail = (lower) => {
+        const p = gammaInc(a, x, lower, false);
+        const v = g * p;
+        // the product where it is a normal number (then also its log: lgamma(a) + log P can cancel)
+        if (Number.isFinite(g) && p > DBL_MIN && Number.isFinite(v) && v > DBL_MIN)
+            return [v, Math.log(v)];
+        const log = lg + gammaInc(a, x, lower, true);
+        // the smaller tail, unless the value over- or underflows anyway (its log is then large, and lg + log P is accurate
+        // relative to it)
+        if (log < 710 && log > -746 && x > 0 && (lower ? x < a : x > a))
+            return smallTail(x, a, lower);
+        return [Math.exp(log), log];
+    };
+    const [lower, logLower] = tail(true);
+    const [upper, logUpper] = tail(false);
+    return { lower, upper, logLower, logUpper };
+}
+const DBL_MIN = 2.2250738585072014e-308;
+/**
+ * [value, log] of gamma(a, x) for x < a (lower) or Gamma(a, x) for x > a: x^a e^-x / a times the series
+ * sum_n x^n / ((a + 1) ... (a + n)), or x^a e^-x times the continued fraction. The exponent is formed in
+ * double-double together with the logs of the other factors, and exp is taken once
+ */
+function smallTail(x, a, lower) {
+    let e = ddAdd(ddMulNum(ddLog([x, 0]), a), [-x, 0]);
+    if (lower)
+        e = ddAdd(e, ddLog([igamSeriesSum(a, x) / a, 0]));
+    else
+        e = ddAdd(e, ddLog([igamcContinuedFractionValue(a, x), 0]));
+    const log = e[0] + e[1];
+    // exp(e0 + e1) = exp(e0) (1 + e1); in the subnormal range the last digits are lost anyway
+    const v = e[0] > -708 ? Math.exp(e[0]) * (1 + e[1]) : Math.exp(log);
+    return [v, log];
+}
+/**
+ * Inverse of the complementary error function: the x with erfc(x) = z, for 0 <= z <= 2 (NaN outside). As
+ * `pracma::erfcinv`.
+ */
+export function erfcinv(z) {
+    if (Number.isNaN(z) || z < 0 || z > 2)
+        return NaN;
+    return -qnorm(z / 2) * Math.SQRT1_2;
+}
+/**
+ * Inverse of the error function: the x with erf(x) = y, for -1 <= y <= 1 (NaN outside). As `pracma::erfinv`, but
+ * accurate for small |y| (pracma's `qnorm((1 + y) / 2)` loses it: `erfinv(1e-300)` is -0 there).
+ *
+ * @example
+ * ```ts
+ * erfinv(0.5); // 0.4769362762044699
+ * ```
+ */
+export function erfinv(y) {
+    if (Number.isNaN(y) || y < -1 || y > 1)
+        return NaN;
+    const s = y < 0 ? -1 : 1;
+    const a = Math.abs(y);
+    if (a >= 0.5)
+        return s * erfcinv(1 - a);
+    if (a < 1e-8)
+        return y * 0.886226925452758 * (1 + (Math.PI / 12) * y * y); // sqrt(pi)/2 (y + pi y^3 / 12)
+    let x = erfcinv(1 - a);
+    for (let i = 0; i < 3; i++) {
+        const d = (erf(x) - a) / (1.1283791670955126 * Math.exp(-x * x)); // erf' = 2/sqrt(pi) e^(-x^2)
+        x -= d;
+        if (Math.abs(d) <= 1e-17 * x)
+            break;
+    }
+    return s * x;
+}
+/**
+ * Number of ordered selections of k items from n: n! / (n - k)!, defined for real n >= 0 as
+ * Gamma(n + 1) / Gamma(n - k + 1) (0 for an integer n < k). jStat's `permutation`. Negative arguments give NaN.
+ *
+ * @example
+ * ```ts
+ * perm(5, 2); // 20
+ * ```
+ */
+export function perm(n, k) {
+    if (Number.isNaN(n) || Number.isNaN(k) || n < 0 || k < 0)
+        return NaN;
+    const intK = k === Math.floor(k);
+    if (n === Math.floor(n) && intK && k > n)
+        return 0;
+    if (!Number.isFinite(n) || !Number.isFinite(k))
+        return permLgamma(n, k);
+    if (intK && k <= 1000)
+        return fallingFactorial(n, k);
+    return gammaRatio(n, k);
+}
+/** n (n - 1) ... (n - k + 1) in double-double (integer k; no factor is 0), +-Infinity once it overflows */
+function fallingFactorial(n, k) {
+    let p = [1, 0];
+    for (let i = 0; i < k; i++) {
+        const f = twoSum(n, -i); // n - i exactly
+        const hi = p[0] * f[0];
+        if (!Number.isFinite(hi)) {
+            // the sign of the rest of the product decides the sign of the infinity
+            let sign = Math.sign(hi);
+            for (let j = i + 1; j < k; j++)
+                if (n - j < 0)
+                    sign = -sign;
+            return sign * Infinity;
+        }
+        // Veltkamp splitting overflows above about 1e300: the last steps before overflow in double precision
+        p = Math.abs(p[0]) > 1e290 || Math.abs(f[0]) > 1e290 ? [(p[0] + p[1]) * (f[0] + f[1]), 0] : ddMul(p, f);
+    }
+    return p[0] + p[1];
+}
+/**
+ * Gamma(n + 1) / Gamma(m + 1), m = n - k (as mh + ml exactly). For n > 170 Stirling's formula
+ * Gamma(z + 1) = sqrt(2 pi z) (z / e)^z exp(stirlerr(z)) gives, with n = mh + kk,
+ *   log ratio = kk log n - bd0(mh, n) + stirlerr(n) - stirlerr(mh),  bd0(mh, n) = mh log(mh / n) + n - mh,
+ * formed in double-double without the cancellation of lgamma(n + 1) - lgamma(m + 1) (1e-9 relative at
+ * perm(1e6, 2.5)). The rounding ml of n - k is put back to first order, Gamma(m + 1) = Gamma(mh + 1) e^(ml psi(mh + 1));
+ * for m + 1 < 0 the reflection formula takes over (m + 1 can lie next to a pole of Gamma)
+ */
+function gammaRatio(n, k) {
+    const [mh, ml] = twoSum(n, -k);
+    if (mh + 1 <= 0)
+        return gammaRatioReflected(n, mh, ml);
+    // n^k (1 + O(k^2 / n)); a k large enough for the correction to matter overflows n^k
+    if (n > 1e280)
+        return k * k < 1e-17 * n ? Math.pow(n, k) : Infinity;
+    let r;
+    if (mh >= 15) {
+        // the ratio is at least (m + 1)^k: overflow before the terms get large
+        if (k * Math.log(mh + 1) > 720)
+            return Infinity;
+        const kk = twoSum(n, -mh);
+        let e = ddSub(ddMul(kk, ddLog([n, 0])), bd0dd(mh, [n, 0]));
+        e = ddAdd(e, [stirlerr(n) - stirlerr(mh), 0]);
+        r = Math.sqrt(n / mh) * Math.exp(e[0]) * (1 + e[1]);
+    }
+    else if (n < 30) {
+        r = gamma(n + 1) / gamma(mh + 1);
+    }
+    else {
+        if (lgamma(n + 1) - lgamma(mh + 1) > 720)
+            return Infinity;
+        const e = ddSub(lgammaDD(n + 1), ddLog([gamma(mh + 1), 0]));
+        r = Math.exp(e[0]) * (1 + e[1]);
+    }
+    if (ml !== 0 && Number.isFinite(r) && r !== 0)
+        r *= Math.exp(-ml * digamma(mh + 1));
+    return r;
+}
+/**
+ * Gamma(n + 1) / Gamma(m + 1) for m + 1 = z <= 0: 1 / Gamma(z) = Gamma(1 - z) sin(pi z) / pi with 1 - z = -m.
+ * sin(pi z) takes the low part of z to first order (exact 0 at a pole, (-1)^j pi zl next to it)
+ */
+function gammaRatioReflected(n, mh, ml) {
+    const z = ddAdd(twoSum(mh, 1), [ml, 0]);
+    const s = sinpi(z[0]) + sinpi(z[0] + 0.5) * Math.PI * z[1];
+    if (s === 0)
+        return 0;
+    const sign = Math.sign(s);
+    // log(|s| / pi) in double-double too: next to a pole it is about -33, whose rounding would be 3e-15 relative
+    const ls = ddAdd(ddSub(ddLog([Math.abs(s), 0]), LOGPI_DD), [-ml * digamma(-mh), 0]);
+    if (lgamma(n + 1) + lgamma(-mh) + ls[0] > 720)
+        return sign * Infinity;
+    const e = ddAdd(ddAdd(lgammaDD(n + 1), lgammaDD(-mh)), ls);
+    return sign * Math.exp(e[0]) * (1 + e[1]);
+}
+const LS2PI_DD = [0.91893853320467278, -3.8782941580672414e-17];
+const LOGPI_DD = [1.1447298858494002, 1.0265951162707826e-17];
+/**
+ * lgamma(z) in double-double for 0 < z < 1e280: the log of gamma(z) below 15, above it
+ * (z - 1/2) log z - z + log sqrt(2 pi) + stirlerr(z) (stirlerr(z) = lgamma(z + 1) - (z + 1/2) log z + z - log sqrt(2 pi))
+ */
+function lgammaDD(z) {
+    if (z < 15)
+        return ddLog([gamma(z), 0]);
+    const e = ddSub(ddMul(twoSum(z, -0.5), ddLog([z, 0])), [z, 0]);
+    return ddAdd(ddAdd(e, LS2PI_DD), [stirlerr(z), 0]);
+}
+/** Gamma(n + 1) / Gamma(n - k + 1) from lgamma (infinite n or k) */
+function permLgamma(n, k) {
+    const num = lgammaSign(n + 1);
+    const den = lgammaSign(n - k + 1);
+    return num.sign * den.sign * Math.exp(num.value - den.value);
+}

package/dist/special/igam.d.ts

@@ -1,3 +1,7 @@
+/** sum_n x^n / ((a + 1) ... (a + n)): P(a, x) = x^a e^-x / Gamma(a + 1) times this */
+export declare function igamSeriesSum(a: number, x: number): number;
+/** The continued fraction of DLMF 8.9.2: Q(a, x) = x^a e^-x / Gamma(a) times this */
+export declare function igamcContinuedFractionValue(a: number, x: number): number;
 /**
  * Return [log, linear] of gammaInc from a single series/continued-fraction computation.
  * The values are bit-identical to gammaInc(.., true) and gammaInc(.., false) respectively