@iyulab/u-numflow 0.6.2 → 0.6.4

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 |
@@ -38,31 +38,34 @@ u-numflow = "0.2"
 ```
 
 ```rust
-use u_numflow::stats::OnlineStats;
-use u_numflow::distributions::{PertDistribution, Distribution};
-use u_numflow::random::Rng;
+use u_numflow::distributions::Pert;
+use u_numflow::random::{create_rng, shuffle};
+use u_numflow::stats::WelfordAccumulator;
 
-// Online statistics with numerical stability
-let mut stats = OnlineStats::new();
+// Online statistics with numerical stability (Welford)
+let mut stats = WelfordAccumulator::new();
 for x in [1.0, 2.0, 3.0, 4.0, 5.0] {
-    stats.push(x);
+    stats.update(x);
 }
-assert_eq!(stats.mean(), 3.0);
+assert_eq!(stats.mean(), Some(3.0));
 
-// PERT distribution sampling
-let pert = PertDistribution::new(1.0, 4.0, 7.0);
-let mut rng = Rng::seed_from_u64(42);
-let sample = pert.sample(&mut rng);
+// PERT distribution: moments and quantiles; sample by inverting a uniform draw
+let pert = Pert::new(1.0, 4.0, 7.0).unwrap();
+assert_eq!(pert.mean(), 4.0);
+let p90 = pert.quantile(0.9).unwrap();
+assert!(p90 > 4.0 && p90 < 7.0);
 
 // Seeded shuffling for reproducibility
+let mut rng = create_rng(42);
 let mut items = vec![1, 2, 3, 4, 5];
-u_numflow::random::shuffle(&mut items, &mut rng);
+shuffle(&mut items, &mut rng);
 
 // Box-Cox transformation (non-normal data normalization)
-use u_numflow::transforms::{estimate_lambda, box_cox};
+use u_numflow::transforms::{box_cox, estimate_lambda};
 let data = [1.0, 2.0, 4.0, 8.0, 16.0];
-let lambda = estimate_lambda(&data, -2.0, 2.0).unwrap(); // MLE via golden-section
-let transformed = box_cox(&data, lambda).unwrap();
+let fit = estimate_lambda(&data, -2.0, 2.0).unwrap(); // MLE via golden-section
+let transformed = box_cox(&data, fit.lambda).unwrap();
+assert_eq!(transformed.len(), data.len());
 
 // Discrete Fourier transform of any length
 use u_numflow::fourier::rfft;
@@ -104,22 +107,43 @@ 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:
+Every exported function declares its parameter and return types, and the
+declarations are generated from the same structs the binding reads and
+serialises, so they cannot drift from what it actually accepts and returns:
 
 ```ts
-export function estimate_lambda(data: any): LambdaEstimateDto;
+export function estimate_lambda(data: Float64Array, lambda_min: number, lambda_max: number): 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.
+Every parameter is a number or a `Float64Array`, so there is nothing to
+declare beyond what wasm-bindgen already does; the publishing workflow keeps it
+that way. The binding still validates every input at the boundary, and a
+rejected one says what was wrong.
 
 ## Related
 

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.
  *
@@ -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).
  *
@@ -158,10 +289,10 @@ function __wbg_get_imports() {
             getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
             getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
         },
-        __wbg___wbindgen_throw_5d9e815e6fdf150f: function(arg0, arg1) {
+        __wbg___wbindgen_throw_41e9ee4f547fc59a: function(arg0, arg1) {
             throw new Error(getStringFromWasm0(arg0, arg1));
         },
-        __wbg_new_bebc3f4757acf305: function() {
+        __wbg_new_617a8cdb8bb1130e: function() {
             const ret = new Object();
             return ret;
         },

package/node/u_numflow.d.cts

@@ -20,6 +20,23 @@ export interface LambdaEstimateDto {
  */
 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.
  *
@@ -36,6 +53,31 @@ export function box_cox(data: Float64Array, lambda: number): Float64Array;
  */
 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.
  *
@@ -78,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.2",
+  "version": "0.6.4",
   "license": "MIT",
   "repository": {
     "type": "git",

package/u_numflow.d.ts

@@ -20,6 +20,23 @@ export interface LambdaEstimateDto {
  */
 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.
  *
@@ -36,6 +53,31 @@ export function box_cox(data: Float64Array, lambda: number): Float64Array;
  */
 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.
  *
@@ -78,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.
  *
@@ -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).
  *
@@ -145,10 +269,10 @@ export function __wbg_String_8564e559799eccda(arg0, arg1) {
     getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
     getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
 }
-export function __wbg___wbindgen_throw_5d9e815e6fdf150f(arg0, arg1) {
+export function __wbg___wbindgen_throw_41e9ee4f547fc59a(arg0, arg1) {
     throw new Error(getStringFromWasm0(arg0, arg1));
 }
-export function __wbg_new_bebc3f4757acf305() {
+export function __wbg_new_617a8cdb8bb1130e() {
     const ret = new Object();
     return ret;
 }