@nshiab/simple-data-analysis-core 2.1.12 → 2.1.14

package/src/helpers/clusterHdbscan.ts

@@ -0,0 +1,396 @@
+import type { DuckDBConnection } from "@duckdb/node-api";
+
+type Edge = { source: number; target: number; distance: number };
+type Linkage = { left: number; right: number; distance: number; size: number };
+type CondensedEdge = {
+  parent: number;
+  child: number;
+  lambda: number;
+  childSize: number;
+};
+
+/**
+ * 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 async function clusterHdbscan(
+  connection: DuckDBConnection,
+  mst: string,
+  options: {
+    count: number;
+    minClusterSize: number;
+    allowSingleCluster: boolean;
+  },
+): Promise<{
+  labels: Int32Array;
+  probabilities: Float64Array;
+  outlierScores: Float64Array;
+}> {
+  // 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: DuckDBConnection, mst: string, count: number): Promise<Edge[]> {
+  const edges: Edge[] = [];
+  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: Edge[], count: number): Linkage[] {
+  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: number): number => {
+    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: 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: Linkage[],
+  count: number,
+  minClusterSize: number,
+): CondensedEdge[] {
+  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: CondensedEdge[] = [];
+
+  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: Linkage[],
+  count: number,
+  root: number,
+  parent: number,
+  lambda: number,
+  ignored: Uint8Array,
+  result: CondensedEdge[],
+): void {
+  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: Linkage[], count: number, root: number): number[] {
+  const result: number[] = [];
+  let level = [root];
+  while (level.length > 0) {
+    for (const node of level) result.push(node);
+    const next: number[] = [];
+    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: CondensedEdge[],
+  count: number,
+  allowSingleCluster: boolean,
+): {
+  labels: Int32Array;
+  probabilities: Float64Array;
+  outlierScores: Float64Array;
+} {
+  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<number, number>();
+  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<number, boolean>();
+  const children = new Map<number, number[]>();
+  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: number[] = [];
+  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: CondensedEdge[] = [];
+  pointEdges.length = count;
+  const parentByCluster = new Map<number, number>();
+  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. */
+export function accumulateFloat32(values: number[]): number {
+  let total = 0;
+  for (const value of values) total = Math.fround(total + value);
+  return total;
+}
+
+function directMaximumLambdas(tree: CondensedEdge[], maximumParent: number): Float64Array {
+  const deaths = new Float64Array(maximumParent + 1);
+  for (const edge of tree) {
+    deaths[edge.parent] = Math.max(deaths[edge.parent], edge.lambda);
+  }
+  return deaths;
+}

package/src/helpers/computeCovariance.ts

@@ -0,0 +1,139 @@
+import type { DuckDBConnection } from "@duckdb/node-api";
+import quoteIdentifier from "./quoteIdentifier.ts";
+import { type CovarianceFactor, factorCovariance } from "./factorCovariance.ts";
+
+export type CovarianceModel = CovarianceFactor & {
+  means: Float64Array;
+  origins: Float64Array;
+  meanOffsets: Float64Array;
+  observations: number;
+};
+
+export default async function computeCovariance(
+  connection: DuckDBConnection,
+  input: {
+    relation: string;
+    rowIdColumn: string;
+    vectorColumn: string;
+    observations: number;
+    dimensions: number;
+  },
+): Promise<CovarianceModel> {
+  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 = quoteIdentifier(input.relation);
+  const rowId = quoteIdentifier(input.rowIdColumn);
+  const vector = quoteIdentifier(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 {
+    ...factorCovariance(covariance, dimensions),
+    means,
+    origins,
+    meanOffsets,
+    observations,
+  };
+}

package/src/helpers/computeMahalanobisDistances.ts

@@ -0,0 +1,114 @@
+import { ARRAY, DOUBLE, type DuckDBConnection } from "@duckdb/node-api";
+import type { CovarianceModel } from "./computeCovariance.ts";
+import { covarianceWhitening } from "./factorCovariance.ts";
+import quoteIdentifier from "./quoteIdentifier.ts";
+
+/** Evaluates bulk distances in DuckDB; the caller owns the returned scratch table. */
+export default async 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>;
+}> {
+  const { dimensions, means, origins, meanOffsets } = model;
+  if ([means, origins, meanOffsets].some((values) => values.length !== dimensions)) {
+    throw new Error("The covariance centroid has the wrong dimensions.");
+  }
+  const vectorLiteral = (values: Float64Array) => {
+    if (values.some((value) => !Number.isFinite(value))) {
+      throw new Error("Mahalanobis centering requires finite coefficients.");
+    }
+    return `[${values.join(",")}]::DOUBLE[${dimensions}]`;
+  };
+  const originSql = vectorLiteral(origins);
+  const offsetSql = vectorLiteral(meanOffsets);
+  if (
+    referencePoint !== undefined &&
+    (referencePoint.length !== dimensions ||
+      referencePoint.some((value) => !Number.isFinite(value)))
+  ) {
+    throw new Error("Mahalanobis reference point must contain one finite number per dimension.");
+  }
+  // Direct subtraction retains exact matches and tiny reference offsets that
+  // would be lost by subtracting the centroid from both points separately.
+  const centeredValue =
+    referencePoint === undefined
+      ? `(value - array_extract(${originSql}, dimension)) - array_extract(${offsetSql}, dimension)`
+      : `value - array_extract(${vectorLiteral(Float64Array.from(referencePoint))}, dimension)`;
+  const whitening = covarianceWhitening(model);
+  const suffix = crypto.randomUUID().replaceAll("-", "");
+  const relation = `__sda_mahalanobis_distances_${suffix}`;
+  const weights = `__sda_mahalanobis_weights_${suffix}`;
+  const rowIdColumn = "row_id";
+  const distanceColumn = "distance";
+  const cleanup = async () => {
+    await connection.run(`DROP TABLE IF EXISTS ${quoteIdentifier(relation)}`);
+  };
+  try {
+    await connection.run(`CREATE TEMP TABLE ${quoteIdentifier(weights)}
+      (weight DOUBLE[${dimensions}])`);
+    const appender = await connection.createAppender(weights);
+    try {
+      // Only O(d²) summary state crosses this boundary, one O(d) row at a time.
+      // Binding a native table avoids parsing a matrix-sized SQL literal and
+      // repeatedly evaluating it inside a per-observation lambda.
+      for (let row = 0; row < dimensions; row++) {
+        appender.appendArray(
+          Array.from(whitening.subarray(row * dimensions, (row + 1) * dimensions)),
+          ARRAY(DOUBLE, dimensions),
+        );
+        appender.endRow();
+      }
+      appender.flushSync();
+    } finally {
+      appender.closeSync();
+    }
+    // Center once per observation. The cross product is consumed by a grouped
+    // aggregate: O(n d²) arithmetic, O(n d) centered storage, O(d²) coefficients,
+    // and O(n) aggregate/output state. Source vectors never enter JavaScript.
+    await connection.run(`CREATE TEMP TABLE ${quoteIdentifier(relation)} AS
+      WITH centered AS MATERIALIZED (
+        SELECT ${quoteIdentifier(input.rowIdColumn)} AS row_id,
+          list_transform(${quoteIdentifier(input.vectorColumn)},
+            (value, dimension) -> ${centeredValue})::DOUBLE[${dimensions}] AS vector
+        FROM ${quoteIdentifier(input.relation)}
+      ), components AS MATERIALIZED (
+        SELECT row_id, abs(array_inner_product(weight, vector)) AS component
+        FROM centered CROSS JOIN ${quoteIdentifier(weights)}
+      ), magnitudes AS (
+        SELECT row_id, max(component) AS magnitude FROM components GROUP BY row_id
+      )
+      SELECT row_id, CASE WHEN magnitude = 0 THEN 0::DOUBLE
+        ELSE magnitude * sqrt(sum(pow(component / magnitude, 2))) END AS distance
+      FROM components JOIN magnitudes USING (row_id)
+      GROUP BY row_id, magnitude`);
+    const invalid = Number(
+      (
+        await connection.runAndReadAll(
+          `SELECT count(*) FROM ${quoteIdentifier(relation)}
+        WHERE distance IS NULL OR NOT isfinite(distance)`,
+        )
+      ).getRowsJS()[0][0],
+    );
+    if (invalid > 0) {
+      throw new Error(
+        `Mahalanobis distance produced ${invalid} non-finite results. Rescale features or remove numerically unstable dimensions.`,
+      );
+    }
+    return { relation, rowIdColumn, distanceColumn, cleanup };
+  } catch (error) {
+    await cleanup();
+    throw error;
+  } finally {
+    await connection.run(`DROP TABLE IF EXISTS ${quoteIdentifier(weights)}`);
+  }
+}

package/src/helpers/createDirectory.ts

@@ -0,0 +1,26 @@
+import { existsSync, mkdirSync } from "node:fs";
+
+/**
+ * Creates missing directories in an output path, including parent directories.
+ * Non-hidden path segments containing a dot are treated as filenames and omitted.
+ *
+ * @example
+ * ```ts
+ * import { createDirectory } from "@nshiab/simple-data-analysis-core/helpers";
+ * createDirectory("output/tables/results.csv"); // Creates output/tables.
+ * ```
+ *
+ * @param path - An output file path or a directory path without dotted segments.
+ *
+ * @returns Nothing. Existing directories are left unchanged.
+ */
+export default function createDirectory(path: string): void {
+  path = path
+    .split("/")
+    .filter((d) => (d.startsWith(".") ? true : !d.includes(".")))
+    .join("/");
+
+  if (path !== "" && !existsSync(path)) {
+    mkdirSync(path, { recursive: true });
+  }
+}