@iyulab/u-numflow 0.6.1 → 0.6.3

package/README.md

@@ -17,7 +17,7 @@ u-numflow provides foundational mathematical, statistical, and probabilistic bui
 |--------|-------------|
 | `stats` | Descriptive statistics (mean, variance, skewness, kurtosis) with Welford's online algorithm and Neumaier summation |
 | `distributions` | Probability distributions: Uniform, Triangular, PERT, Normal, LogNormal |
-| `special` | Special functions: normal CDF and tail-precise survival function (and their inverses), t/F/chi² CDF, regularized incomplete beta/gamma, erf |
+| `special` | Special functions: normal CDF and tail-precise survival function (and their inverses), t/F/chi² CDF and quantiles, the noncentral t CDF (Lenth AS 243 — the distribution power is computed from), regularized incomplete beta/gamma, erf |
 | `transforms` | Data transformations: Box-Cox (λ via MLE golden-section search), inverse Box-Cox |
 | `fourier` | Discrete Fourier transform of any length (radix-2 for powers of two, Bluestein otherwise): `fft`, `ifft`, `rfft`, `Complex` |
 | `matrix` | Dense matrix operations: determinant, inverse, Cholesky decomposition, Jacobi eigenvalue decomposition |
@@ -104,6 +104,42 @@ Exported functions: `mean`, `std_dev`, `variance`, `normal_cdf`, `normal_sf` (up
 `rfft(data) -> Float64Array` — the DFT of a real sequence of any length, interleaved as
 `[re0, im0, re1, im1, …]` (bins `k` and `n − k` are conjugates, so `0..=n/2` describes the spectrum).
 
+Distribution functions for critical values and p-values — each returns a `number` and
+**throws** (a message naming the argument) when an argument is outside the domain,
+rather than returning `NaN`:
+
+| Function | Returns |
+|---|---|
+| `inverse_normal_cdf(p)` | `z` with `P(Z ≤ z) = p` |
+| `t_distribution_cdf(t, df)` / `t_distribution_quantile(p, df)` | Student's t; a two-sided critical value at level α is `t_distribution_quantile(1 − α/2, df)` |
+| `f_distribution_cdf(x, df1, df2)` / `f_distribution_quantile(p, df1, df2)` | F |
+| `chi_squared_cdf(x, k)` / `chi_squared_quantile(p, k)` | χ² |
+
+`p` must lie strictly between 0 and 1 and every degrees-of-freedom argument must be a
+finite number `> 0` (fractional values are allowed).
+
+```js
+const { t_distribution_quantile } = require("@iyulab/u-numflow");
+t_distribution_quantile(0.975, 10); // 2.2281…
+```
+
+### TypeScript
+
+Every exported function declares its return type, and the declarations are
+generated from the same structs the binding serialises, so they cannot drift
+from what it actually returns:
+
+```ts
+export function estimate_lambda(data: any): LambdaEstimateDto;
+```
+
+An absent optional value is declared `T | undefined`, which is what the binding
+sends. Nothing needs an `as` cast -- and a wrong assumption about a result's
+shape is a compile error rather than something that fails at run time.
+
+Inputs are still `any`: they are validated at the boundary, and a rejected one
+says what was wrong.
+
 ## Related
 
 - [u-metaheur](https://github.com/iyulab/u-metaheur) — Metaheuristic optimization (GA, SA, ALNS, CP)

package/node/u_numflow.cjs

@@ -25,6 +25,43 @@ function box_cox(data, lambda) {
 }
 exports.box_cox = box_cox;
 
+/**
+ * Chi-squared CDF: `P(X ≤ x)` for `X ~ χ²(k)` (`0` for `x ≤ 0`).
+ *
+ * # Errors
+ * Throws if `x` is NaN or `k` is not a finite number > 0.
+ * @param {number} x
+ * @param {number} k
+ * @returns {number}
+ */
+function chi_squared_cdf(x, k) {
+    const ret = wasm.chi_squared_cdf(x, k);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return ret[0];
+}
+exports.chi_squared_cdf = chi_squared_cdf;
+
+/**
+ * Chi-squared quantile: the `x` with `P(X ≤ x) = p` for `X ~ χ²(k)`.
+ *
+ * # Errors
+ * Throws if `p` is not strictly between 0 and 1, or `k` is not a finite
+ * number > 0.
+ * @param {number} p
+ * @param {number} k
+ * @returns {number}
+ */
+function chi_squared_quantile(p, k) {
+    const ret = wasm.chi_squared_quantile(p, k);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return ret[0];
+}
+exports.chi_squared_quantile = chi_squared_quantile;
+
 /**
  * Estimate the optimal Box-Cox lambda via profile maximum likelihood.
  *
@@ -41,7 +78,7 @@ exports.box_cox = box_cox;
  * @param {Float64Array} data
  * @param {number} lambda_min
  * @param {number} lambda_max
- * @returns {any}
+ * @returns {LambdaEstimateDto}
  */
 function estimate_lambda(data, lambda_min, lambda_max) {
     const ptr0 = passArrayF64ToWasm0(data, wasm.__wbindgen_malloc);
@@ -54,6 +91,62 @@ function estimate_lambda(data, lambda_min, lambda_max) {
 }
 exports.estimate_lambda = estimate_lambda;
 
+/**
+ * F CDF: `P(X ≤ x)` for `X ~ F(df1, df2)` (`0` for `x ≤ 0`).
+ *
+ * # Errors
+ * Throws if `x` is NaN, or `df1`/`df2` is not a finite number > 0.
+ * @param {number} x
+ * @param {number} df1
+ * @param {number} df2
+ * @returns {number}
+ */
+function f_distribution_cdf(x, df1, df2) {
+    const ret = wasm.f_distribution_cdf(x, df1, df2);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return ret[0];
+}
+exports.f_distribution_cdf = f_distribution_cdf;
+
+/**
+ * F quantile: the `x` with `P(X ≤ x) = p` for `X ~ F(df1, df2)`.
+ *
+ * # Errors
+ * Throws if `p` is not strictly between 0 and 1, or `df1`/`df2` is not a
+ * finite number > 0.
+ * @param {number} p
+ * @param {number} df1
+ * @param {number} df2
+ * @returns {number}
+ */
+function f_distribution_quantile(p, df1, df2) {
+    const ret = wasm.f_distribution_quantile(p, df1, df2);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return ret[0];
+}
+exports.f_distribution_quantile = f_distribution_quantile;
+
+/**
+ * Standard normal quantile Φ⁻¹(p): the `z` with `P(Z ≤ z) = p`.
+ *
+ * # Errors
+ * Throws if `p` is not strictly between 0 and 1.
+ * @param {number} p
+ * @returns {number}
+ */
+function inverse_normal_cdf(p) {
+    const ret = wasm.inverse_normal_cdf(p);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return ret[0];
+}
+exports.inverse_normal_cdf = inverse_normal_cdf;
+
 /**
  * Arithmetic mean of `data` using Kahan compensated summation.
  *
@@ -134,6 +227,44 @@ function std_dev(data) {
 }
 exports.std_dev = std_dev;
 
+/**
+ * Student's t CDF: `P(T ≤ t)` for `T ~ t(df)`. `df` may be fractional.
+ *
+ * # Errors
+ * Throws if `t` is NaN or `df` is not a finite number > 0.
+ * @param {number} t
+ * @param {number} df
+ * @returns {number}
+ */
+function t_distribution_cdf(t, df) {
+    const ret = wasm.t_distribution_cdf(t, df);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return ret[0];
+}
+exports.t_distribution_cdf = t_distribution_cdf;
+
+/**
+ * Student's t quantile: the `t` with `P(T ≤ t) = p`. A two-sided critical
+ * value at level α is `t_distribution_quantile(1 − α/2, df)`.
+ *
+ * # Errors
+ * Throws if `p` is not strictly between 0 and 1, or `df` is not a finite
+ * number > 0.
+ * @param {number} p
+ * @param {number} df
+ * @returns {number}
+ */
+function t_distribution_quantile(p, df) {
+    const ret = wasm.t_distribution_quantile(p, df);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return ret[0];
+}
+exports.t_distribution_quantile = t_distribution_quantile;
+
 /**
  * Sample variance of `data` (Bessel-corrected, denominator n−1).
  *

package/node/u_numflow.d.cts

@@ -1,5 +1,13 @@
 /* tslint:disable */
 /* eslint-disable */
+/**
+ * Output of [`estimate_lambda`]: `{ lambda, at_bound }`.
+ */
+export interface LambdaEstimateDto {
+    lambda: number;
+    at_bound: boolean;
+}
+
 
 /**
  * Apply the Box-Cox power transformation to positive data.
@@ -12,6 +20,23 @@
  */
 export function box_cox(data: Float64Array, lambda: number): Float64Array;
 
+/**
+ * Chi-squared CDF: `P(X ≤ x)` for `X ~ χ²(k)` (`0` for `x ≤ 0`).
+ *
+ * # Errors
+ * Throws if `x` is NaN or `k` is not a finite number > 0.
+ */
+export function chi_squared_cdf(x: number, k: number): number;
+
+/**
+ * Chi-squared quantile: the `x` with `P(X ≤ x) = p` for `X ~ χ²(k)`.
+ *
+ * # Errors
+ * Throws if `p` is not strictly between 0 and 1, or `k` is not a finite
+ * number > 0.
+ */
+export function chi_squared_quantile(p: number, k: number): number;
+
 /**
  * Estimate the optimal Box-Cox lambda via profile maximum likelihood.
  *
@@ -26,7 +51,32 @@ export function box_cox(data: Float64Array, lambda: number): Float64Array;
  * has fewer than 2 elements, or the range is not finite with
  * `lambda_min < lambda_max`.
  */
-export function estimate_lambda(data: Float64Array, lambda_min: number, lambda_max: number): any;
+export function estimate_lambda(data: Float64Array, lambda_min: number, lambda_max: number): LambdaEstimateDto;
+
+/**
+ * F CDF: `P(X ≤ x)` for `X ~ F(df1, df2)` (`0` for `x ≤ 0`).
+ *
+ * # Errors
+ * Throws if `x` is NaN, or `df1`/`df2` is not a finite number > 0.
+ */
+export function f_distribution_cdf(x: number, df1: number, df2: number): number;
+
+/**
+ * F quantile: the `x` with `P(X ≤ x) = p` for `X ~ F(df1, df2)`.
+ *
+ * # Errors
+ * Throws if `p` is not strictly between 0 and 1, or `df1`/`df2` is not a
+ * finite number > 0.
+ */
+export function f_distribution_quantile(p: number, df1: number, df2: number): number;
+
+/**
+ * Standard normal quantile Φ⁻¹(p): the `z` with `P(Z ≤ z) = p`.
+ *
+ * # Errors
+ * Throws if `p` is not strictly between 0 and 1.
+ */
+export function inverse_normal_cdf(p: number): number;
 
 /**
  * Arithmetic mean of `data` using Kahan compensated summation.
@@ -70,6 +120,24 @@ export function rfft(data: Float64Array): Float64Array;
  */
 export function std_dev(data: Float64Array): number;
 
+/**
+ * Student's t CDF: `P(T ≤ t)` for `T ~ t(df)`. `df` may be fractional.
+ *
+ * # Errors
+ * Throws if `t` is NaN or `df` is not a finite number > 0.
+ */
+export function t_distribution_cdf(t: number, df: number): number;
+
+/**
+ * Student's t quantile: the `t` with `P(T ≤ t) = p`. A two-sided critical
+ * value at level α is `t_distribution_quantile(1 − α/2, df)`.
+ *
+ * # Errors
+ * Throws if `p` is not strictly between 0 and 1, or `df` is not a finite
+ * number > 0.
+ */
+export function t_distribution_quantile(p: number, df: number): number;
+
 /**
  * Sample variance of `data` (Bessel-corrected, denominator n−1).
  *

package/package.json

@@ -5,7 +5,7 @@
     "iyulab"
   ],
   "description": "Foundational mathematical primitives: statistics, probability distributions, random sampling, and collections.",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "license": "MIT",
   "repository": {
     "type": "git",

package/u_numflow.d.ts

@@ -1,5 +1,13 @@
 /* tslint:disable */
 /* eslint-disable */
+/**
+ * Output of [`estimate_lambda`]: `{ lambda, at_bound }`.
+ */
+export interface LambdaEstimateDto {
+    lambda: number;
+    at_bound: boolean;
+}
+
 
 /**
  * Apply the Box-Cox power transformation to positive data.
@@ -12,6 +20,23 @@
  */
 export function box_cox(data: Float64Array, lambda: number): Float64Array;
 
+/**
+ * Chi-squared CDF: `P(X ≤ x)` for `X ~ χ²(k)` (`0` for `x ≤ 0`).
+ *
+ * # Errors
+ * Throws if `x` is NaN or `k` is not a finite number > 0.
+ */
+export function chi_squared_cdf(x: number, k: number): number;
+
+/**
+ * Chi-squared quantile: the `x` with `P(X ≤ x) = p` for `X ~ χ²(k)`.
+ *
+ * # Errors
+ * Throws if `p` is not strictly between 0 and 1, or `k` is not a finite
+ * number > 0.
+ */
+export function chi_squared_quantile(p: number, k: number): number;
+
 /**
  * Estimate the optimal Box-Cox lambda via profile maximum likelihood.
  *
@@ -26,7 +51,32 @@ export function box_cox(data: Float64Array, lambda: number): Float64Array;
  * has fewer than 2 elements, or the range is not finite with
  * `lambda_min < lambda_max`.
  */
-export function estimate_lambda(data: Float64Array, lambda_min: number, lambda_max: number): any;
+export function estimate_lambda(data: Float64Array, lambda_min: number, lambda_max: number): LambdaEstimateDto;
+
+/**
+ * F CDF: `P(X ≤ x)` for `X ~ F(df1, df2)` (`0` for `x ≤ 0`).
+ *
+ * # Errors
+ * Throws if `x` is NaN, or `df1`/`df2` is not a finite number > 0.
+ */
+export function f_distribution_cdf(x: number, df1: number, df2: number): number;
+
+/**
+ * F quantile: the `x` with `P(X ≤ x) = p` for `X ~ F(df1, df2)`.
+ *
+ * # Errors
+ * Throws if `p` is not strictly between 0 and 1, or `df1`/`df2` is not a
+ * finite number > 0.
+ */
+export function f_distribution_quantile(p: number, df1: number, df2: number): number;
+
+/**
+ * Standard normal quantile Φ⁻¹(p): the `z` with `P(Z ≤ z) = p`.
+ *
+ * # Errors
+ * Throws if `p` is not strictly between 0 and 1.
+ */
+export function inverse_normal_cdf(p: number): number;
 
 /**
  * Arithmetic mean of `data` using Kahan compensated summation.
@@ -70,6 +120,24 @@ export function rfft(data: Float64Array): Float64Array;
  */
 export function std_dev(data: Float64Array): number;
 
+/**
+ * Student's t CDF: `P(T ≤ t)` for `T ~ t(df)`. `df` may be fractional.
+ *
+ * # Errors
+ * Throws if `t` is NaN or `df` is not a finite number > 0.
+ */
+export function t_distribution_cdf(t: number, df: number): number;
+
+/**
+ * Student's t quantile: the `t` with `P(T ≤ t) = p`. A two-sided critical
+ * value at level α is `t_distribution_quantile(1 − α/2, df)`.
+ *
+ * # Errors
+ * Throws if `p` is not strictly between 0 and 1, or `df` is not a finite
+ * number > 0.
+ */
+export function t_distribution_quantile(p: number, df: number): number;
+
 /**
  * Sample variance of `data` (Bessel-corrected, denominator n−1).
  *

package/u_numflow.js

@@ -5,5 +5,5 @@ import { __wbg_set_wasm } from "./u_numflow_bg.js";
 __wbg_set_wasm(wasm);
 wasm.__wbindgen_start();
 export {
-    box_cox, estimate_lambda, mean, normal_cdf, normal_sf, rfft, std_dev, variance
+    box_cox, chi_squared_cdf, chi_squared_quantile, estimate_lambda, f_distribution_cdf, f_distribution_quantile, inverse_normal_cdf, mean, normal_cdf, normal_sf, rfft, std_dev, t_distribution_cdf, t_distribution_quantile, variance
 } from "./u_numflow_bg.js";

package/u_numflow_bg.js

@@ -22,6 +22,41 @@ export function box_cox(data, lambda) {
     return v2;
 }
 
+/**
+ * Chi-squared CDF: `P(X ≤ x)` for `X ~ χ²(k)` (`0` for `x ≤ 0`).
+ *
+ * # Errors
+ * Throws if `x` is NaN or `k` is not a finite number > 0.
+ * @param {number} x
+ * @param {number} k
+ * @returns {number}
+ */
+export function chi_squared_cdf(x, k) {
+    const ret = wasm.chi_squared_cdf(x, k);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return ret[0];
+}
+
+/**
+ * Chi-squared quantile: the `x` with `P(X ≤ x) = p` for `X ~ χ²(k)`.
+ *
+ * # Errors
+ * Throws if `p` is not strictly between 0 and 1, or `k` is not a finite
+ * number > 0.
+ * @param {number} p
+ * @param {number} k
+ * @returns {number}
+ */
+export function chi_squared_quantile(p, k) {
+    const ret = wasm.chi_squared_quantile(p, k);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return ret[0];
+}
+
 /**
  * Estimate the optimal Box-Cox lambda via profile maximum likelihood.
  *
@@ -38,7 +73,7 @@ export function box_cox(data, lambda) {
  * @param {Float64Array} data
  * @param {number} lambda_min
  * @param {number} lambda_max
- * @returns {any}
+ * @returns {LambdaEstimateDto}
  */
 export function estimate_lambda(data, lambda_min, lambda_max) {
     const ptr0 = passArrayF64ToWasm0(data, wasm.__wbindgen_malloc);
@@ -50,6 +85,59 @@ export function estimate_lambda(data, lambda_min, lambda_max) {
     return takeFromExternrefTable0(ret[0]);
 }
 
+/**
+ * F CDF: `P(X ≤ x)` for `X ~ F(df1, df2)` (`0` for `x ≤ 0`).
+ *
+ * # Errors
+ * Throws if `x` is NaN, or `df1`/`df2` is not a finite number > 0.
+ * @param {number} x
+ * @param {number} df1
+ * @param {number} df2
+ * @returns {number}
+ */
+export function f_distribution_cdf(x, df1, df2) {
+    const ret = wasm.f_distribution_cdf(x, df1, df2);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return ret[0];
+}
+
+/**
+ * F quantile: the `x` with `P(X ≤ x) = p` for `X ~ F(df1, df2)`.
+ *
+ * # Errors
+ * Throws if `p` is not strictly between 0 and 1, or `df1`/`df2` is not a
+ * finite number > 0.
+ * @param {number} p
+ * @param {number} df1
+ * @param {number} df2
+ * @returns {number}
+ */
+export function f_distribution_quantile(p, df1, df2) {
+    const ret = wasm.f_distribution_quantile(p, df1, df2);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return ret[0];
+}
+
+/**
+ * Standard normal quantile Φ⁻¹(p): the `z` with `P(Z ≤ z) = p`.
+ *
+ * # Errors
+ * Throws if `p` is not strictly between 0 and 1.
+ * @param {number} p
+ * @returns {number}
+ */
+export function inverse_normal_cdf(p) {
+    const ret = wasm.inverse_normal_cdf(p);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return ret[0];
+}
+
 /**
  * Arithmetic mean of `data` using Kahan compensated summation.
  *
@@ -125,6 +213,42 @@ export function std_dev(data) {
     return ret;
 }
 
+/**
+ * Student's t CDF: `P(T ≤ t)` for `T ~ t(df)`. `df` may be fractional.
+ *
+ * # Errors
+ * Throws if `t` is NaN or `df` is not a finite number > 0.
+ * @param {number} t
+ * @param {number} df
+ * @returns {number}
+ */
+export function t_distribution_cdf(t, df) {
+    const ret = wasm.t_distribution_cdf(t, df);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return ret[0];
+}
+
+/**
+ * Student's t quantile: the `t` with `P(T ≤ t) = p`. A two-sided critical
+ * value at level α is `t_distribution_quantile(1 − α/2, df)`.
+ *
+ * # Errors
+ * Throws if `p` is not strictly between 0 and 1, or `df` is not a finite
+ * number > 0.
+ * @param {number} p
+ * @param {number} df
+ * @returns {number}
+ */
+export function t_distribution_quantile(p, df) {
+    const ret = wasm.t_distribution_quantile(p, df);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return ret[0];
+}
+
 /**
  * Sample variance of `data` (Bessel-corrected, denominator n−1).
  *