@nshiab/simple-data-analysis-core 2.0.8 → 2.1.0

package/script/helpers/camelCase.d.ts

@@ -2,29 +2,31 @@
  * Converts a string into camelCase. This is useful for creating variable
  * names or object keys from human-readable text.
  *
- * @param input - The string to convert to camelCase. It can contain spaces,
- *   punctuation, and mixed casing.
- *
- * @returns The camelCased version of the input string.
- *
  * @example
  * ```ts
  * // Basic conversion
  * const result1 = camelCase("hello world");
  * console.log(result1); // "helloWorld"
  * ```
+ *
  * @example
  * ```ts
  * // With punctuation and mixed case
  * const result2 = camelCase("  --Some@Thing is- happening--  ");
  * console.log(result2); // "someThingIsHappening"
  * ```
+ *
  * @example
  * ```ts
  * // With a single word
  * const result3 = camelCase("Journalism");
  * console.log(result3); // "journalism"
  * ```
+ *
+ * @param input - The string to convert to camelCase. It can contain spaces,
+ *   punctuation, and mixed casing.
+ *
+ * @returns The camelCased version of the input string.
  */
 export default function camelCase(input: string): string;
 //# sourceMappingURL=camelCase.d.ts.map

package/script/helpers/camelCase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"camelCase.d.ts","sourceRoot":"","sources":["../../src/helpers/camelCase.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAC,OAAO,UAAU,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAiBvD"}
+{"version":3,"file":"camelCase.d.ts","sourceRoot":"","sources":["../../src/helpers/camelCase.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,OAAO,UAAU,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAiBvD"}

package/script/helpers/camelCase.js

@@ -9,29 +9,31 @@ const capitalize_js_1 = __importDefault(require("./capitalize.js"));
  * Converts a string into camelCase. This is useful for creating variable
  * names or object keys from human-readable text.
  *
- * @param input - The string to convert to camelCase. It can contain spaces,
- *   punctuation, and mixed casing.
- *
- * @returns The camelCased version of the input string.
- *
  * @example
  * ```ts
  * // Basic conversion
  * const result1 = camelCase("hello world");
  * console.log(result1); // "helloWorld"
  * ```
+ *
  * @example
  * ```ts
  * // With punctuation and mixed case
  * const result2 = camelCase("  --Some@Thing is- happening--  ");
  * console.log(result2); // "someThingIsHappening"
  * ```
+ *
  * @example
  * ```ts
  * // With a single word
  * const result3 = camelCase("Journalism");
  * console.log(result3); // "journalism"
  * ```
+ *
+ * @param input - The string to convert to camelCase. It can contain spaces,
+ *   punctuation, and mixed casing.
+ *
+ * @returns The camelCased version of the input string.
  */
 function camelCase(input) {
     const words = input

package/script/helpers/capitalize.d.ts

@@ -1,28 +1,30 @@
 /**
  * Capitalizes the first letter of a given string.
  *
- * @param string - The string to be capitalized.
- *
- * @returns A new string with the first letter in uppercase.
- *
  * @example
  * ```ts
  * // Basic usage
  * const capitalized = capitalize("hello world");
  * console.log(capitalized); // "Hello world"
  * ```
+ *
  * @example
  * ```ts
  * // With an already capitalized string
  * const alreadyCapitalized = capitalize("Journalism");
  * console.log(alreadyCapitalized); // "Journalism"
  * ```
+ *
  * @example
  * ```ts
  * // With a single character
  * const singleChar = capitalize("a");
  * console.log(singleChar); // "A"
  * ```
+ *
+ * @param string - The string to be capitalized.
+ *
+ * @returns A new string with the first letter in uppercase.
  */
 export default function capitalize(string: string): string;
 //# sourceMappingURL=capitalize.d.ts.map

package/script/helpers/capitalize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capitalize.d.ts","sourceRoot":"","sources":["../../src/helpers/capitalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAC,OAAO,UAAU,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAMzD"}
+{"version":3,"file":"capitalize.d.ts","sourceRoot":"","sources":["../../src/helpers/capitalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAC,OAAO,UAAU,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAMzD"}

package/script/helpers/capitalize.js

@@ -4,28 +4,30 @@ exports.default = capitalize;
 /**
  * Capitalizes the first letter of a given string.
  *
- * @param string - The string to be capitalized.
- *
- * @returns A new string with the first letter in uppercase.
- *
  * @example
  * ```ts
  * // Basic usage
  * const capitalized = capitalize("hello world");
  * console.log(capitalized); // "Hello world"
  * ```
+ *
  * @example
  * ```ts
  * // With an already capitalized string
  * const alreadyCapitalized = capitalize("Journalism");
  * console.log(alreadyCapitalized); // "Journalism"
  * ```
+ *
  * @example
  * ```ts
  * // With a single character
  * const singleChar = capitalize("a");
  * console.log(singleChar); // "A"
  * ```
+ *
+ * @param string - The string to be capitalized.
+ *
+ * @returns A new string with the first letter in uppercase.
  */
 function capitalize(string) {
     if (string.length === 0) {

package/script/helpers/clusterHdbscan.d.ts

@@ -0,0 +1,18 @@
+import type { DuckDBConnection } from "@duckdb/node-api";
+/**
+ * Build the condensed hierarchy, select EOM clusters, and calculate point
+ * outputs from an HDBSCAN mutual-reachability MST. Only O(n) graph/hierarchy
+ * state crosses from DuckDB; source vectors remain native.
+ */
+export default function clusterHdbscan(connection: DuckDBConnection, mst: string, options: {
+    count: number;
+    minClusterSize: number;
+    allowSingleCluster: boolean;
+}): Promise<{
+    labels: Int32Array;
+    probabilities: Float64Array;
+    outlierScores: Float64Array;
+}>;
+/** Match a C float accumulator, including rounding after every addition. */
+export declare function accumulateFloat32(values: number[]): number;
+//# sourceMappingURL=clusterHdbscan.d.ts.map

package/script/helpers/clusterHdbscan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clusterHdbscan.d.ts","sourceRoot":"","sources":["../../src/helpers/clusterHdbscan.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAWzD;;;;GAIG;AACH,wBAA8B,cAAc,CAC1C,UAAU,EAAE,gBAAgB,EAC5B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;IACP,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,OAAO,CAAC;CAC7B,GACA,OAAO,CAAC;IACT,MAAM,EAAE,UAAU,CAAC;IACnB,aAAa,EAAE,YAAY,CAAC;IAC5B,aAAa,EAAE,YAAY,CAAC;CAC7B,CAAC,CAcD;AA4YD,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAI1D"}

package/script/helpers/clusterHdbscan.js

@@ -0,0 +1,346 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = clusterHdbscan;
+exports.accumulateFloat32 = accumulateFloat32;
+/**
+ * Build the condensed hierarchy, select EOM clusters, and calculate point
+ * outputs from an HDBSCAN mutual-reachability MST. Only O(n) graph/hierarchy
+ * state crosses from DuckDB; source vectors remain native.
+ */
+async function clusterHdbscan(connection, mst, options) {
+    // Leaves and internal nodes share the signed Int32 hierarchy namespace.
+    if (!Number.isSafeInteger(options.count) || options.count < 2 ||
+        options.count > 0x40000000) {
+        throw new Error("HDBSCAN hierarchy requires between 2 and 1073741824 rows so all 2*n-1 node identifiers fit signed INTEGER state.");
+    }
+    const edges = await readMst(connection, mst, options.count);
+    const linkage = buildSingleLinkage(edges, options.count);
+    const tree = condenseTree(linkage, options.count, options.minClusterSize);
+    return selectClusters(tree, options.count, options.allowSingleCluster);
+}
+async function readMst(connection, mst, count) {
+    const edges = [];
+    const result = await connection.stream(`SELECT source,target,distance FROM ${mst}`);
+    while (true) {
+        const chunk = await result.fetchChunk();
+        if (!chunk || chunk.rowCount === 0)
+            break;
+        const sources = chunk.getColumnVector(0);
+        const targets = chunk.getColumnVector(1);
+        const distances = chunk.getColumnVector(2);
+        for (let row = 0; row < chunk.rowCount; row++) {
+            const rawSource = sources.getItem(row);
+            const rawTarget = targets.getItem(row);
+            const rawDistance = distances.getItem(row);
+            if (rawSource === null || rawSource === undefined ||
+                rawTarget === null || rawTarget === undefined ||
+                rawDistance === null || rawDistance === undefined) {
+                throw new Error("HDBSCAN mutual-reachability MST contains an invalid edge.");
+            }
+            const source = Number(rawSource);
+            const target = Number(rawTarget);
+            const distance = Number(rawDistance);
+            if (!Number.isSafeInteger(source) || source < 0 || source >= count ||
+                !Number.isSafeInteger(target) || target < 0 || target >= count ||
+                source === target || !Number.isFinite(distance) || distance < 0) {
+                throw new Error("HDBSCAN mutual-reachability MST contains an invalid edge.");
+            }
+            edges.push({ source, target, distance });
+        }
+    }
+    if (edges.length !== count - 1) {
+        throw new Error(`HDBSCAN mutual-reachability MST returned ${edges.length} edges; ${count - 1} were required.`);
+    }
+    return edges;
+}
+function buildSingleLinkage(edges, count) {
+    edges.sort((a, b) => a.distance - b.distance ||
+        Math.min(a.source, a.target) - Math.min(b.source, b.target) ||
+        Math.max(a.source, a.target) - Math.max(b.source, b.target));
+    const parent = new Int32Array(count);
+    const size = new Int32Array(count).fill(1);
+    const node = new Int32Array(count);
+    for (let vertex = 0; vertex < count; vertex++) {
+        parent[vertex] = vertex;
+        node[vertex] = vertex;
+    }
+    const find = (start) => {
+        let root = start;
+        while (parent[root] !== root)
+            root = parent[root];
+        let current = start;
+        while (parent[current] !== current) {
+            const next = parent[current];
+            parent[current] = root;
+            current = next;
+        }
+        return root;
+    };
+    const linkage = [];
+    for (const edge of edges) {
+        let leftRoot = find(edge.source);
+        let rightRoot = find(edge.target);
+        if (leftRoot === rightRoot) {
+            throw new Error("HDBSCAN mutual-reachability edges do not form a tree.");
+        }
+        const combinedNode = count + linkage.length;
+        const combinedSize = size[leftRoot] + size[rightRoot];
+        linkage.push({
+            left: node[leftRoot],
+            right: node[rightRoot],
+            distance: edge.distance,
+            size: combinedSize,
+        });
+        if (size[leftRoot] < size[rightRoot]) {
+            [leftRoot, rightRoot] = [rightRoot, leftRoot];
+        }
+        parent[rightRoot] = leftRoot;
+        size[leftRoot] = combinedSize;
+        node[leftRoot] = combinedNode;
+    }
+    if (linkage.length !== count - 1 || linkage.at(-1)?.size !== count) {
+        throw new Error("HDBSCAN mutual-reachability edges do not form one connected tree.");
+    }
+    return linkage;
+}
+function condenseTree(hierarchy, count, minClusterSize) {
+    const root = 2 * count - 2;
+    const relabel = new Int32Array(root + 1).fill(-1);
+    relabel[root] = count;
+    let nextLabel = count + 1;
+    const ignored = new Uint8Array(root + 1);
+    const result = [];
+    for (const current of breadthFirstHierarchy(hierarchy, count, root)) {
+        if (ignored[current] || current < count)
+            continue;
+        const split = hierarchy[current - count];
+        const lambda = split.distance > 0 ? 1 / split.distance : Infinity;
+        const leftSize = split.left >= count
+            ? hierarchy[split.left - count].size
+            : 1;
+        const rightSize = split.right >= count
+            ? hierarchy[split.right - count].size
+            : 1;
+        if (leftSize >= minClusterSize && rightSize >= minClusterSize) {
+            relabel[split.left] = nextLabel++;
+            result.push({
+                parent: relabel[current],
+                child: relabel[split.left],
+                lambda,
+                childSize: leftSize,
+            });
+            relabel[split.right] = nextLabel++;
+            result.push({
+                parent: relabel[current],
+                child: relabel[split.right],
+                lambda,
+                childSize: rightSize,
+            });
+        }
+        else if (leftSize < minClusterSize && rightSize < minClusterSize) {
+            appendRunt(hierarchy, count, split.left, relabel[current], lambda, ignored, result);
+            appendRunt(hierarchy, count, split.right, relabel[current], lambda, ignored, result);
+        }
+        else if (leftSize < minClusterSize) {
+            relabel[split.right] = relabel[current];
+            appendRunt(hierarchy, count, split.left, relabel[current], lambda, ignored, result);
+        }
+        else {
+            relabel[split.left] = relabel[current];
+            appendRunt(hierarchy, count, split.right, relabel[current], lambda, ignored, result);
+        }
+    }
+    if (result.length === 0) {
+        throw new Error("HDBSCAN condensed hierarchy is empty.");
+    }
+    return result;
+}
+function appendRunt(hierarchy, count, root, parent, lambda, ignored, result) {
+    for (const node of breadthFirstHierarchy(hierarchy, count, root)) {
+        if (node < count) {
+            result.push({ parent, child: node, lambda, childSize: 1 });
+        }
+        ignored[node] = 1;
+    }
+}
+function breadthFirstHierarchy(hierarchy, count, root) {
+    const result = [];
+    let level = [root];
+    while (level.length > 0) {
+        for (const node of level)
+            result.push(node);
+        const next = [];
+        for (const node of level) {
+            if (node < count)
+                continue;
+            const split = hierarchy[node - count];
+            next.push(split.left, split.right);
+        }
+        level = next;
+    }
+    return result;
+}
+function selectClusters(tree, count, allowSingleCluster) {
+    let root = Number.MAX_SAFE_INTEGER;
+    let maximumParent = -1;
+    for (const edge of tree) {
+        if (edge.parent < root)
+            root = edge.parent;
+        if (edge.parent > maximumParent)
+            maximumParent = edge.parent;
+    }
+    if (root !== count) {
+        throw new Error("HDBSCAN condensed hierarchy has an invalid root.");
+    }
+    const births = new Float64Array(maximumParent + 1).fill(NaN);
+    for (const edge of tree) {
+        if (Number.isNaN(births[edge.child]))
+            births[edge.child] = edge.lambda;
+        else
+            births[edge.child] = Math.min(births[edge.child], edge.lambda);
+    }
+    births[root] = 0;
+    const stability = new Map();
+    for (let cluster = root; cluster <= maximumParent; cluster++) {
+        stability.set(cluster, 0);
+    }
+    for (const edge of tree) {
+        stability.set(edge.parent, stability.get(edge.parent) +
+            (edge.lambda - births[edge.parent]) * edge.childSize);
+    }
+    const clusterEdges = tree.filter(({ childSize }) => childSize > 1);
+    const nodeList = [...stability.keys()].sort((a, b) => b - a);
+    if (!allowSingleCluster)
+        nodeList.pop();
+    const preferred = new Map();
+    const children = new Map();
+    for (const edge of clusterEdges) {
+        const values = children.get(edge.parent) ?? [];
+        values.push(edge.child);
+        children.set(edge.parent, values);
+    }
+    for (const cluster of nodeList) {
+        const childClusters = children.get(cluster) ?? [];
+        // hdbscan 0.8.44 stores this otherwise-double reduction in a C float.
+        const subtreeStability = accumulateFloat32(childClusters.map((child) => stability.get(child)));
+        if (subtreeStability > stability.get(cluster)) {
+            stability.set(cluster, subtreeStability);
+            preferred.set(cluster, false);
+        }
+        else {
+            preferred.set(cluster, true);
+        }
+    }
+    const clusters = [];
+    const pending = [root];
+    while (pending.length > 0) {
+        const cluster = pending.pop();
+        if ((cluster !== root || allowSingleCluster) && preferred.get(cluster)) {
+            clusters.push(cluster);
+            continue;
+        }
+        const childClusters = children.get(cluster) ?? [];
+        for (let index = childClusters.length - 1; index >= 0; index--) {
+            pending.push(childClusters[index]);
+        }
+    }
+    clusters.sort((a, b) => a - b);
+    const labelsByCluster = new Map(clusters.map((cluster, label) => [cluster, label]));
+    const pointEdges = new Array(count);
+    const parentByCluster = new Map();
+    for (const edge of tree) {
+        if (edge.child < count)
+            pointEdges[edge.child] = edge;
+        else
+            parentByCluster.set(edge.child, edge.parent);
+    }
+    for (let point = 0; point < count; point++) {
+        if (pointEdges[point] === undefined) {
+            throw new Error("HDBSCAN condensed hierarchy omitted an input row.");
+        }
+    }
+    const labels = new Int32Array(count).fill(-1);
+    const selectedAncestor = new Int32Array(maximumParent + 1).fill(-1);
+    for (let cluster = root; cluster <= maximumParent; cluster++) {
+        if (labelsByCluster.has(cluster)) {
+            selectedAncestor[cluster] = cluster;
+            continue;
+        }
+        const parent = parentByCluster.get(cluster);
+        if (parent !== undefined) {
+            selectedAncestor[cluster] = selectedAncestor[parent];
+        }
+    }
+    let rootExit = 0;
+    for (const edge of tree) {
+        if (edge.parent === root && edge.lambda > rootExit)
+            rootExit = edge.lambda;
+    }
+    for (let point = 0; point < count; point++) {
+        const pointEdge = pointEdges[point];
+        const cluster = selectedAncestor[pointEdge.parent];
+        if (cluster < 0)
+            continue;
+        if (cluster === root &&
+            !(clusters.length === 1 && allowSingleCluster &&
+                pointEdge.lambda >= rootExit))
+            continue;
+        labels[point] = labelsByCluster.get(cluster);
+    }
+    const deaths = directMaximumLambdas(tree, maximumParent);
+    const probabilities = new Float64Array(count);
+    for (let point = 0; point < count; point++) {
+        const label = labels[point];
+        if (label < 0)
+            continue;
+        const cluster = clusters[label];
+        const maximum = deaths[cluster];
+        const lambda = pointEdges[point].lambda;
+        probabilities[point] = maximum === 0 || !Number.isFinite(lambda)
+            ? 1
+            : Math.min(lambda, maximum) / maximum;
+    }
+    // hdbscan 0.8.44 propagates maximum density through the condensed tree in
+    // reverse edge order, so each parent sees maxima already resolved below it.
+    for (let index = tree.length - 1; index >= 0; index--) {
+        const edge = tree[index];
+        if (deaths[edge.child] > deaths[edge.parent]) {
+            deaths[edge.parent] = deaths[edge.child];
+        }
+    }
+    const outlierScores = new Float64Array(count);
+    for (let point = 0; point < count; point++) {
+        const edge = pointEdges[point];
+        const maximum = deaths[edge.parent];
+        if (maximum === 0 || !Number.isFinite(edge.lambda)) {
+            outlierScores[point] = 0;
+        }
+        else if (!Number.isFinite(maximum)) {
+            // hdbscan 0.8.44 returns NaN for (Infinity - finite) / Infinity.
+            // Use the finite perturbation limit so public outputs remain finite.
+            outlierScores[point] = 1;
+        }
+        else {
+            outlierScores[point] = (maximum - edge.lambda) / maximum;
+        }
+    }
+    if (probabilities.some((value) => !Number.isFinite(value)) ||
+        outlierScores.some((value) => !Number.isFinite(value))) {
+        throw new Error("HDBSCAN produced non-finite point scores.");
+    }
+    return { labels, probabilities, outlierScores };
+}
+/** Match a C float accumulator, including rounding after every addition. */
+function accumulateFloat32(values) {
+    let total = 0;
+    for (const value of values)
+        total = Math.fround(total + value);
+    return total;
+}
+function directMaximumLambdas(tree, maximumParent) {
+    const deaths = new Float64Array(maximumParent + 1);
+    for (const edge of tree) {
+        deaths[edge.parent] = Math.max(deaths[edge.parent], edge.lambda);
+    }
+    return deaths;
+}

package/script/helpers/computeCovariance.d.ts

@@ -0,0 +1,16 @@
+import type { DuckDBConnection } from "@duckdb/node-api";
+import { type CovarianceFactor } from "./factorCovariance.js";
+export type CovarianceModel = CovarianceFactor & {
+    means: Float64Array;
+    origins: Float64Array;
+    meanOffsets: Float64Array;
+    observations: number;
+};
+export default function computeCovariance(connection: DuckDBConnection, input: {
+    relation: string;
+    rowIdColumn: string;
+    vectorColumn: string;
+    observations: number;
+    dimensions: number;
+}): Promise<CovarianceModel>;
+//# sourceMappingURL=computeCovariance.d.ts.map

package/script/helpers/computeCovariance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"computeCovariance.d.ts","sourceRoot":"","sources":["../../src/helpers/computeCovariance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,OAAO,EAAE,KAAK,gBAAgB,EAAoB,MAAM,uBAAuB,CAAC;AAEhF,MAAM,MAAM,eAAe,GAAG,gBAAgB,GAAG;IAC/C,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,EAAE,YAAY,CAAC;IACtB,WAAW,EAAE,YAAY,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,wBAA8B,iBAAiB,CAC7C,UAAU,EAAE,gBAAgB,EAC5B,KAAK,EAAE;IACL,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACpB,GACA,OAAO,CAAC,eAAe,CAAC,CAmH1B"}

package/script/helpers/computeCovariance.js

@@ -0,0 +1,105 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = computeCovariance;
+const quoteIdentifier_js_1 = __importDefault(require("./quoteIdentifier.js"));
+const factorCovariance_js_1 = require("./factorCovariance.js");
+async function computeCovariance(connection, input) {
+    const { observations, dimensions } = input;
+    if (!Number.isSafeInteger(dimensions) || dimensions < 1) {
+        throw new Error("Covariance requires at least one feature dimension.");
+    }
+    if (!Number.isSafeInteger(observations) || observations <= dimensions) {
+        throw new Error(`Covariance requires more observations than features (n > d), but received n=${observations} and d=${dimensions}. More observations are necessary, though constant or linearly dependent features can still make covariance singular.`);
+    }
+    const relation = (0, quoteIdentifier_js_1.default)(input.relation);
+    const rowId = (0, quoteIdentifier_js_1.default)(input.rowIdColumn);
+    const vector = (0, quoteIdentifier_js_1.default)(input.vectorColumn);
+    const expanded = `SELECT r.${rowId} AS observation,
+      f.feature::INTEGER AS feature,
+      array_extract(r.${vector}, f.feature)::DOUBLE AS value
+    FROM ${relation} r CROSS JOIN range(1, ${dimensions + 1}) f(feature)`;
+    const offsets = `SELECT observation, feature, value,
+      first_value(value) OVER (PARTITION BY feature ORDER BY observation
+        ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING) AS origin
+    FROM (${expanded})`;
+    const meanRows = (await connection.runAndReadAll(`SELECT feature - 1 AS feature, first(origin) AS origin,
+      avg(value - origin) AS mean_offset, max(abs(value - origin)) AS magnitude FROM (${offsets})
+      GROUP BY feature ORDER BY feature`)).getRowsJS();
+    if (meanRows.length !== dimensions) {
+        throw new Error("Covariance aggregation returned an incomplete centroid.");
+    }
+    const magnitudes = new Float64Array(dimensions);
+    const means = new Float64Array(dimensions);
+    const origins = new Float64Array(dimensions);
+    const meanOffsets = new Float64Array(dimensions);
+    for (const row of meanRows) {
+        const feature = Number(row[0]);
+        const origin = Number(row[1]);
+        const meanOffset = Number(row[2]);
+        if (!Number.isSafeInteger(feature) || !Number.isFinite(origin) ||
+            !Number.isFinite(meanOffset)) {
+            throw new Error("Covariance is numerically unstable because centroid aggregation produced a non-finite result. Rescale features or remove dimensions whose range cannot be represented as DOUBLE.");
+        }
+        const magnitude = Number(row[3]);
+        if (!Number.isFinite(magnitude) || magnitude <= 0) {
+            throw new Error(`Covariance is singular or numerically unstable (feature ${feature + 1} has constant values or an unrepresentable range). Constant columns, linearly dependent features, or too few observations are common causes. Remove redundant features or provide more observations.`);
+        }
+        magnitudes[feature] = magnitude;
+        origins[feature] = origin;
+        meanOffsets[feature] = meanOffset;
+        means[feature] = origin + meanOffset;
+    }
+    const covariance = new Float64Array(dimensions * dimensions);
+    // covar_samp divides centered cross-products by n - 1. Subtracting a native
+    // per-feature anchor first avoids cancellation in E[x*y] - E[x]E[y] and
+    // retains small deviations when a feature has a large common offset.
+    // Divide by each feature's observed magnitude before accumulating products.
+    // Otherwise the n-1 cross-product sum can overflow even when the final sample
+    // covariance is finite (e.g. [0, 1e154, 2e154], whose variance is 1e308).
+    const result = await connection.stream(`WITH features AS MATERIALIZED (
+        SELECT observation, feature, (value - origin) /
+          array_extract([${magnitudes.join(",")}]::DOUBLE[${dimensions}], feature) AS value
+        FROM (${offsets})
+      )
+      SELECT a.feature - 1 AS row, b.feature - 1 AS column,
+        covar_samp(a.value, b.value) AS covariance
+      FROM features a JOIN features b
+        ON a.observation = b.observation AND a.feature <= b.feature
+      GROUP BY a.feature, b.feature`);
+    let values = 0;
+    while (true) {
+        const chunk = await result.fetchChunk();
+        if (!chunk || chunk.rowCount === 0)
+            break;
+        const rows = new Int32Array(chunk.rowCount);
+        const columns = new Int32Array(chunk.rowCount);
+        const entries = new Float64Array(chunk.rowCount);
+        chunk.visitColumnValues(0, (value, row) => rows[row] = Number(value));
+        chunk.visitColumnValues(1, (value, row) => columns[row] = Number(value));
+        chunk.visitColumnValues(2, (value, row) => entries[row] = Number(value));
+        for (let i = 0; i < chunk.rowCount; i++) {
+            const row = rows[i];
+            const column = columns[i];
+            // Restore units using the larger magnitude first to avoid prematurely
+            // underflowing a finite cross-covariance between very different units.
+            const value = entries[i] * Math.max(magnitudes[row], magnitudes[column]) *
+                Math.min(magnitudes[row], magnitudes[column]);
+            covariance[row * dimensions + column] = value;
+            covariance[column * dimensions + row] = value;
+            values++;
+        }
+    }
+    if (values !== dimensions * (dimensions + 1) / 2) {
+        throw new Error("Covariance aggregation returned an incomplete matrix.");
+    }
+    return {
+        ...(0, factorCovariance_js_1.factorCovariance)(covariance, dimensions),
+        means,
+        origins,
+        meanOffsets,
+        observations,
+    };
+}

package/script/helpers/computeMahalanobisDistances.d.ts

@@ -0,0 +1,14 @@
+import { type DuckDBConnection } from "@duckdb/node-api";
+import type { CovarianceModel } from "./computeCovariance.js";
+/** Evaluates bulk distances in DuckDB; the caller owns the returned scratch table. */
+export default function computeMahalanobisDistances(connection: DuckDBConnection, input: {
+    relation: string;
+    rowIdColumn: string;
+    vectorColumn: string;
+}, model: CovarianceModel, referencePoint?: number[]): Promise<{
+    relation: string;
+    rowIdColumn: string;
+    distanceColumn: string;
+    cleanup: () => Promise<void>;
+}>;
+//# sourceMappingURL=computeMahalanobisDistances.d.ts.map

package/script/helpers/computeMahalanobisDistances.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"computeMahalanobisDistances.d.ts","sourceRoot":"","sources":["../../src/helpers/computeMahalanobisDistances.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAI9D,sFAAsF;AACtF,wBAA8B,2BAA2B,CACvD,UAAU,EAAE,gBAAgB,EAC5B,KAAK,EAAE;IACL,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB,EACD,KAAK,EAAE,eAAe,EACtB,cAAc,CAAC,EAAE,MAAM,EAAE,GACxB,OAAO,CAAC;IACT,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B,CAAC,CAkGD"}