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

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

package/script/helpers/findGeoColumnFromSchema.js

@@ -8,11 +8,6 @@ const quoteIdentifier_js_1 = __importDefault(require("./quoteIdentifier.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(
@@ -21,6 +16,14 @@ const quoteIdentifier_js_1 = __importDefault(require("./quoteIdentifier.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.
  */
 function findGeoColumnFromSchema(types, method, tableName) {
     const geometryColumns = Object.keys(types).filter((column) => types[column].toLowerCase().includes("geometry")).sort();

package/script/helpers/fitUmapCurve.d.ts

@@ -0,0 +1,2 @@
+export default function fitUmapCurve(minDistance: number): [number, number];
+//# sourceMappingURL=fitUmapCurve.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fitUmapCurve.d.ts","sourceRoot":"","sources":["../../src/helpers/fitUmapCurve.ts"],"names":[],"mappings":"AAGA,MAAM,CAAC,OAAO,UAAU,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CA2D1E"}

package/script/helpers/fitUmapCurve.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = fitUmapCurve;
+// Least-squares fit of 1/(1+a*x^(2*b)) to the reference UMAP target curve.
+// Spread is fixed to one. See umap-learn's find_ab_params (0.5.9.post2).
+// A two-parameter damped Gauss-Newton solve avoids a runtime fitting dependency.
+function fitUmapCurve(minDistance) {
+    if (!Number.isFinite(minDistance) || minDistance < 0 || minDistance > 1) {
+        throw new Error("minDistance must be between zero and one.");
+    }
+    const samples = Array.from({ length: 299 }, (_, i) => {
+        const x = (i + 1) * 3 / 299;
+        return {
+            logX: Math.log(x),
+            target: Math.exp(-Math.max(0, x - minDistance)),
+        };
+    });
+    const loss = (logA, logB) => {
+        let sum = 0;
+        for (const { logX, target } of samples) {
+            const residual = 1 / (1 + Math.exp(logA + 2 * Math.exp(logB) * logX)) -
+                target;
+            sum += residual * residual;
+        }
+        return sum;
+    };
+    let logA = 0, logB = 0, damping = 1e-3;
+    let error = loss(logA, logB);
+    for (let iteration = 0; iteration < 100; iteration++) {
+        let aa = 0, ab = 0, bb = 0, ga = 0, gb = 0;
+        for (const { logX, target } of samples) {
+            const power = Math.exp(logA + 2 * Math.exp(logB) * logX);
+            const predicted = 1 / (1 + power);
+            const da = -power * predicted * predicted;
+            const db = da * 2 * Math.exp(logB) * logX;
+            aa += da * da;
+            ab += da * db;
+            bb += db * db;
+            ga += da * (predicted - target);
+            gb += db * (predicted - target);
+        }
+        const aDiagonal = aa + damping * Math.max(aa, 1e-12);
+        const bDiagonal = bb + damping * Math.max(bb, 1e-12);
+        const determinant = aDiagonal * bDiagonal - ab * ab;
+        if (!(determinant > 0))
+            throw new Error("UMAP curve fit became singular.");
+        const stepA = (ab * gb - bDiagonal * ga) / determinant;
+        const stepB = (ab * ga - aDiagonal * gb) / determinant;
+        const nextA = Math.max(-20, Math.min(20, logA + stepA));
+        const nextB = Math.max(-20, Math.min(20, logB + stepB));
+        const nextError = loss(nextA, nextB);
+        if (nextError < error) {
+            const improvement = error - nextError;
+            logA = nextA;
+            logB = nextB;
+            error = nextError;
+            damping = Math.max(damping / 3, 1e-12);
+            if (improvement < 1e-13)
+                return [Math.exp(logA), Math.exp(logB)];
+        }
+        else {
+            damping *= 10;
+            if (Math.max(Math.abs(ga), Math.abs(gb)) < 1e-7) {
+                return [Math.exp(logA), Math.exp(logB)];
+            }
+        }
+    }
+    throw new Error("UMAP curve fit did not converge.");
+}