@nshiab/simple-data-analysis-core 2.1.11 → 2.1.13

package/src/helpers/csvFormat.ts

@@ -0,0 +1,74 @@
+import stringifyUnknown from "./stringifyUnknown.ts";
+/*
+ * Formatting subset of d3-dsv 3.0.1: https://github.com/d3/d3-dsv
+ * Copyright 2013-2021 Mike Bostock
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any purpose
+ * with or without fee is hereby granted, provided that the above copyright notice
+ * and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+ * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+ * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+ * OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+ * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+ * THIS SOFTWARE.
+ */
+
+function pad(value: number, width: number): string {
+  return String(value).padStart(width, "0");
+}
+
+function formatDate(date: Date): string {
+  if (Number.isNaN(date.getTime())) return "Invalid Date";
+  const year = date.getUTCFullYear();
+  const formattedYear =
+    year < 0 ? `-${pad(-year, 6)}` : year > 9999 ? `+${pad(year, 6)}` : pad(year, 4);
+  const hours = date.getUTCHours();
+  const minutes = date.getUTCMinutes();
+  const seconds = date.getUTCSeconds();
+  const milliseconds = date.getUTCMilliseconds();
+  const day = `${formattedYear}-${pad(date.getUTCMonth() + 1, 2)}-${pad(date.getUTCDate(), 2)}`;
+  const time = `${pad(hours, 2)}:${pad(minutes, 2)}`;
+  return (
+    day +
+    (milliseconds
+      ? `T${time}:${pad(seconds, 2)}.${pad(milliseconds, 3)}Z`
+      : seconds
+        ? `T${time}:${pad(seconds, 2)}Z`
+        : minutes || hours
+          ? `T${time}Z`
+          : "")
+  );
+}
+
+function formatValue(value: unknown): string {
+  if (value == null) return "";
+  if (value instanceof Date) return formatDate(value);
+  const text = stringifyUnknown(value, "default");
+  return /[",\n\r]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
+}
+
+export default function csvFormat(
+  rows: Record<string, unknown>[],
+  columns?: string[] | null,
+): string {
+  if (columns == null) {
+    const seen = new Set<string>();
+    columns = [];
+    for (const row of rows) {
+      for (const column in row) {
+        if (!seen.has(column)) {
+          seen.add(column);
+          columns.push(column);
+        }
+      }
+    }
+  }
+  const fields = columns;
+  return [
+    fields.map(formatValue).join(","),
+    ...rows.map((row) => fields.map((column) => formatValue(row[column])).join(",")),
+  ].join("\n");
+}

package/src/helpers/dataToArrays.ts

@@ -0,0 +1,63 @@
+/**
+ * Transforms an array of objects into an object of arrays. This function is the inverse of `arraysToData` and is useful for converting data from a row-based format to a columnar format.
+ *
+ * @example
+ * ```ts
+ * // Basic usage with a simple dataset
+ * const rowData = [
+ *   { name: 'Alice', age: 30, city: 'New York' },
+ *   { name: 'Bob', age: 25, city: 'London' },
+ *   { name: 'Charlie', age: 35, city: 'Paris' }
+ * ];
+ *
+ * const columnarData = dataToArrays(rowData);
+ *
+ * console.log(columnarData);
+ * // Expected output:
+ * // {
+ * //   name: ['Alice', 'Bob', 'Charlie'],
+ * //   age: [30, 25, 35],
+ * //   city: ['New York', 'London', 'Paris']
+ * // }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Preparing data for statistical analysis
+ * const measurements = [
+ *   { id: 1, temp: 20, humidity: 60 },
+ *   { id: 2, temp: 22, humidity: 65 },
+ *   { id: 3, temp: 18, humidity: 55 }
+ * ];
+ *
+ * const separatedVariables = dataToArrays(measurements);
+ *
+ * console.log(separatedVariables);
+ * // Expected output:
+ * // {
+ * //   id: [1, 2, 3],
+ * //   temp: [20, 22, 18],
+ * //   humidity: [60, 65, 55]
+ * // }
+ * ```
+ *
+ * @param data An array of objects. Each object is expected to have the same set of keys.
+ *
+ * @returns An object where each key maps to an array of values, effectively representing the data in a columnar format.
+ *
+ * @category Formatting
+ */
+
+export default function dataToArrays<T extends Record<string, unknown>>(
+  data: T[],
+): { [K in keyof T]: T[K][] } {
+  const newData = {} as { [K in keyof T]: T[K][] };
+
+  const keys = Object.keys(data[0]) as Array<keyof T>;
+
+  for (const key of keys) {
+    newData[key] = data.map((d) => d[key]);
+  }
+
+  return newData;
+}

package/src/helpers/ensureSpatial.ts

@@ -0,0 +1,23 @@
+import mergeOptions from "./mergeOptions.ts";
+import queryDB from "./queryDB.ts";
+import type SimpleTable from "../class/SimpleTable.ts";
+
+/**
+ * Loads the spatial extension once per connection, so geospatial operations
+ * can fuse as plain SELECT fragments instead of each being multi-statement.
+ */
+export default async function ensureSpatial(simpleTable: SimpleTable): Promise<void> {
+  if (simpleTable.sdb.spatialLoaded) {
+    return;
+  }
+  await queryDB(
+    simpleTable,
+    `INSTALL spatial; LOAD spatial; SET geometry_always_xy = true;`,
+    mergeOptions(simpleTable, {
+      table: null,
+      method: null,
+      parameters: null,
+    }),
+  );
+  simpleTable.sdb.spatialLoaded = true;
+}

package/src/helpers/extractTypes.ts

@@ -0,0 +1,17 @@
+export default function extractTypes(
+  types:
+    | {
+        [key: string]: unknown;
+      }[]
+    | null,
+) {
+  const rows = (types ?? []) as {
+    column_name: string;
+    column_type: string;
+  }[];
+  // Define own properties so valid names such as __proto__ do not invoke
+  // Object.prototype setters in Node.js.
+  return Object.fromEntries(
+    rows.filter((row) => row.column_name).map((row) => [row.column_name, row.column_type]),
+  );
+}

package/src/helpers/extractZipEntryToFile.ts

@@ -0,0 +1,268 @@
+import { createReadStream, createWriteStream } from "node:fs";
+import { open, rm, stat } from "node:fs/promises";
+import { Transform, type TransformCallback } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createInflateRaw } from "node:zlib";
+
+/*
+ * Adapted from the ZIP reader in @nshiab/journalism-web-scraping. This
+ * version streams the selected entry to disk so complete StatCan tables do
+ * not need to be buffered in JavaScript memory.
+ */
+
+const END_OF_CENTRAL_DIRECTORY = 0x0605_4b50;
+const CENTRAL_DIRECTORY_ENTRY = 0x0201_4b50;
+const LOCAL_FILE_HEADER = 0x0403_4b50;
+const MAX_COMMENT_LENGTH = 0xffff;
+const MAX_END_RECORD_LENGTH = 22 + MAX_COMMENT_LENGTH;
+const CRC_TABLE = createCrcTable();
+
+type ZipEntry = {
+  compressionMethod: number;
+  compressedSize: number;
+  uncompressedSize: number;
+  expectedCrc: number;
+  localHeaderOffset: number;
+};
+
+class ChecksumTransform extends Transform {
+  #crc = 0xffff_ffff;
+  size = 0;
+
+  get crc32(): number {
+    return (this.#crc ^ 0xffff_ffff) >>> 0;
+  }
+
+  override _transform(
+    chunk: Uint8Array,
+    _encoding: BufferEncoding,
+    callback: TransformCallback,
+  ): void {
+    for (const byte of chunk) {
+      this.#crc = CRC_TABLE[(this.#crc ^ byte) & 0xff] ^ (this.#crc >>> 8);
+    }
+    this.size += chunk.byteLength;
+    callback(null, chunk);
+  }
+}
+
+/** Extracts one entry from a non-ZIP64, single-disk ZIP without buffering it. */
+export default async function extractZipEntryToFile(
+  archive: string,
+  wantedName: string,
+  output: string,
+): Promise<void> {
+  const entry = await findZipEntry(archive, wantedName);
+  if (entry === undefined) {
+    throw new Error(`No ${wantedName} in the zipped file.`);
+  }
+  if (entry.compressionMethod !== 0 && entry.compressionMethod !== 8) {
+    throw new Error(
+      `ZIP entry ${wantedName} uses unsupported compression method ${entry.compressionMethod}.`,
+    );
+  }
+
+  const file = await open(archive, "r");
+  let operationError: unknown;
+  try {
+    const localHeader = new Uint8Array(30);
+    await readExactly(file, localHeader, entry.localHeaderOffset);
+    const view = new DataView(localHeader.buffer);
+    assertSignature(view, 0, LOCAL_FILE_HEADER, "local file header");
+    const fileNameLength = view.getUint16(26, true);
+    const extraLength = view.getUint16(28, true);
+    const dataOffset = entry.localHeaderOffset + 30 + fileNameLength + extraLength;
+    const checksum = new ChecksumTransform();
+    const source = createReadStream(archive, {
+      start: dataOffset,
+      end: dataOffset + entry.compressedSize - 1,
+    });
+    const streams =
+      entry.compressionMethod === 8
+        ? ([
+            source,
+            createInflateRaw(),
+            checksum,
+            createWriteStream(output, {
+              flags: "wx",
+            }),
+          ] as const)
+        : ([source, checksum, createWriteStream(output, { flags: "wx" })] as const);
+    await pipeline(streams);
+
+    if (checksum.size !== entry.uncompressedSize) {
+      throw new Error(`ZIP entry ${wantedName} has an invalid size.`);
+    }
+    if (checksum.crc32 !== entry.expectedCrc) {
+      throw new Error(`ZIP entry ${wantedName} failed its CRC check.`);
+    }
+  } catch (error) {
+    operationError = error;
+  }
+
+  try {
+    await file.close();
+  } catch (closeError) {
+    operationError =
+      operationError === undefined
+        ? closeError
+        : new AggregateError(
+            [operationError, closeError],
+            "Extracting and closing the ZIP archive both failed.",
+            { cause: operationError },
+          );
+  }
+
+  if (operationError !== undefined) {
+    try {
+      await rm(output, { force: true });
+    } catch (cleanupError) {
+      throw new AggregateError(
+        [operationError, cleanupError],
+        "Extracting and cleaning up the ZIP entry both failed.",
+        { cause: operationError },
+      );
+    }
+    throw operationError;
+  }
+}
+
+async function findZipEntry(archive: string, wantedName: string): Promise<ZipEntry | undefined> {
+  const file = await open(archive, "r");
+  try {
+    const size = (await stat(archive)).size;
+    const tailLength = Math.min(size, MAX_END_RECORD_LENGTH);
+    const tail = new Uint8Array(tailLength);
+    await readExactly(file, tail, size - tailLength);
+    const tailView = new DataView(tail.buffer);
+    const endOffset = findEndOfCentralDirectory(tailView);
+    const diskNumber = tailView.getUint16(endOffset + 4, true);
+    const centralDirectoryDisk = tailView.getUint16(endOffset + 6, true);
+    const entriesOnDisk = tailView.getUint16(endOffset + 8, true);
+    const entryCount = tailView.getUint16(endOffset + 10, true);
+    const centralDirectorySize = tailView.getUint32(endOffset + 12, true);
+    const centralDirectoryOffset = tailView.getUint32(endOffset + 16, true);
+
+    if (diskNumber !== 0 || centralDirectoryDisk !== 0 || entriesOnDisk !== entryCount) {
+      throw new Error("Multi-disk ZIP archives are not supported.");
+    }
+    if (
+      entryCount === 0xffff ||
+      centralDirectorySize === 0xffff_ffff ||
+      centralDirectoryOffset === 0xffff_ffff
+    ) {
+      throw new Error("ZIP64 archives are not supported.");
+    }
+    if (centralDirectoryOffset + centralDirectorySize > size) {
+      throw new Error("Invalid ZIP archive: truncated central directory.");
+    }
+
+    const centralDirectory = new Uint8Array(centralDirectorySize);
+    await readExactly(file, centralDirectory, centralDirectoryOffset);
+    const view = new DataView(centralDirectory.buffer);
+    let offset = 0;
+    for (let index = 0; index < entryCount; index++) {
+      assertSignature(view, offset, CENTRAL_DIRECTORY_ENTRY, "central directory");
+      assertRange(centralDirectory, offset, 46, "central directory entry");
+      const flags = view.getUint16(offset + 8, true);
+      const compressionMethod = view.getUint16(offset + 10, true);
+      const expectedCrc = view.getUint32(offset + 16, true);
+      const compressedSize = view.getUint32(offset + 20, true);
+      const uncompressedSize = view.getUint32(offset + 24, true);
+      const fileNameLength = view.getUint16(offset + 28, true);
+      const extraLength = view.getUint16(offset + 30, true);
+      const commentLength = view.getUint16(offset + 32, true);
+      const localHeaderOffset = view.getUint32(offset + 42, true);
+      const entryLength = 46 + fileNameLength + extraLength + commentLength;
+      assertRange(centralDirectory, offset, entryLength, "central directory entry");
+      const name = new TextDecoder().decode(
+        centralDirectory.subarray(offset + 46, offset + 46 + fileNameLength),
+      );
+      if (name === wantedName) {
+        if ((flags & 1) !== 0) {
+          throw new Error(`ZIP entry ${wantedName} is encrypted.`);
+        }
+        if (
+          compressedSize === 0xffff_ffff ||
+          uncompressedSize === 0xffff_ffff ||
+          localHeaderOffset === 0xffff_ffff
+        ) {
+          throw new Error("ZIP64 archives are not supported.");
+        }
+        return {
+          compressionMethod,
+          compressedSize,
+          uncompressedSize,
+          expectedCrc,
+          localHeaderOffset,
+        };
+      }
+      offset += entryLength;
+    }
+    return undefined;
+  } finally {
+    await file.close();
+  }
+}
+
+async function readExactly(
+  file: Awaited<ReturnType<typeof open>>,
+  buffer: Uint8Array,
+  position: number,
+): Promise<void> {
+  let offset = 0;
+  while (offset < buffer.byteLength) {
+    const { bytesRead } = await file.read(
+      buffer,
+      offset,
+      buffer.byteLength - offset,
+      position + offset,
+    );
+    if (bytesRead === 0) {
+      throw new Error("Invalid ZIP archive: unexpected end of file.");
+    }
+    offset += bytesRead;
+  }
+}
+
+function findEndOfCentralDirectory(view: DataView): number {
+  for (let offset = view.byteLength - 22; offset >= 0; offset--) {
+    if (
+      view.getUint32(offset, true) === END_OF_CENTRAL_DIRECTORY &&
+      offset + 22 + view.getUint16(offset + 20, true) === view.byteLength
+    ) {
+      return offset;
+    }
+  }
+  throw new Error("Invalid ZIP archive: end of central directory not found.");
+}
+
+function assertSignature(
+  view: DataView,
+  offset: number,
+  expected: number,
+  description: string,
+): void {
+  if (offset < 0 || offset + 4 > view.byteLength) {
+    throw new Error(`Invalid ZIP archive: truncated ${description}.`);
+  }
+  if (view.getUint32(offset, true) !== expected) {
+    throw new Error(`Invalid ZIP archive: malformed ${description}.`);
+  }
+}
+
+function assertRange(data: Uint8Array, offset: number, length: number, description: string): void {
+  if (offset < 0 || length < 0 || offset + length > data.byteLength) {
+    throw new Error(`Invalid ZIP archive: truncated ${description}.`);
+  }
+}
+
+function createCrcTable(): Uint32Array {
+  return Uint32Array.from({ length: 256 }, (_, index) => {
+    let value = index;
+    for (let bit = 0; bit < 8; bit++) {
+      value = (value >>> 1) ^ (0xedb8_8320 & -(value & 1));
+    }
+    return value >>> 0;
+  });
+}

package/src/helpers/factorCovariance.ts

@@ -0,0 +1,233 @@
+export type CovarianceFactor = {
+  dimensions: number;
+  covariance: Float64Array;
+  scales: Float64Array;
+  cholesky: Float64Array;
+  reciprocalCondition: number;
+};
+
+const instabilityMultiplier = 64;
+
+function singularCovariance(reason: string): Error {
+  return new Error(
+    `Covariance is singular or numerically unstable (${reason}). Constant columns, linearly dependent features, or too few observations are common causes. Remove redundant features or provide more observations.`,
+  );
+}
+
+function scaleCovarianceEntry(value: number, leftScale: number, rightScale: number): number {
+  // Divide by the larger scale first. For a valid covariance, Cauchy-Schwarz
+  // bounds |value| by their product, so this avoids intermediate overflow when
+  // two otherwise equivalent features use radically different units.
+  return leftScale >= rightScale ? value / leftScale / rightScale : value / rightScale / leftScale;
+}
+
+function solveCorrelation(
+  cholesky: Float64Array,
+  dimensions: number,
+  rightHandSide: ArrayLike<number>,
+): Float64Array {
+  const solution = new Float64Array(dimensions);
+  for (let row = 0; row < dimensions; row++) {
+    let value = rightHandSide[row];
+    for (let column = 0; column < row; column++) {
+      value -= cholesky[row * dimensions + column] * solution[column];
+    }
+    solution[row] = value / cholesky[row * dimensions + row];
+  }
+  for (let row = dimensions - 1; row >= 0; row--) {
+    let value = solution[row];
+    for (let column = row + 1; column < dimensions; column++) {
+      value -= cholesky[column * dimensions + row] * solution[column];
+    }
+    solution[row] = value / cholesky[row * dimensions + row];
+  }
+  return solution;
+}
+
+// Hager's estimator avoids forming the inverse merely to decide whether the
+// correlation-scaled covariance is safe to solve. Scaling first makes this
+// rank decision invariant to a change of units in any feature.
+function estimateInverseOneNorm(cholesky: Float64Array, dimensions: number): number {
+  let vector = new Float64Array(dimensions).fill(1 / dimensions);
+  let estimate = 0;
+  let previousIndex = -1;
+  for (let iteration = 0; iteration < 8; iteration++) {
+    const solved = solveCorrelation(cholesky, dimensions, vector);
+    estimate = Math.max(
+      estimate,
+      solved.reduce((sum, value) => sum + Math.abs(value), 0),
+    );
+    const signs = solved.map((value) => (value < 0 ? -1 : 1));
+    const dual = solveCorrelation(cholesky, dimensions, signs);
+    let index = 0;
+    for (let i = 1; i < dimensions; i++) {
+      if (Math.abs(dual[i]) > Math.abs(dual[index])) index = i;
+    }
+    const directional = dual.reduce((sum, value, i) => sum + value * vector[i], 0);
+    if (Math.abs(dual[index]) <= directional || index === previousIndex) break;
+    vector = new Float64Array(dimensions);
+    vector[index] = 1;
+    previousIndex = index;
+  }
+  // The all-positive initial vector can be an eigenvector that causes Hager's
+  // iteration to stop at the *smallest* inverse eigenvalue (for example an
+  // equicorrelation matrix). Higham's alternating, increasing-magnitude probe
+  // prevents that failure; normalize by its 1-norm to retain a lower estimate.
+  // Reference: https://www.netlib.org/lapack/double/dlacon.f (final stage).
+  const alternating = Float64Array.from(
+    { length: dimensions },
+    (_, i) => (i % 2 === 0 ? 1 : -1) * (1 + i / Math.max(1, dimensions - 1)),
+  );
+  const alternatingNorm = alternating.reduce((sum, value) => sum + Math.abs(value), 0);
+  const solved = solveCorrelation(cholesky, dimensions, alternating);
+  estimate = Math.max(
+    estimate,
+    solved.reduce((sum, value) => sum + Math.abs(value), 0) / alternatingNorm,
+  );
+  return estimate;
+}
+
+/** Factors a sample covariance matrix for stable repeated linear solves. */
+export function factorCovariance(
+  covarianceInput: ArrayLike<number>,
+  dimensions: number,
+): CovarianceFactor {
+  if (!Number.isSafeInteger(dimensions) || dimensions < 1) {
+    throw new Error("Covariance dimensions must be a positive safe integer.");
+  }
+  if (covarianceInput.length !== dimensions * dimensions) {
+    throw new Error(
+      `Expected ${dimensions * dimensions} covariance values, received ${covarianceInput.length}.`,
+    );
+  }
+
+  const covariance = Float64Array.from(covarianceInput);
+  const scales = new Float64Array(dimensions);
+  for (let dimension = 0; dimension < dimensions; dimension++) {
+    const variance = covariance[dimension * dimensions + dimension];
+    if (!Number.isFinite(variance) || variance <= 0) {
+      throw singularCovariance(
+        `feature ${dimension + 1} has non-positive or non-finite sample variance`,
+      );
+    }
+    scales[dimension] = Math.sqrt(variance);
+  }
+
+  const correlation = new Float64Array(dimensions * dimensions);
+  let correlationOneNorm = 0;
+  for (let column = 0; column < dimensions; column++) {
+    let columnSum = 0;
+    for (let row = 0; row < dimensions; row++) {
+      const left = covariance[row * dimensions + column];
+      const right = covariance[column * dimensions + row];
+      if (!Number.isFinite(left) || !Number.isFinite(right)) {
+        throw singularCovariance("the sample covariance contains non-finite values");
+      }
+      const value =
+        row === column
+          ? 1
+          : scaleCovarianceEntry(left, scales[row], scales[column]) / 2 +
+            scaleCovarianceEntry(right, scales[row], scales[column]) / 2;
+      if (!Number.isFinite(value)) {
+        throw singularCovariance("correlation scaling produced a non-finite value");
+      }
+      correlation[row * dimensions + column] = value;
+      columnSum += Math.abs(value);
+    }
+    correlationOneNorm = Math.max(correlationOneNorm, columnSum);
+  }
+
+  const cholesky = new Float64Array(dimensions * dimensions);
+  for (let row = 0; row < dimensions; row++) {
+    for (let column = 0; column <= row; column++) {
+      let value = correlation[row * dimensions + column];
+      for (let k = 0; k < column; k++) {
+        value -= cholesky[row * dimensions + k] * cholesky[column * dimensions + k];
+      }
+      if (row === column) {
+        if (!Number.isFinite(value) || value <= 0) {
+          throw singularCovariance(`correlation-scaled Cholesky pivot ${row + 1} is not positive`);
+        }
+        cholesky[row * dimensions + column] = Math.sqrt(value);
+      } else {
+        cholesky[row * dimensions + column] = value / cholesky[column * dimensions + column];
+      }
+    }
+  }
+
+  const inverseOneNorm = estimateInverseOneNorm(cholesky, dimensions);
+  const reciprocalCondition = 1 / (correlationOneNorm * inverseOneNorm);
+  // This is the usual dimension-scaled floating-point rank tolerance, with a
+  // modest safety factor for covariance aggregation and subsequent row solves.
+  const tolerance = instabilityMultiplier * dimensions * Number.EPSILON;
+  if (!Number.isFinite(reciprocalCondition) || reciprocalCondition <= tolerance) {
+    throw singularCovariance(
+      `estimated reciprocal condition ${reciprocalCondition} is at or below ${tolerance}`,
+    );
+  }
+
+  return {
+    dimensions,
+    covariance,
+    scales,
+    cholesky,
+    reciprocalCondition,
+  };
+}
+
+/** Solves covariance * x = rightHandSide through the scaled Cholesky factor. */
+export function solveCovariance(
+  factor: CovarianceFactor,
+  rightHandSide: ArrayLike<number>,
+): Float64Array {
+  const { dimensions, scales, cholesky } = factor;
+  if (rightHandSide.length !== dimensions) {
+    throw new Error(
+      `Expected a right-hand side with ${dimensions} values, received ${rightHandSide.length}.`,
+    );
+  }
+  const scaled = new Float64Array(dimensions);
+  for (let i = 0; i < dimensions; i++) {
+    if (!Number.isFinite(rightHandSide[i])) {
+      throw new Error("The covariance solve requires finite values.");
+    }
+    scaled[i] = rightHandSide[i] / scales[i];
+  }
+  const solution = solveCorrelation(cholesky, dimensions, scaled);
+  for (let i = 0; i < dimensions; i++) {
+    solution[i] /= scales[i];
+    if (!Number.isFinite(solution[i])) {
+      throw singularCovariance("the linear solve produced a non-finite value");
+    }
+  }
+  return solution;
+}
+
+/**
+ * Returns the lower-triangular transform whose squared norm is Mahalanobis
+ * squared distance. This inverts only the Cholesky factor, never covariance.
+ */
+export function covarianceWhitening(factor: CovarianceFactor): Float64Array {
+  const { dimensions, scales, cholesky } = factor;
+  const whitening = new Float64Array(dimensions * dimensions);
+  // Invert the triangular correlation factor first, then apply feature units.
+  // Keeping units out of the recurrence avoids repeated underflow/rounding of
+  // the same coefficient, and visits only the nonzero triangle.
+  for (let column = 0; column < dimensions; column++) {
+    for (let row = column; row < dimensions; row++) {
+      let value = row === column ? 1 : 0;
+      for (let k = column; k < row; k++) {
+        value -= cholesky[row * dimensions + k] * whitening[k * dimensions + column];
+      }
+      whitening[row * dimensions + column] = value / cholesky[row * dimensions + row];
+    }
+    for (let row = column; row < dimensions; row++) {
+      const index = row * dimensions + column;
+      whitening[index] /= scales[column];
+      if (!Number.isFinite(whitening[index])) {
+        throw singularCovariance("the whitening transform produced a non-finite value");
+      }
+    }
+  }
+  return whitening;
+}