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

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"}

package/script/helpers/computeMahalanobisDistances.js

@@ -0,0 +1,93 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = computeMahalanobisDistances;
+const node_api_1 = require("@duckdb/node-api");
+const factorCovariance_js_1 = require("./factorCovariance.js");
+const quoteIdentifier_js_1 = __importDefault(require("./quoteIdentifier.js"));
+/** Evaluates bulk distances in DuckDB; the caller owns the returned scratch table. */
+async function computeMahalanobisDistances(connection, input, model, referencePoint) {
+    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) => {
+        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 = (0, factorCovariance_js_1.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 ${(0, quoteIdentifier_js_1.default)(relation)}`);
+    };
+    try {
+        await connection.run(`CREATE TEMP TABLE ${(0, quoteIdentifier_js_1.default)(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)), (0, node_api_1.ARRAY)(node_api_1.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 ${(0, quoteIdentifier_js_1.default)(relation)} AS
+      WITH centered AS MATERIALIZED (
+        SELECT ${(0, quoteIdentifier_js_1.default)(input.rowIdColumn)} AS row_id,
+          list_transform(${(0, quoteIdentifier_js_1.default)(input.vectorColumn)},
+            (value, dimension) -> ${centeredValue})::DOUBLE[${dimensions}] AS vector
+        FROM ${(0, quoteIdentifier_js_1.default)(input.relation)}
+      ), components AS MATERIALIZED (
+        SELECT row_id, abs(array_inner_product(weight, vector)) AS component
+        FROM centered CROSS JOIN ${(0, quoteIdentifier_js_1.default)(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 ${(0, quoteIdentifier_js_1.default)(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 ${(0, quoteIdentifier_js_1.default)(weights)}`);
+    }
+}

package/script/helpers/createDirectory.d.ts

@@ -2,14 +2,15 @@
  * Creates missing directories in an output path, including parent directories.
  * Non-hidden path segments containing a dot are treated as filenames and omitted.
  *
- * @param path - An output file path or a directory path without dotted segments.
- * @returns Nothing. Existing directories are left unchanged.
- *
  * @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;
 //# sourceMappingURL=createDirectory.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"createDirectory.d.ts","sourceRoot":"","sources":["../../src/helpers/createDirectory.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,OAAO,UAAU,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAS1D"}
+{"version":3,"file":"createDirectory.d.ts","sourceRoot":"","sources":["../../src/helpers/createDirectory.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,OAAO,UAAU,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAS1D"}

package/script/helpers/createDirectory.js

@@ -6,14 +6,15 @@ const node_fs_1 = require("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.
  *
- * @param path - An output file path or a directory path without dotted segments.
- * @returns Nothing. Existing directories are left unchanged.
- *
  * @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.
  */
 function createDirectory(path) {
     path = path

package/script/helpers/dataToArrays.d.ts

@@ -1,10 +1,6 @@
 /**
  * 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.
  *
- * @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.
- *
  * @example
  * ```ts
  * // Basic usage with a simple dataset
@@ -24,6 +20,7 @@
  * //   city: ['New York', 'London', 'Paris']
  * // }
  * ```
+ *
  * @example
  * ```ts
  * // Preparing data for statistical analysis
@@ -43,6 +40,11 @@
  * //   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[]): {

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

@@ -1 +1 @@
-{"version":3,"file":"dataToArrays.d.ts","sourceRoot":"","sources":["../../src/helpers/dataToArrays.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,MAAM,CAAC,OAAO,UAAU,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpE,IAAI,EAAE,CAAC,EAAE,GACR;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE;CAAE,CAU5B"}
+{"version":3,"file":"dataToArrays.d.ts","sourceRoot":"","sources":["../../src/helpers/dataToArrays.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,MAAM,CAAC,OAAO,UAAU,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpE,IAAI,EAAE,CAAC,EAAE,GACR;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE;CAAE,CAU5B"}

package/script/helpers/dataToArrays.js

@@ -2,10 +2,6 @@
 /**
  * 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.
  *
- * @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.
- *
  * @example
  * ```ts
  * // Basic usage with a simple dataset
@@ -25,6 +21,7 @@
  * //   city: ['New York', 'London', 'Paris']
  * // }
  * ```
+ *
  * @example
  * ```ts
  * // Preparing data for statistical analysis
@@ -44,6 +41,11 @@
  * //   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
  */
 Object.defineProperty(exports, "__esModule", { value: true });

package/script/helpers/extractTypes.d.ts

@@ -1,6 +1,6 @@
 export default function extractTypes(types: {
     [key: string]: unknown;
 }[] | null): {
-    [key: string]: string;
+    [k: string]: string;
 };
 //# sourceMappingURL=extractTypes.d.ts.map

package/script/helpers/extractTypes.js

@@ -2,13 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = extractTypes;
 function extractTypes(types) {
-    const typesObj = {};
-    if (types) {
-        for (const t of types) {
-            if (t.column_name) {
-                typesObj[t.column_name] = t.column_type;
-            }
-        }
-    }
-    return typesObj;
+    const rows = (types ?? []);
+    // 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/script/helpers/factorCovariance.d.ts

@@ -0,0 +1,17 @@
+export type CovarianceFactor = {
+    dimensions: number;
+    covariance: Float64Array;
+    scales: Float64Array;
+    cholesky: Float64Array;
+    reciprocalCondition: number;
+};
+/** Factors a sample covariance matrix for stable repeated linear solves. */
+export declare function factorCovariance(covarianceInput: ArrayLike<number>, dimensions: number): CovarianceFactor;
+/** Solves covariance * x = rightHandSide through the scaled Cholesky factor. */
+export declare function solveCovariance(factor: CovarianceFactor, rightHandSide: ArrayLike<number>): Float64Array;
+/**
+ * Returns the lower-triangular transform whose squared norm is Mahalanobis
+ * squared distance. This inverts only the Cholesky factor, never covariance.
+ */
+export declare function covarianceWhitening(factor: CovarianceFactor): Float64Array;
+//# sourceMappingURL=factorCovariance.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"factorCovariance.d.ts","sourceRoot":"","sources":["../../src/helpers/factorCovariance.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,YAAY,CAAC;IACzB,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE,YAAY,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC;CAC7B,CAAC;AAkGF,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAC9B,eAAe,EAAE,SAAS,CAAC,MAAM,CAAC,EAClC,UAAU,EAAE,MAAM,GACjB,gBAAgB,CAoGlB;AAED,gFAAgF;AAChF,wBAAgB,eAAe,CAC7B,MAAM,EAAE,gBAAgB,EACxB,aAAa,EAAE,SAAS,CAAC,MAAM,CAAC,GAC/B,YAAY,CAsBd;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,gBAAgB,GACvB,YAAY,CA2Bd"}

package/script/helpers/factorCovariance.js

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.factorCovariance = factorCovariance;
+exports.solveCovariance = solveCovariance;
+exports.covarianceWhitening = covarianceWhitening;
+const instabilityMultiplier = 64;
+function singularCovariance(reason) {
+    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, leftScale, rightScale) {
+    // 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, dimensions, rightHandSide) {
+    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, dimensions) {
+    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. */
+function factorCovariance(covarianceInput, dimensions) {
+    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. */
+function solveCovariance(factor, rightHandSide) {
+    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.
+ */
+function covarianceWhitening(factor) {
+    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;
+}

package/script/helpers/findGeoColumn.d.ts

@@ -2,14 +2,16 @@ import type SimpleTable from "../class/SimpleTable.js";
 /**
  * Returns the only geometry column in a table.
  *
- * @param simpleTable - The table to inspect.
- * @param method - The SDA method requesting a geometry column.
- * @returns A promise resolving to the name of the only geometry column.
- *
  * @example
  * ```ts
  * const column = await findGeoColumn(table, "getGeoData()");
  * ```
+ *
+ * @param simpleTable - The table to inspect.
+ *
+ * @param method - The SDA method requesting a geometry column.
+ *
+ * @returns A promise resolving to the name of the only geometry column.
  */
 export default function findGeoColumn(simpleTable: SimpleTable, method: string): Promise<string>;
 //# sourceMappingURL=findGeoColumn.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"findGeoColumn.d.ts","sourceRoot":"","sources":["../../src/helpers/findGeoColumn.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD;;;;;;;;;;;GAWG;AACH,wBAA8B,aAAa,CACzC,WAAW,EAAE,WAAW,EACxB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAMjB"}
+{"version":3,"file":"findGeoColumn.d.ts","sourceRoot":"","sources":["../../src/helpers/findGeoColumn.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD;;;;;;;;;;;;;GAaG;AACH,wBAA8B,aAAa,CACzC,WAAW,EAAE,WAAW,EACxB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAMjB"}

package/script/helpers/findGeoColumn.js

@@ -8,14 +8,16 @@ const findGeoColumnFromSchema_js_1 = __importDefault(require("./findGeoColumnFro
 /**
  * Returns the only geometry column in a table.
  *
- * @param simpleTable - The table to inspect.
- * @param method - The SDA method requesting a geometry column.
- * @returns A promise resolving to the name of the only geometry column.
- *
  * @example
  * ```ts
  * const column = await findGeoColumn(table, "getGeoData()");
  * ```
+ *
+ * @param simpleTable - The table to inspect.
+ *
+ * @param method - The SDA method requesting a geometry column.
+ *
+ * @returns A promise resolving to the name of the only geometry column.
  */
 async function findGeoColumn(simpleTable, method) {
     return (0, findGeoColumnFromSchema_js_1.default)(await simpleTable.getTypes(), method, simpleTable.name);

package/script/helpers/findGeoColumnFromSchema.d.ts

@@ -2,11 +2,6 @@ import type { TableSchema } from "./pendingOps.js";
 /**
  * Returns the only geometry column in a table schema.
  *
- * @param types - The table schema to inspect.
- * @param method - The SDA method requesting a geometry column.
- * @param tableName - The name of the table represented by the schema.
- * @returns The name of the only geometry column.
- *
  * @example
  * ```ts
  * const column = findGeoColumnFromSchema(
@@ -15,6 +10,14 @@ import type { TableSchema } from "./pendingOps.js";
  *   "places",
  * );
  * ```
+ *
+ * @param types - The table schema to inspect.
+ *
+ * @param method - The SDA method requesting a geometry column.
+ *
+ * @param tableName - The name of the table represented by the schema.
+ *
+ * @returns The name of the only geometry column.
  */
 export default function findGeoColumnFromSchema(types: TableSchema, method: string, tableName: string): string;
 //# sourceMappingURL=findGeoColumnFromSchema.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"findGeoColumnFromSchema.d.ts","sourceRoot":"","sources":["../../src/helpers/findGeoColumnFromSchema.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,OAAO,UAAU,uBAAuB,CAC7C,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,MAAM,CAoBR"}
+{"version":3,"file":"findGeoColumnFromSchema.d.ts","sourceRoot":"","sources":["../../src/helpers/findGeoColumnFromSchema.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,OAAO,UAAU,uBAAuB,CAC7C,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,MAAM,CAoBR"}