@iyulab/u-numflow 0.13.1 → 0.14.1

package/README.md

@@ -24,6 +24,7 @@ u-numflow provides foundational mathematical, statistical, and probabilistic bui
 | `random` | Seeded RNG, Fisher-Yates shuffle, weighted sampling, random subset selection |
 | `distributions::Sample` | Random variates from every continuous distribution — `sample(&mut rng)` and reproducible `sample_n(n, seed)`; inversion where the quantile is direct, Marsaglia–Tsang for the gamma family (Gamma, χ², Beta, PERT); uniforms from the open interval (0, 1), so no variate is infinite |
 | `collections` | Specialized data structures: Union-Find with path compression and union-by-rank; `IntervalSet` — unions of half-open intervals with union, intersection, difference, clip and a measure that counts overlapping input once |
+| `units` | Units of measure: dimensional analysis over the seven SI base quantities, UCUM-syntax unit expressions (`kW.h`, `m/s2`, `J/(kg.K)`), conversion of readings (with a scale's offset — 20 °C is 293.15 K) and of differences (without — a rise of 20 °C is a rise of 20 K); the SI built in, every other unit defined by the caller |
 
 ## Design Philosophy
 
@@ -35,7 +36,7 @@ u-numflow provides foundational mathematical, statistical, and probabilistic bui
 
 ```toml
 [dependencies]
-u-numflow = "0.13"
+u-numflow = "0.14"
 ```
 
 ```rust
@@ -86,6 +87,31 @@ let up = week.difference(&planned.union(&unplanned));
 assert_eq!(up.measure(), 138.0);
 ```
 
+```rust
+// Units: the SI is built in; a unit whose size varies by convention is yours to define
+use u_numflow::units::Units;
+let mut units = Units::si();
+units.define("cal_IT", 4.1868, "J", 0.0).unwrap(); // the international calorie
+units.define("toe", 1e7, "kcal_IT", 0.0).unwrap();  // tonne of oil equivalent
+assert!((units.convert(1.0, "toe", "GJ").unwrap() - 41.868).abs() < 1e-9);
+assert!((units.convert(20.0, "Cel", "K").unwrap() - 293.15).abs() < 1e-9); // a reading
+assert_eq!(units.convert_difference(20.0, "Cel", "K").unwrap(), 20.0);    // a change
+assert!(units.convert(1.0, "m3", "kg").is_err());                         // volume is not mass
+```
+
+Unit expressions follow UCUM's case-sensitive syntax: an atom with an optional
+decimal prefix (`km`, `kW`, `uA` — `u` is micro), an integer exponent after it
+(`m3`, `s-2`), `.` for a product and `/` for a quotient read left to right
+(`kg/m.s` is `(kg/m)·s`), parentheses, integer factors (`1000.m`), and `{…}`
+annotations, which have no effect (`m3{gas}`). Built in: the SI base units
+(`m`, `g`, `s`, `A`, `K`, `mol`, `cd`), the 22 derived units with special names
+(`N`, `Pa`, `J`, `W`, `Cel`, …), `min`, `h`, `d`, `L`/`l`, `t`, and the prefixes
+`Q` … `q`. No unit table beyond the SI is embedded: the calorie (three
+definitions, up to 0.07 % apart), the tonne of oil equivalent, imperial units
+and the normal cubic metre are the caller's `define` calls, so the crate never
+picks one convention silently. A scale with an offset (`Cel`) stands alone — a
+prefix, exponent or product on it is refused.
+
 `IntervalSet<T>` works over `f32`, `f64` and every primitive integer type. Its
 measure has the type of a distance — the unsigned type of the same width for
 integers (as `i64::abs_diff` returns `u64`), so it cannot overflow. A reversed
@@ -114,8 +140,8 @@ MIT License — see [LICENSE](LICENSE).
 dotnet add package UNumflow
 ```
 
-The distributions (CDF, quantile, moments, seeded sampling) and interval sets,
-backed by this crate through its C ABI (the `ffi` feature) — see
+The distributions (CDF, quantile, moments, seeded sampling), sample statistics
+(median, R-7 quantiles), interval sets and units, backed by this crate through its C ABI (the `ffi` feature) — see
 [bindings/csharp/README.md](bindings/csharp/README.md). Refusals carry the same
 `code` and fields as the WebAssembly binding's.
 
@@ -137,7 +163,7 @@ file with an ES module import, which browsers refuse (`application/wasm` is not
 module script type), so `<script type="module">` from a CDN fails, and CDN
 re-bundling services fail on the same import. Use a bundler or Node.
 
-Exported functions: `mean`, `std_dev`, `variance`, `normal_cdf`, `normal_sf` (upper tail `P(Z > x)`, computed directly so tail probabilities keep ~15 significant digits), `box_cox`, `estimate_lambda` (returns `{ lambda, at_bound }` — `at_bound` is `true` when the likelihood was still rising at an end of the search range, so `lambda` is that limit), and
+Exported functions: `mean`, `std_dev`, `variance`, `median`, `quantiles(data, probabilities) -> Float64Array` (sample quantiles in the order asked, R-7 linear interpolation — the default of R, NumPy and Excel — with one sort for all of them), `normal_cdf`, `normal_sf` (upper tail `P(Z > x)`, computed directly so tail probabilities keep ~15 significant digits), `box_cox`, `estimate_lambda` (returns `{ lambda, at_bound }` — `at_bound` is `true` when the likelihood was still rising at an end of the search range, so `lambda` is that limit), and
 `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).
 
@@ -146,6 +172,8 @@ element that is not a number (`null`, `undefined`, a string) throws `malformed_i
 and a NaN or ±Infinity throws `value_not_finite`, each with the element's `index` —
 `mean([1, null, 3])` throws rather than averaging the `null` as 0. `mean` of no values
 throws `empty_input`; `std_dev` and `variance` of fewer than 2 throw `insufficient_data`.
+`median` and `quantiles` of no values throw `empty_input`; a probability outside `[0, 1]`
+throws `parameter_out_of_range` with `parameter` `probabilities[i]`, `min` 0 and `max` 1.
 
 Distribution functions for critical values and p-values — each returns a `number` and
 **throws** (an `Error` naming the argument — see *Errors* below) when an argument is outside the domain,
@@ -210,6 +238,35 @@ const up = interval_difference([[0, 168]], down);          // [[30, 168]]
 console.log(interval_measure(up));                         // 138
 ```
 
+Units of measure — `from`, `to` and `unit` are unit expressions (UCUM syntax, see the
+Rust section above) over the SI and the optional `definitions`, an array of
+`UnitDefinitionSpec` `{ symbol, unit, factor?, offset? }` (`symbol` = `factor` × `unit`,
+plus `offset` SI units at its zero; `factor` defaults to 1, `offset` to 0; a definition
+may use the ones before it):
+
+| Function | Returns |
+|---|---|
+| `unit_convert(value, from, to, definitions?)` | A reading converted — 20 `Cel` is 293.15 `K` |
+| `unit_convert_difference(value, from, to, definitions?)` | An amount of change converted — the offset cancels: a rise of 20 `Cel` is a rise of 20 `K` |
+| `unit_info(unit, definitions?)` | `UnitInfo` `{ dimension, exponents, scale, offset }` — the dimension in SI base units (`"kg.m2.s-2"`; exponents of m, kg, s, A, K, mol, cd) and `value_in_si = value · scale + offset`. Two units convert into each other exactly when their dimensions are equal |
+
+```js
+const { unit_convert, unit_convert_difference, unit_info } = require("@iyulab/u-numflow");
+const energy = [
+  { symbol: "cal_IT", unit: "J", factor: 4.1868 },
+  { symbol: "toe", unit: "kcal_IT", factor: 1e7 },
+];
+console.log(unit_convert(1, "Gcal_IT", "GJ", energy));     // 4.1868
+console.log(unit_convert(20, "Cel", "K"));                 // 293.15
+console.log(unit_convert_difference(20, "Cel", "K"));      // 20
+console.log(unit_info("toe", energy).dimension);           // "kg.m2.s-2"
+try {
+  unit_convert(1, "m3", "kg");
+} catch (err) {
+  console.log(err.code, err.parameter, err.expected, err.got); // dimension_mismatch to m3 kg
+}
+```
+
 `codes()` returns every refusal `code` the functions throw, with the fields that
 can come with it — `{ refusals: [{ code, fields }], violations: [] }` — built from
 the table the refusals come from; the table below explains each. The C library
@@ -231,11 +288,15 @@ try {
 
 | `code` | Fields | Meaning |
 |---|---|---|
-| `parameter_out_of_range` | `parameter`, `min`, `max`, `got`; `exclusive_min` / `exclusive_max` on an open end | `p` not strictly inside (0, 1) (`exclusive_min` 0, `exclusive_max` 1), or a degrees of freedom that is not a finite number `> 0` (`exclusive_min` 0); a distribution parameter that must be `> 0` (`exclusive_min` 0; `parameter` is its path, e.g. `distribution.sigma`), or that falls outside the range the others leave it: `distribution.max` not above `min` (`exclusive_min` = `min`), `distribution.mode` outside `[min, max]` (`min`, `max`); `estimate_lambda`'s `lambda_min` not below `lambda_max` (`exclusive_max` = `lambda_max`); a whole `n` or `seed` outside its range, a negative one included (`min` 0, `max`) |
+| `parameter_out_of_range` | `parameter`, `min`, `max`, `got`; `exclusive_min` / `exclusive_max` on an open end | `p` not strictly inside (0, 1) (`exclusive_min` 0, `exclusive_max` 1), or a degrees of freedom that is not a finite number `> 0` (`exclusive_min` 0); a distribution parameter that must be `> 0` (`exclusive_min` 0; `parameter` is its path, e.g. `distribution.sigma`), or that falls outside the range the others leave it: `distribution.max` not above `min` (`exclusive_min` = `min`), `distribution.mode` outside `[min, max]` (`min`, `max`); `estimate_lambda`'s `lambda_min` not below `lambda_max` (`exclusive_max` = `lambda_max`); a whole `n` or `seed` outside its range, a negative one included (`min` 0, `max`); a unit definition's `factor` not `> 0` (`parameter` `definitions[i].factor`, `exclusive_min` 0) |
 | `unknown_option` | `parameter`, `got`, `expected` | A `distribution.kind` the crate does not have |
-| `malformed_input` | `parameter`, `index` (or absent) | A `data` argument that is not an array or `Float64Array`, or an element that is not a number; a `distribution` that is not an object with a string `kind`, lacks a parameter or has one its kind does not take; an interval row that is not two numbers (`parameter` is its path, e.g. `a[2]`); an `n` or `seed` with a fraction ("must be a whole number") |
+| `malformed_input` | `parameter`, `index` (or absent) | A `data` argument that is not an array or `Float64Array`, or an element that is not a number; a `distribution` that is not an object with a string `kind`, lacks a parameter or has one its kind does not take; an interval row that is not two numbers (`parameter` is its path, e.g. `a[2]`); an `n` or `seed` with a fraction ("must be a whole number"); a unit expression that does not parse (`from`, `to`, `unit`, `definitions[i].unit`), a definition symbol that is empty, starts with a digit or holds an operator character (`definitions[i].symbol`), or a definition of the wrong shape (`definitions[i]`) |
+| `unknown_unit` | `parameter`, `got` | A unit symbol that is neither built in nor defined, nor a prefix on one — `got` is the symbol (`hr` in `kW.hr`) |
+| `dimension_mismatch` | `parameter`, `expected`, `got` | `unit_convert` between units of different dimensions — `parameter` is `to`, `expected` the dimension of `from` and `got` that of `to`, both in SI base units (`m3`, `kg`) |
+| `invalid_option` | `parameter` | A scale with an offset (`Cel`, or a defined one) given a prefix, an exponent or a product — it has a meaning only alone |
+| `duplicate_id` | `parameter`, `id`, `index` | A unit definition whose `symbol` is already a unit (built in or defined before) — `index` is the definition's position |
 | `reversed_interval` | `parameter`, `index` | An interval row with start > end — refused, not swapped |
-| `value_not_finite` | `parameter`, `index` for an array element | A NaN argument, an infinite `n`, `seed`, `lambda_min` or `lambda_max`, or a NaN or infinity in any `data` array or interval row (`parameter` is the row's path) |
+| `value_not_finite` | `parameter`, `index` for an array element | A NaN argument, an infinite `n`, `seed`, `lambda_min` or `lambda_max`, or a NaN or infinity in any `data` array or interval row (`parameter` is the row's path); a NaN or infinite `value` to convert or definition `factor` / `offset` |
 | `empty_input` | `parameter` | `mean` of no values |
 | `non_positive_data` | `parameter`, `index`, `got` | Box-Cox data with a value `≤ 0` — `index` is the first such value |
 | `insufficient_data` | `parameter`, `min`, `got` | Fewer values than the function needs (`std_dev`/`variance` 2, Box-Cox 2) |

package/node/u_numflow.cjs

@@ -362,6 +362,23 @@ function mean(data) {
 }
 exports.mean = mean;
 
+/**
+ * Median of the sample `data` (even length: the mean of the middle two).
+ *
+ * # Errors
+ * Throws `empty_input` when `data` is empty.
+ * @param {number[] | Float64Array} data
+ * @returns {number}
+ */
+function median(data) {
+    const ret = wasm.median(data);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return ret[0];
+}
+exports.median = median;
+
 /**
  * Standard normal CDF Φ(x) = P(Z ≤ x) for Z ~ N(0, 1).
  *
@@ -393,6 +410,30 @@ function normal_sf(x) {
 }
 exports.normal_sf = normal_sf;
 
+/**
+ * Sample quantiles of `data` at each of `probabilities`, in the order asked
+ * — R-7 linear interpolation (Hyndman & Fan 1996; the default of R, NumPy
+ * and Excel), sorting the sample once.
+ *
+ * # Errors
+ * Throws `empty_input` when `data` is empty, and `parameter_out_of_range`
+ * (`parameter` `probabilities[i]`, `min` 0, `max` 1) for a probability
+ * outside `[0, 1]`.
+ * @param {number[] | Float64Array} data
+ * @param {number[] | Float64Array} probabilities
+ * @returns {Float64Array}
+ */
+function quantiles(data, probabilities) {
+    const ret = wasm.quantiles(data, probabilities);
+    if (ret[3]) {
+        throw takeFromExternrefTable0(ret[2]);
+    }
+    var v1 = getArrayF64FromWasm0(ret[0], ret[1]).slice();
+    wasm.__wbindgen_free(ret[0], ret[1] * 8, 8);
+    return v1;
+}
+exports.quantiles = quantiles;
+
 /**
  * Forward DFT of a real sequence of any length.
  *
@@ -472,6 +513,89 @@ function t_distribution_quantile(p, df) {
 }
 exports.t_distribution_quantile = t_distribution_quantile;
 
+/**
+ * A reading `value` in the unit `from`, in the unit `to`: 20 `Cel` is
+ * 293.15 `K`. Units are UCUM expressions (`kW.h`, `m/s2`, `J/(kg.K)`) over
+ * the SI and the `definitions` given — e.g.
+ * `[{ symbol: "cal_IT", unit: "J", factor: 4.1868 }]`.
+ *
+ * # Errors
+ * `value_not_finite` (`parameter` `value`); `malformed_input` for an
+ * expression that does not parse or a definition of the wrong shape;
+ * `unknown_unit` (`parameter`, `got` = the symbol); `invalid_option` for a
+ * scale such as `Cel` with a prefix, exponent or product;
+ * `dimension_mismatch` (`parameter` `to`, `expected` = the dimension of
+ * `from`, `got` = that of `to`, both in SI base units); for a definition,
+ * `duplicate_id` (`id`, `index`) for a symbol already a unit and
+ * `parameter_out_of_range` for a `factor` not `> 0`, each at
+ * `definitions[i].…`.
+ * @param {number} value
+ * @param {string} from
+ * @param {string} to
+ * @param {UnitDefinitionSpec[] | null} [definitions]
+ * @returns {number}
+ */
+function unit_convert(value, from, to, definitions) {
+    const ptr0 = passStringToWasm0(from, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passStringToWasm0(to, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    const ret = wasm.unit_convert(value, ptr0, len0, ptr1, len1, isLikeNone(definitions) ? 0 : addToExternrefTable0(definitions));
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return ret[0];
+}
+exports.unit_convert = unit_convert;
+
+/**
+ * An amount of change `value` in `from`, in `to`: the offset of a scale
+ * cancels, so a rise of 20 `Cel` is a rise of 20 `K`.
+ *
+ * # Errors
+ * As [`unit_convert`].
+ * @param {number} value
+ * @param {string} from
+ * @param {string} to
+ * @param {UnitDefinitionSpec[] | null} [definitions]
+ * @returns {number}
+ */
+function unit_convert_difference(value, from, to, definitions) {
+    const ptr0 = passStringToWasm0(from, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passStringToWasm0(to, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    const ret = wasm.unit_convert_difference(value, ptr0, len0, ptr1, len1, isLikeNone(definitions) ? 0 : addToExternrefTable0(definitions));
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return ret[0];
+}
+exports.unit_convert_difference = unit_convert_difference;
+
+/**
+ * What the unit expression `unit` stands for: its dimension in SI base units
+ * (`"kg.m2.s-2"`, with the exponents of m, kg, s, A, K, mol, cd), and
+ * `scale` / `offset` with `value_in_si = value · scale + offset`. Two units
+ * convert into each other exactly when their dimensions are equal.
+ *
+ * # Errors
+ * As [`unit_convert`] for `unit` (at `parameter` `unit`) and `definitions`.
+ * @param {string} unit
+ * @param {UnitDefinitionSpec[] | null} [definitions]
+ * @returns {UnitInfo}
+ */
+function unit_info(unit, definitions) {
+    const ptr0 = passStringToWasm0(unit, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.unit_info(ptr0, len0, isLikeNone(definitions) ? 0 : addToExternrefTable0(definitions));
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+exports.unit_info = unit_info;
+
 /**
  * Sample variance of `data` (Bessel-corrected, denominator n−1).
  *
@@ -541,6 +665,10 @@ function __wbg_get_imports() {
             const ret = typeof(val) === 'object' && val !== null;
             return ret;
         },
+        __wbg___wbindgen_is_undefined_8865fb403f8fe9d8: function(arg0) {
+            const ret = arg0 === undefined;
+            return ret;
+        },
         __wbg___wbindgen_jsval_eq_02babf21faa37971: function(arg0, arg1) {
             const ret = arg0 === arg1;
             return ret;
@@ -598,6 +726,10 @@ function __wbg_get_imports() {
             const ret = arg0[arg1 >>> 0];
             return ret;
         },
+        __wbg_get_with_ref_key_6412cf3094599694: function(arg0, arg1) {
+            const ret = arg0[arg1];
+            return ret;
+        },
         __wbg_instanceof_ArrayBuffer_a99f175873e5d9b8: function(arg0) {
             let result;
             try {

package/node/u_numflow.d.cts

@@ -14,6 +14,29 @@ export interface RefusalCode {
     fields: string[];
 }
 
+/**
+ * A unit the caller defines: `symbol` = `factor` × `unit` (+ `offset` SI
+ * units at its zero, for a scale such as a Fahrenheit degree).
+ */
+export interface UnitDefinitionSpec {
+    /**
+     * The new symbol, e.g. `cal_IT`.
+     */
+    symbol: string;
+    /**
+     * What it is a multiple of, as a unit expression, e.g. `J`.
+     */
+    unit: string;
+    /**
+     * How many `unit` one `symbol` is (default 1, `> 0`).
+     */
+    factor?: number;
+    /**
+     * SI value at the symbol's zero (default 0).
+     */
+    offset?: number;
+}
+
 /**
  * A violation a checker reports. This package has no checker; the type is
  * here so every engine's [`Codes`] has one shape.
@@ -40,6 +63,28 @@ export interface LambdaEstimateDto {
     at_bound: boolean;
 }
 
+/**
+ * What a unit expression stands for.
+ */
+export interface UnitInfo {
+    /**
+     * The dimension in SI base units, e.g. `kg.m2.s-2` (`1` for a pure number).
+     */
+    dimension: string;
+    /**
+     * Exponents of m, kg, s, A, K, mol, cd.
+     */
+    exponents: [number, number, number, number, number, number, number];
+    /**
+     * Size of one unit in coherent SI units.
+     */
+    scale: number;
+    /**
+     * SI value of the unit's zero (0 except for scales such as `Cel`).
+     */
+    offset: number;
+}
+
 /**
  * What this package can answer with besides a result: every refusal
  * `code`, and no violations -- it has no checker.
@@ -231,6 +276,14 @@ export function inverse_normal_cdf(p: number): number;
  */
 export function mean(data: number[] | Float64Array): number;
 
+/**
+ * Median of the sample `data` (even length: the mean of the middle two).
+ *
+ * # Errors
+ * Throws `empty_input` when `data` is empty.
+ */
+export function median(data: number[] | Float64Array): number;
+
 /**
  * Standard normal CDF Φ(x) = P(Z ≤ x) for Z ~ N(0, 1).
  *
@@ -250,6 +303,18 @@ export function normal_cdf(x: number): number;
  */
 export function normal_sf(x: number): number;
 
+/**
+ * Sample quantiles of `data` at each of `probabilities`, in the order asked
+ * — R-7 linear interpolation (Hyndman & Fan 1996; the default of R, NumPy
+ * and Excel), sorting the sample once.
+ *
+ * # Errors
+ * Throws `empty_input` when `data` is empty, and `parameter_out_of_range`
+ * (`parameter` `probabilities[i]`, `min` 0, `max` 1) for a probability
+ * outside `[0, 1]`.
+ */
+export function quantiles(data: number[] | Float64Array, probabilities: number[] | Float64Array): Float64Array;
+
 /**
  * Forward DFT of a real sequence of any length.
  *
@@ -289,6 +354,45 @@ export function t_distribution_cdf(t: number, df: number): number;
  */
 export function t_distribution_quantile(p: number, df: number): number;
 
+/**
+ * A reading `value` in the unit `from`, in the unit `to`: 20 `Cel` is
+ * 293.15 `K`. Units are UCUM expressions (`kW.h`, `m/s2`, `J/(kg.K)`) over
+ * the SI and the `definitions` given — e.g.
+ * `[{ symbol: "cal_IT", unit: "J", factor: 4.1868 }]`.
+ *
+ * # Errors
+ * `value_not_finite` (`parameter` `value`); `malformed_input` for an
+ * expression that does not parse or a definition of the wrong shape;
+ * `unknown_unit` (`parameter`, `got` = the symbol); `invalid_option` for a
+ * scale such as `Cel` with a prefix, exponent or product;
+ * `dimension_mismatch` (`parameter` `to`, `expected` = the dimension of
+ * `from`, `got` = that of `to`, both in SI base units); for a definition,
+ * `duplicate_id` (`id`, `index`) for a symbol already a unit and
+ * `parameter_out_of_range` for a `factor` not `> 0`, each at
+ * `definitions[i].…`.
+ */
+export function unit_convert(value: number, from: string, to: string, definitions?: UnitDefinitionSpec[] | null): number;
+
+/**
+ * An amount of change `value` in `from`, in `to`: the offset of a scale
+ * cancels, so a rise of 20 `Cel` is a rise of 20 `K`.
+ *
+ * # Errors
+ * As [`unit_convert`].
+ */
+export function unit_convert_difference(value: number, from: string, to: string, definitions?: UnitDefinitionSpec[] | null): number;
+
+/**
+ * What the unit expression `unit` stands for: its dimension in SI base units
+ * (`"kg.m2.s-2"`, with the exponents of m, kg, s, A, K, mol, cd), and
+ * `scale` / `offset` with `value_in_si = value · scale + offset`. Two units
+ * convert into each other exactly when their dimensions are equal.
+ *
+ * # Errors
+ * As [`unit_convert`] for `unit` (at `parameter` `unit`) and `definitions`.
+ */
+export function unit_info(unit: string, definitions?: UnitDefinitionSpec[] | null): UnitInfo;
+
 /**
  * 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.13.1",
+  "version": "0.14.1",
   "license": "MIT",
   "repository": {
     "type": "git",

package/u_numflow.d.ts

@@ -14,6 +14,29 @@ export interface RefusalCode {
     fields: string[];
 }
 
+/**
+ * A unit the caller defines: `symbol` = `factor` × `unit` (+ `offset` SI
+ * units at its zero, for a scale such as a Fahrenheit degree).
+ */
+export interface UnitDefinitionSpec {
+    /**
+     * The new symbol, e.g. `cal_IT`.
+     */
+    symbol: string;
+    /**
+     * What it is a multiple of, as a unit expression, e.g. `J`.
+     */
+    unit: string;
+    /**
+     * How many `unit` one `symbol` is (default 1, `> 0`).
+     */
+    factor?: number;
+    /**
+     * SI value at the symbol's zero (default 0).
+     */
+    offset?: number;
+}
+
 /**
  * A violation a checker reports. This package has no checker; the type is
  * here so every engine's [`Codes`] has one shape.
@@ -40,6 +63,28 @@ export interface LambdaEstimateDto {
     at_bound: boolean;
 }
 
+/**
+ * What a unit expression stands for.
+ */
+export interface UnitInfo {
+    /**
+     * The dimension in SI base units, e.g. `kg.m2.s-2` (`1` for a pure number).
+     */
+    dimension: string;
+    /**
+     * Exponents of m, kg, s, A, K, mol, cd.
+     */
+    exponents: [number, number, number, number, number, number, number];
+    /**
+     * Size of one unit in coherent SI units.
+     */
+    scale: number;
+    /**
+     * SI value of the unit's zero (0 except for scales such as `Cel`).
+     */
+    offset: number;
+}
+
 /**
  * What this package can answer with besides a result: every refusal
  * `code`, and no violations -- it has no checker.
@@ -231,6 +276,14 @@ export function inverse_normal_cdf(p: number): number;
  */
 export function mean(data: number[] | Float64Array): number;
 
+/**
+ * Median of the sample `data` (even length: the mean of the middle two).
+ *
+ * # Errors
+ * Throws `empty_input` when `data` is empty.
+ */
+export function median(data: number[] | Float64Array): number;
+
 /**
  * Standard normal CDF Φ(x) = P(Z ≤ x) for Z ~ N(0, 1).
  *
@@ -250,6 +303,18 @@ export function normal_cdf(x: number): number;
  */
 export function normal_sf(x: number): number;
 
+/**
+ * Sample quantiles of `data` at each of `probabilities`, in the order asked
+ * — R-7 linear interpolation (Hyndman & Fan 1996; the default of R, NumPy
+ * and Excel), sorting the sample once.
+ *
+ * # Errors
+ * Throws `empty_input` when `data` is empty, and `parameter_out_of_range`
+ * (`parameter` `probabilities[i]`, `min` 0, `max` 1) for a probability
+ * outside `[0, 1]`.
+ */
+export function quantiles(data: number[] | Float64Array, probabilities: number[] | Float64Array): Float64Array;
+
 /**
  * Forward DFT of a real sequence of any length.
  *
@@ -289,6 +354,45 @@ export function t_distribution_cdf(t: number, df: number): number;
  */
 export function t_distribution_quantile(p: number, df: number): number;
 
+/**
+ * A reading `value` in the unit `from`, in the unit `to`: 20 `Cel` is
+ * 293.15 `K`. Units are UCUM expressions (`kW.h`, `m/s2`, `J/(kg.K)`) over
+ * the SI and the `definitions` given — e.g.
+ * `[{ symbol: "cal_IT", unit: "J", factor: 4.1868 }]`.
+ *
+ * # Errors
+ * `value_not_finite` (`parameter` `value`); `malformed_input` for an
+ * expression that does not parse or a definition of the wrong shape;
+ * `unknown_unit` (`parameter`, `got` = the symbol); `invalid_option` for a
+ * scale such as `Cel` with a prefix, exponent or product;
+ * `dimension_mismatch` (`parameter` `to`, `expected` = the dimension of
+ * `from`, `got` = that of `to`, both in SI base units); for a definition,
+ * `duplicate_id` (`id`, `index`) for a symbol already a unit and
+ * `parameter_out_of_range` for a `factor` not `> 0`, each at
+ * `definitions[i].…`.
+ */
+export function unit_convert(value: number, from: string, to: string, definitions?: UnitDefinitionSpec[] | null): number;
+
+/**
+ * An amount of change `value` in `from`, in `to`: the offset of a scale
+ * cancels, so a rise of 20 `Cel` is a rise of 20 `K`.
+ *
+ * # Errors
+ * As [`unit_convert`].
+ */
+export function unit_convert_difference(value: number, from: string, to: string, definitions?: UnitDefinitionSpec[] | null): number;
+
+/**
+ * What the unit expression `unit` stands for: its dimension in SI base units
+ * (`"kg.m2.s-2"`, with the exponents of m, kg, s, A, K, mol, cd), and
+ * `scale` / `offset` with `value_in_si = value · scale + offset`. Two units
+ * convert into each other exactly when their dimensions are equal.
+ *
+ * # Errors
+ * As [`unit_convert`] for `unit` (at `parameter` `unit`) and `definitions`.
+ */
+export function unit_info(unit: string, definitions?: UnitDefinitionSpec[] | null): UnitInfo;
+
 /**
  * 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, chi_squared_cdf, chi_squared_quantile, codes, 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
+    box_cox, chi_squared_cdf, chi_squared_quantile, codes, 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, median, normal_cdf, normal_sf, quantiles, rfft, std_dev, t_distribution_cdf, t_distribution_quantile, unit_convert, unit_convert_difference, unit_info, variance
 } from "./u_numflow_bg.js";

package/u_numflow_bg.js

@@ -342,6 +342,22 @@ export function mean(data) {
     return ret[0];
 }
 
+/**
+ * Median of the sample `data` (even length: the mean of the middle two).
+ *
+ * # Errors
+ * Throws `empty_input` when `data` is empty.
+ * @param {number[] | Float64Array} data
+ * @returns {number}
+ */
+export function median(data) {
+    const ret = wasm.median(data);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return ret[0];
+}
+
 /**
  * Standard normal CDF Φ(x) = P(Z ≤ x) for Z ~ N(0, 1).
  *
@@ -371,6 +387,29 @@ export function normal_sf(x) {
     return ret;
 }
 
+/**
+ * Sample quantiles of `data` at each of `probabilities`, in the order asked
+ * — R-7 linear interpolation (Hyndman & Fan 1996; the default of R, NumPy
+ * and Excel), sorting the sample once.
+ *
+ * # Errors
+ * Throws `empty_input` when `data` is empty, and `parameter_out_of_range`
+ * (`parameter` `probabilities[i]`, `min` 0, `max` 1) for a probability
+ * outside `[0, 1]`.
+ * @param {number[] | Float64Array} data
+ * @param {number[] | Float64Array} probabilities
+ * @returns {Float64Array}
+ */
+export function quantiles(data, probabilities) {
+    const ret = wasm.quantiles(data, probabilities);
+    if (ret[3]) {
+        throw takeFromExternrefTable0(ret[2]);
+    }
+    var v1 = getArrayF64FromWasm0(ret[0], ret[1]).slice();
+    wasm.__wbindgen_free(ret[0], ret[1] * 8, 8);
+    return v1;
+}
+
 /**
  * Forward DFT of a real sequence of any length.
  *
@@ -446,6 +485,86 @@ export function t_distribution_quantile(p, df) {
     return ret[0];
 }
 
+/**
+ * A reading `value` in the unit `from`, in the unit `to`: 20 `Cel` is
+ * 293.15 `K`. Units are UCUM expressions (`kW.h`, `m/s2`, `J/(kg.K)`) over
+ * the SI and the `definitions` given — e.g.
+ * `[{ symbol: "cal_IT", unit: "J", factor: 4.1868 }]`.
+ *
+ * # Errors
+ * `value_not_finite` (`parameter` `value`); `malformed_input` for an
+ * expression that does not parse or a definition of the wrong shape;
+ * `unknown_unit` (`parameter`, `got` = the symbol); `invalid_option` for a
+ * scale such as `Cel` with a prefix, exponent or product;
+ * `dimension_mismatch` (`parameter` `to`, `expected` = the dimension of
+ * `from`, `got` = that of `to`, both in SI base units); for a definition,
+ * `duplicate_id` (`id`, `index`) for a symbol already a unit and
+ * `parameter_out_of_range` for a `factor` not `> 0`, each at
+ * `definitions[i].…`.
+ * @param {number} value
+ * @param {string} from
+ * @param {string} to
+ * @param {UnitDefinitionSpec[] | null} [definitions]
+ * @returns {number}
+ */
+export function unit_convert(value, from, to, definitions) {
+    const ptr0 = passStringToWasm0(from, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passStringToWasm0(to, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    const ret = wasm.unit_convert(value, ptr0, len0, ptr1, len1, isLikeNone(definitions) ? 0 : addToExternrefTable0(definitions));
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return ret[0];
+}
+
+/**
+ * An amount of change `value` in `from`, in `to`: the offset of a scale
+ * cancels, so a rise of 20 `Cel` is a rise of 20 `K`.
+ *
+ * # Errors
+ * As [`unit_convert`].
+ * @param {number} value
+ * @param {string} from
+ * @param {string} to
+ * @param {UnitDefinitionSpec[] | null} [definitions]
+ * @returns {number}
+ */
+export function unit_convert_difference(value, from, to, definitions) {
+    const ptr0 = passStringToWasm0(from, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passStringToWasm0(to, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    const ret = wasm.unit_convert_difference(value, ptr0, len0, ptr1, len1, isLikeNone(definitions) ? 0 : addToExternrefTable0(definitions));
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return ret[0];
+}
+
+/**
+ * What the unit expression `unit` stands for: its dimension in SI base units
+ * (`"kg.m2.s-2"`, with the exponents of m, kg, s, A, K, mol, cd), and
+ * `scale` / `offset` with `value_in_si = value · scale + offset`. Two units
+ * convert into each other exactly when their dimensions are equal.
+ *
+ * # Errors
+ * As [`unit_convert`] for `unit` (at `parameter` `unit`) and `definitions`.
+ * @param {string} unit
+ * @param {UnitDefinitionSpec[] | null} [definitions]
+ * @returns {UnitInfo}
+ */
+export function unit_info(unit, definitions) {
+    const ptr0 = passStringToWasm0(unit, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.unit_info(ptr0, len0, isLikeNone(definitions) ? 0 : addToExternrefTable0(definitions));
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
 /**
  * Sample variance of `data` (Bessel-corrected, denominator n−1).
  *
@@ -511,6 +630,10 @@ export function __wbg___wbindgen_is_object_3c45d4f2dde4e749(arg0) {
     const ret = typeof(val) === 'object' && val !== null;
     return ret;
 }
+export function __wbg___wbindgen_is_undefined_8865fb403f8fe9d8(arg0) {
+    const ret = arg0 === undefined;
+    return ret;
+}
 export function __wbg___wbindgen_jsval_eq_02babf21faa37971(arg0, arg1) {
     const ret = arg0 === arg1;
     return ret;
@@ -568,6 +691,10 @@ export function __wbg_get_unchecked_288889d017702237(arg0, arg1) {
     const ret = arg0[arg1 >>> 0];
     return ret;
 }
+export function __wbg_get_with_ref_key_6412cf3094599694(arg0, arg1) {
+    const ret = arg0[arg1];
+    return ret;
+}
 export function __wbg_instanceof_ArrayBuffer_a99f175873e5d9b8(arg0) {
     let result;
     try {