@iyulab/u-numflow 0.7.0 → 0.9.0

package/node/u_numflow.d.cts

@@ -1,5 +1,18 @@
 /* tslint:disable */
 /* eslint-disable */
+/**
+ * A distribution named by `kind`, with its parameters.
+ */
+export type DistributionSpec = { kind: "uniform"; min: number; max: number } | { kind: "triangular"; min: number; mode: number; max: number } | { kind: "pert"; min: number; mode: number; max: number; lambda?: number } | { kind: "normal"; mu: number; sigma: number } | { kind: "lognormal"; mu: number; sigma: number } | { kind: "weibull"; shape: number; scale: number } | { kind: "exponential"; rate: number } | { kind: "gamma"; shape: number; rate: number } | { kind: "beta"; alpha: number; beta: number } | { kind: "chi_squared"; k: number };
+
+/**
+ * Mean and variance of a distribution.
+ */
+export interface MomentsDto {
+    mean: number;
+    variance: number;
+}
+
 /**
  * Output of [`estimate_lambda`]: `{ lambda, at_bound }`.
  */
@@ -19,7 +32,7 @@ export interface LambdaEstimateDto {
  * data contains a value ≤ 0, a NaN or infinity, or fewer than 2 elements, and
  * `invalid_transform` when a result is not finite.
  */
-export function box_cox(data: Float64Array, lambda: number): Float64Array;
+export function box_cox(data: number[] | Float64Array, lambda: number): Float64Array;
 
 /**
  * Chi-squared CDF: `P(X ≤ x)` for `X ~ χ²(k)` (`0` for `x ≤ 0`).
@@ -38,6 +51,49 @@ export function chi_squared_cdf(x: number, k: number): number;
  */
 export function chi_squared_quantile(p: number, k: number): number;
 
+/**
+ * `P(X ≤ x)` for the distribution `{ kind, ...parameters }`.
+ *
+ * # Errors
+ * As every `distribution` argument: `malformed_input` for a value that is
+ * not such an object, `unknown_option` for an unknown `kind` (with
+ * `expected`), `value_not_finite` for a NaN or infinite parameter,
+ * `parameter_out_of_range` for a parameter that must be `> 0`, and
+ * `invalid_option` for parameters out of order (`min < max`,
+ * `min ≤ mode ≤ max`). `x` NaN throws `value_not_finite`.
+ */
+export function distribution_cdf(distribution: DistributionSpec, x: number): number;
+
+/**
+ * Mean and variance of `distribution` — also the way to check a
+ * specification before using it.
+ *
+ * # Errors
+ * As [`distribution_cdf`] for `distribution`.
+ */
+export function distribution_moments(distribution: DistributionSpec): MomentsDto;
+
+/**
+ * The `x` with `P(X ≤ x) = p`.
+ *
+ * # Errors
+ * As [`distribution_cdf`] for `distribution`; `p` outside `(0, 1)` throws
+ * `parameter_out_of_range`.
+ */
+export function distribution_quantile(distribution: DistributionSpec, p: number): number;
+
+/**
+ * `n` random variates, reproducible from `seed`: the same `(distribution, n,
+ * seed)` always returns the same values. Uniforms are drawn from the open
+ * interval (0, 1), so no variate is infinite.
+ *
+ * # Errors
+ * As [`distribution_cdf`] for `distribution`; `n` not a whole number in
+ * `[0, 2³² − 1]` or `seed` not a whole number in `[0, 2⁵³]` throws
+ * `parameter_out_of_range`.
+ */
+export function distribution_sample(distribution: DistributionSpec, n: number, seed: number): Float64Array;
+
 /**
  * Estimate the optimal Box-Cox lambda via profile maximum likelihood.
  *
@@ -51,7 +107,7 @@ export function chi_squared_quantile(p: number, k: number): number;
  * Throws as [`box_cox`] does for the data, and `invalid_lambda_range` when the
  * range is not finite with `lambda_min < lambda_max`.
  */
-export function estimate_lambda(data: Float64Array, lambda_min: number, lambda_max: number): LambdaEstimateDto;
+export function estimate_lambda(data: number[] | Float64Array, lambda_min: number, lambda_max: number): LambdaEstimateDto;
 
 /**
  * F CDF: `P(X ≤ x)` for `X ~ F(df1, df2)` (`0` for `x ≤ 0`).
@@ -70,6 +126,53 @@ export function f_distribution_cdf(x: number, df1: number, df2: number): number;
  */
 export function f_distribution_quantile(p: number, df1: number, df2: number): number;
 
+/**
+ * Points in `a` but not in `b`, in normal form — e.g. a reporting window
+ * minus down-time is up-time.
+ *
+ * # Errors
+ * As [`interval_normalize`], naming `a` or `b`.
+ */
+export function interval_difference(a: [number, number][], b: [number, number][]): [number, number][];
+
+/**
+ * Points in both `a` and `b`, in normal form. Clipping to a window is
+ * `interval_intersection(a, [[from, to]])`.
+ *
+ * # Errors
+ * As [`interval_normalize`], naming `a` or `b`.
+ */
+export function interval_intersection(a: [number, number][], b: [number, number][]): [number, number][];
+
+/**
+ * Total length of the union of `intervals`: each point counts once, however
+ * many rows cover it.
+ *
+ * # Errors
+ * As [`interval_normalize`].
+ */
+export function interval_measure(intervals: [number, number][]): number;
+
+/**
+ * The union of `intervals` (each `[start, end]`, half-open) in normal form:
+ * sorted, disjoint, touching pieces merged, empty ones dropped.
+ *
+ * # Errors
+ * Throws `malformed_input` for a row that is not two numbers (`parameter` is
+ * the row's path, e.g. `intervals[2]`), `value_not_finite` for a NaN or
+ * ±Infinity bound, and `reversed_interval` (`parameter`, `index`) for a row
+ * with start > end — reversed rows are refused, not swapped.
+ */
+export function interval_normalize(intervals: [number, number][]): [number, number][];
+
+/**
+ * Points in `a` or `b`, in normal form.
+ *
+ * # Errors
+ * As [`interval_normalize`], naming `a` or `b`.
+ */
+export function interval_union(a: [number, number][], b: [number, number][]): [number, number][];
+
 /**
  * Standard normal quantile Φ⁻¹(p): the `z` with `P(Z ≤ z) = p`.
  *
@@ -81,9 +184,11 @@ export function inverse_normal_cdf(p: number): number;
 /**
  * Arithmetic mean of `data` using Kahan compensated summation.
  *
- * Returns `NaN` if `data` is empty or contains non-finite values.
+ * # Errors
+ * Throws `empty_input` when `data` is empty, and as every `data` argument
+ * does for an element that is not a finite number.
  */
-export function mean(data: Float64Array): number;
+export function mean(data: number[] | Float64Array): number;
 
 /**
  * Standard normal CDF Φ(x) = P(Z ≤ x) for Z ~ N(0, 1).
@@ -110,15 +215,20 @@ export function normal_sf(x: number): number;
  * Returns the `n` complex bins interleaved as `[re0, im0, re1, im1, …]`
  * (length `2n`). Bins `k` and `n − k` are conjugates, so the spectrum of a
  * real signal is fully described by bins `0..=n/2`.
+ *
+ * # Errors
+ * Throws as every `data` argument does for an element that is not a finite
+ * number.
  */
-export function rfft(data: Float64Array): Float64Array;
+export function rfft(data: number[] | Float64Array): Float64Array;
 
 /**
  * Sample standard deviation of `data` (Bessel-corrected, denominator n−1).
  *
- * Returns `NaN` if `data` has fewer than 2 elements or contains non-finite values.
+ * # Errors
+ * Throws `insufficient_data` below 2 values.
  */
-export function std_dev(data: Float64Array): number;
+export function std_dev(data: number[] | Float64Array): number;
 
 /**
  * Student's t CDF: `P(T ≤ t)` for `T ~ t(df)`. `df` may be fractional.
@@ -141,6 +251,7 @@ export function t_distribution_quantile(p: number, df: number): number;
 /**
  * Sample variance of `data` (Bessel-corrected, denominator n−1).
  *
- * Returns `NaN` if `data` has fewer than 2 elements or contains non-finite values.
+ * # Errors
+ * Throws `insufficient_data` below 2 values.
  */
-export function variance(data: Float64Array): number;
+export function variance(data: number[] | Float64Array): number;

package/package.json

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

package/u_numflow.d.ts

@@ -1,5 +1,18 @@
 /* tslint:disable */
 /* eslint-disable */
+/**
+ * A distribution named by `kind`, with its parameters.
+ */
+export type DistributionSpec = { kind: "uniform"; min: number; max: number } | { kind: "triangular"; min: number; mode: number; max: number } | { kind: "pert"; min: number; mode: number; max: number; lambda?: number } | { kind: "normal"; mu: number; sigma: number } | { kind: "lognormal"; mu: number; sigma: number } | { kind: "weibull"; shape: number; scale: number } | { kind: "exponential"; rate: number } | { kind: "gamma"; shape: number; rate: number } | { kind: "beta"; alpha: number; beta: number } | { kind: "chi_squared"; k: number };
+
+/**
+ * Mean and variance of a distribution.
+ */
+export interface MomentsDto {
+    mean: number;
+    variance: number;
+}
+
 /**
  * Output of [`estimate_lambda`]: `{ lambda, at_bound }`.
  */
@@ -19,7 +32,7 @@ export interface LambdaEstimateDto {
  * data contains a value ≤ 0, a NaN or infinity, or fewer than 2 elements, and
  * `invalid_transform` when a result is not finite.
  */
-export function box_cox(data: Float64Array, lambda: number): Float64Array;
+export function box_cox(data: number[] | Float64Array, lambda: number): Float64Array;
 
 /**
  * Chi-squared CDF: `P(X ≤ x)` for `X ~ χ²(k)` (`0` for `x ≤ 0`).
@@ -38,6 +51,49 @@ export function chi_squared_cdf(x: number, k: number): number;
  */
 export function chi_squared_quantile(p: number, k: number): number;
 
+/**
+ * `P(X ≤ x)` for the distribution `{ kind, ...parameters }`.
+ *
+ * # Errors
+ * As every `distribution` argument: `malformed_input` for a value that is
+ * not such an object, `unknown_option` for an unknown `kind` (with
+ * `expected`), `value_not_finite` for a NaN or infinite parameter,
+ * `parameter_out_of_range` for a parameter that must be `> 0`, and
+ * `invalid_option` for parameters out of order (`min < max`,
+ * `min ≤ mode ≤ max`). `x` NaN throws `value_not_finite`.
+ */
+export function distribution_cdf(distribution: DistributionSpec, x: number): number;
+
+/**
+ * Mean and variance of `distribution` — also the way to check a
+ * specification before using it.
+ *
+ * # Errors
+ * As [`distribution_cdf`] for `distribution`.
+ */
+export function distribution_moments(distribution: DistributionSpec): MomentsDto;
+
+/**
+ * The `x` with `P(X ≤ x) = p`.
+ *
+ * # Errors
+ * As [`distribution_cdf`] for `distribution`; `p` outside `(0, 1)` throws
+ * `parameter_out_of_range`.
+ */
+export function distribution_quantile(distribution: DistributionSpec, p: number): number;
+
+/**
+ * `n` random variates, reproducible from `seed`: the same `(distribution, n,
+ * seed)` always returns the same values. Uniforms are drawn from the open
+ * interval (0, 1), so no variate is infinite.
+ *
+ * # Errors
+ * As [`distribution_cdf`] for `distribution`; `n` not a whole number in
+ * `[0, 2³² − 1]` or `seed` not a whole number in `[0, 2⁵³]` throws
+ * `parameter_out_of_range`.
+ */
+export function distribution_sample(distribution: DistributionSpec, n: number, seed: number): Float64Array;
+
 /**
  * Estimate the optimal Box-Cox lambda via profile maximum likelihood.
  *
@@ -51,7 +107,7 @@ export function chi_squared_quantile(p: number, k: number): number;
  * Throws as [`box_cox`] does for the data, and `invalid_lambda_range` when the
  * range is not finite with `lambda_min < lambda_max`.
  */
-export function estimate_lambda(data: Float64Array, lambda_min: number, lambda_max: number): LambdaEstimateDto;
+export function estimate_lambda(data: number[] | Float64Array, lambda_min: number, lambda_max: number): LambdaEstimateDto;
 
 /**
  * F CDF: `P(X ≤ x)` for `X ~ F(df1, df2)` (`0` for `x ≤ 0`).
@@ -70,6 +126,53 @@ export function f_distribution_cdf(x: number, df1: number, df2: number): number;
  */
 export function f_distribution_quantile(p: number, df1: number, df2: number): number;
 
+/**
+ * Points in `a` but not in `b`, in normal form — e.g. a reporting window
+ * minus down-time is up-time.
+ *
+ * # Errors
+ * As [`interval_normalize`], naming `a` or `b`.
+ */
+export function interval_difference(a: [number, number][], b: [number, number][]): [number, number][];
+
+/**
+ * Points in both `a` and `b`, in normal form. Clipping to a window is
+ * `interval_intersection(a, [[from, to]])`.
+ *
+ * # Errors
+ * As [`interval_normalize`], naming `a` or `b`.
+ */
+export function interval_intersection(a: [number, number][], b: [number, number][]): [number, number][];
+
+/**
+ * Total length of the union of `intervals`: each point counts once, however
+ * many rows cover it.
+ *
+ * # Errors
+ * As [`interval_normalize`].
+ */
+export function interval_measure(intervals: [number, number][]): number;
+
+/**
+ * The union of `intervals` (each `[start, end]`, half-open) in normal form:
+ * sorted, disjoint, touching pieces merged, empty ones dropped.
+ *
+ * # Errors
+ * Throws `malformed_input` for a row that is not two numbers (`parameter` is
+ * the row's path, e.g. `intervals[2]`), `value_not_finite` for a NaN or
+ * ±Infinity bound, and `reversed_interval` (`parameter`, `index`) for a row
+ * with start > end — reversed rows are refused, not swapped.
+ */
+export function interval_normalize(intervals: [number, number][]): [number, number][];
+
+/**
+ * Points in `a` or `b`, in normal form.
+ *
+ * # Errors
+ * As [`interval_normalize`], naming `a` or `b`.
+ */
+export function interval_union(a: [number, number][], b: [number, number][]): [number, number][];
+
 /**
  * Standard normal quantile Φ⁻¹(p): the `z` with `P(Z ≤ z) = p`.
  *
@@ -81,9 +184,11 @@ export function inverse_normal_cdf(p: number): number;
 /**
  * Arithmetic mean of `data` using Kahan compensated summation.
  *
- * Returns `NaN` if `data` is empty or contains non-finite values.
+ * # Errors
+ * Throws `empty_input` when `data` is empty, and as every `data` argument
+ * does for an element that is not a finite number.
  */
-export function mean(data: Float64Array): number;
+export function mean(data: number[] | Float64Array): number;
 
 /**
  * Standard normal CDF Φ(x) = P(Z ≤ x) for Z ~ N(0, 1).
@@ -110,15 +215,20 @@ export function normal_sf(x: number): number;
  * Returns the `n` complex bins interleaved as `[re0, im0, re1, im1, …]`
  * (length `2n`). Bins `k` and `n − k` are conjugates, so the spectrum of a
  * real signal is fully described by bins `0..=n/2`.
+ *
+ * # Errors
+ * Throws as every `data` argument does for an element that is not a finite
+ * number.
  */
-export function rfft(data: Float64Array): Float64Array;
+export function rfft(data: number[] | Float64Array): Float64Array;
 
 /**
  * Sample standard deviation of `data` (Bessel-corrected, denominator n−1).
  *
- * Returns `NaN` if `data` has fewer than 2 elements or contains non-finite values.
+ * # Errors
+ * Throws `insufficient_data` below 2 values.
  */
-export function std_dev(data: Float64Array): number;
+export function std_dev(data: number[] | Float64Array): number;
 
 /**
  * Student's t CDF: `P(T ≤ t)` for `T ~ t(df)`. `df` may be fractional.
@@ -141,6 +251,7 @@ export function t_distribution_quantile(p: number, df: number): number;
 /**
  * Sample variance of `data` (Bessel-corrected, denominator n−1).
  *
- * Returns `NaN` if `data` has fewer than 2 elements or contains non-finite values.
+ * # Errors
+ * Throws `insufficient_data` below 2 values.
  */
-export function variance(data: Float64Array): number;
+export function variance(data: number[] | Float64Array): number;

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, 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
+    box_cox, chi_squared_cdf, chi_squared_quantile, distribution_cdf, distribution_moments, distribution_quantile, distribution_sample, estimate_lambda, f_distribution_cdf, f_distribution_quantile, interval_difference, interval_intersection, interval_measure, interval_normalize, interval_union, inverse_normal_cdf, mean, normal_cdf, normal_sf, rfft, std_dev, t_distribution_cdf, t_distribution_quantile, variance
 } from "./u_numflow_bg.js";