@nshiab/simple-data-analysis-core 2.0.3 → 2.0.5

package/script/class/SimpleTable.js

@@ -22,6 +22,8 @@ const removeMissing_js_1 = __importDefault(require("../methods/removeMissing.js"
 const getColumns_js_1 = __importDefault(require("../methods/getColumns.js"));
 const getRowCount_js_1 = __importDefault(require("../methods/getRowCount.js"));
 const getCharacterCount_js_1 = __importDefault(require("../methods/getCharacterCount.js"));
+const addCharacterCount_js_1 = __importDefault(require("../methods/addCharacterCount.js"));
+const addWordCount_js_1 = __importDefault(require("../methods/addWordCount.js"));
 const getTypes_js_1 = __importDefault(require("../methods/getTypes.js"));
 const getHash_js_1 = __importDefault(require("../methods/getHash.js"));
 const getValues_js_1 = __importDefault(require("../methods/getValues.js"));
@@ -123,6 +125,7 @@ const length_js_1 = __importDefault(require("../methods/length.js"));
 const area_js_1 = __importDefault(require("../methods/area.js"));
 const reproject_js_1 = __importDefault(require("../methods/reproject.js"));
 const reducePrecision_js_1 = __importDefault(require("../methods/reducePrecision.js"));
+const addGeoNoise_js_1 = __importDefault(require("../methods/addGeoNoise.js"));
 const flipCoordinates_js_1 = __importDefault(require("../methods/flipCoordinates.js"));
 const addGeoType_js_1 = __importDefault(require("../methods/addGeoType.js"));
 const addGeoClosedStatus_js_1 = __importDefault(require("../methods/addGeoClosedStatus.js"));
@@ -137,6 +140,7 @@ const getSchema_js_1 = __importDefault(require("../methods/getSchema.js"));
 const outliersIQR_js_1 = __importDefault(require("../methods/outliersIQR.js"));
 const bins_js_1 = __importDefault(require("../methods/bins.js"));
 const round_js_1 = __importDefault(require("../methods/round.js"));
+const addNoise_js_1 = __importDefault(require("../methods/addNoise.js"));
 const rowToText_js_1 = __importDefault(require("../methods/rowToText.js"));
 const replaceNulls_js_1 = __importDefault(require("../methods/replaceNulls.js"));
 const pad_js_1 = __importDefault(require("../methods/pad.js"));
@@ -158,6 +162,7 @@ const insertRows_js_1 = __importDefault(require("../methods/insertRows.js"));
 const loadGeoData_js_1 = __importDefault(require("../methods/loadGeoData.js"));
 const loadOpenStreetMap_js_1 = __importDefault(require("../methods/loadOpenStreetMap.js"));
 const loadStatCanData_js_1 = __importDefault(require("../methods/loadStatCanData.js"));
+const loadYahooFinanceData_js_1 = __importDefault(require("../methods/loadYahooFinanceData.js"));
 const setTypes_js_1 = __importDefault(require("../methods/setTypes.js"));
 const flushAllTables_js_1 = __importDefault(require("../helpers/flushAllTables.js"));
 const queueOp_js_1 = __importDefault(require("../helpers/queueOp.js"));
@@ -341,7 +346,7 @@ class SimpleTable extends Simple_js_1.default {
         return this;
     }
     /**
-     * Loads an array of JavaScript objects into the table. This method queues the load; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
+     * Loads an array of JavaScript objects into the table. Types can also be specified for individual columns instead of inferred from their values. This method queues the load; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
      *
      * JavaScript `Date` values are inferred as DuckDB `TIMESTAMP` values. Their
      * instant is preserved, but JavaScript `Date` does not retain the timezone or
@@ -349,6 +354,8 @@ class SimpleTable extends Simple_js_1.default {
      * use `convert()` to parse them as temporal values.
      *
      * @param rows - An array of objects, where each object represents a row and its properties represent columns.
+     * @param options - Options for loading the array, captured when called.
+     * @param options.columnTypes - Types for specific columns; omitted columns are inferred. Values must be compatible with the selected type without losing information.
      * @returns The table, so methods can be chained.
      * @category Importing Data
      *
@@ -364,6 +371,15 @@ class SimpleTable extends Simple_js_1.default {
      *
      * @example
      * ```ts
+     * // Specify a numeric type for an all-null column
+     * await table.loadArray(
+     *   [{ name: "A", value: null }, { name: "B", value: null }],
+     *   { columnTypes: { value: "DOUBLE" } },
+     * ).log();
+     * ```
+     *
+     * @example
+     * ```ts
      * // The offset determines the instant; the loaded TIMESTAMP is returned as
      * // the equivalent UTC JavaScript Date.
      * await table.loadArray([{
@@ -371,8 +387,8 @@ class SimpleTable extends Simple_js_1.default {
      * }]).log();
      * ```
      */
-    loadArray(rows) {
-        (0, loadArray_js_1.default)(this, rows);
+    loadArray(rows, options = {}) {
+        (0, loadArray_js_1.default)(this, rows, options);
         return this;
     }
     /**
@@ -503,6 +519,70 @@ class SimpleTable extends Simple_js_1.default {
         (0, loadStatCanData_js_1.default)(this, pid, options);
         return this;
     }
+    /**
+     * Downloads historical market data from Yahoo Finance and loads it into this
+     * table as `datetime`, `open`, `high`, `low`, `close`, `adjustedClose`, and
+     * `volume` columns. `datetime` contains Yahoo's timestamps as JavaScript
+     * `Date` values. Unavailable values are preserved as `null`.
+     *
+     * All range boundaries are evaluated in UTC. Use ISO date-time strings ending
+     * in `Z`. Yahoo trading sessions may occur on a different UTC date from their
+     * exchange-local date, so choose the range appropriate for the market and
+     * interval. Avoid numeric constructors such as `new Date(2025, 2, 15)`, which
+     * use the runtime's local timezone.
+     *
+     * This method uses an undocumented Yahoo Finance endpoint and is not
+     * affiliated with or endorsed by Yahoo. It is provided for educational,
+     * research, and journalistic purposes. Before using it, review Yahoo's terms
+     * and any applicable data-provider restrictions.
+     *
+     * The method queues the download and load; they run when an async observer
+     * method (like `getData()` or `log()`) is awaited, or when `run()` is called.
+     *
+     * @param symbol - The stock or index symbol, such as `"AAPL"` or `"^GSPTSE"`.
+     * @param startDate - The inclusive UTC start of the requested range.
+     * @param endDate - The inclusive UTC end of the requested range. The UTC day,
+     * hour, or minute containing this instant is included, according to
+     * `interval`.
+     * @param interval - The interval between observations: daily, hourly, or every
+     * minute.
+     * @returns The table, so methods can be chained.
+     * @throws {RangeError} If either date is invalid or `endDate` is before `startDate`.
+     * @throws {Error} If Yahoo rejects the request or returns no data.
+     * @see https://legal.yahoo.com/us/en/yahoo/terms/otos/index.html
+     * @see https://help.yahoo.com/kb/finance/SLN2310.html
+     * @category Importing Data
+     *
+     * @example
+     * ```ts
+     * // Request daily observations using explicit UTC boundaries.
+     * await table
+     *   .loadYahooFinanceData(
+     *     "^GSPTSE",
+     *     new Date("2025-03-01T00:00:00Z"),
+     *     new Date("2025-03-15T00:00:00Z"),
+     *     "1d",
+     *   )
+     *   .log();
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Include the UTC hours from 13:00 through 16:00.
+     * await table
+     *   .loadYahooFinanceData(
+     *     "AAPL",
+     *     new Date("2025-03-14T13:00:00Z"),
+     *     new Date("2025-03-14T16:00:00Z"),
+     *     "1h",
+     *   )
+     *   .log();
+     * ```
+     */
+    loadYahooFinanceData(symbol, startDate, endDate, interval) {
+        (0, loadYahooFinanceData_js_1.default)(this, symbol, startDate, endDate, interval);
+        return this;
+    }
     /**
      * Loads geospatial data from an external file or URL into the table.
      *
@@ -2695,6 +2775,37 @@ class SimpleTable extends Simple_js_1.default {
         (0, round_js_1.default)(this, columns, options);
         return this;
     }
+    /**
+     * Adds independently generated uniform random noise to numeric values in one or more columns.
+     * Each changed value receives an offset between `-max` and `max`. Selected integer and decimal columns become `DOUBLE` columns so fractional noise is retained. This method adds random jitter; it does not provide anonymization or differential privacy guarantees.
+     *
+     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
+     *
+     * @param columns - The numeric column name or array of numeric column names to which noise will be added. When multiple columns are provided, each value receives an independent random offset.
+     * @param max - The maximum absolute offset, expressed in each column's units. Must be a finite number greater than or equal to `0`.
+     * @param options - An optional object with configuration options:
+     * @param options.onlyDuplicates - If `true`, adds noise only to values that occur more than once in their column. Each selected column is evaluated independently, and every occurrence of a duplicated value is changed. Defaults to `false`.
+     * @returns The table, so methods can be chained.
+     * @category Updating Data
+     *
+     * @example
+     * ```ts
+     * // Add an offset between -0.01 and 0.01 to every value
+     * await table.addNoise("measurement", 0.01).log();
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Add noise independently to duplicated x values and duplicated y values
+     * await table.addNoise(["x", "y"], 0.1, {
+     *   onlyDuplicates: true,
+     * }).log();
+     * ```
+     */
+    addNoise(columns, max, options = {}) {
+        (0, addNoise_js_1.default)(this, columns, max, options);
+        return this;
+    }
     /**
      * Updates values in a specified column using a SQL expression.
      *
@@ -2878,11 +2989,18 @@ class SimpleTable extends Simple_js_1.default {
      * | 2022 | 354 | 278   | 56        | 0.51    | 0.4       | 0.08          |
      * | 2023 | 856 | 321   | 221       | 0.61    | 0.23      | 0.16          |
      *
+     * @example
+     * ```ts
+     * // Compute percentages that sum to 100 on each row before rounding
+     * await table.rowProportions(["Men", "Women", "NonBinary"], { base: 100, decimals: 1 }).log();
+     * ```
+     *
      * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
      *
      * @param columns - An array of column names for which proportions will be computed on each row.
      * @param options - An optional object with configuration options:
      * @param options.suffix - A string suffix to append to the names of the new columns storing the computed proportions. Defaults to `"Perc"`.
+     * @param options.base - A finite positive value that the proportions in each row sum to before rounding. Defaults to `1`.
      * @param options.decimals - The number of decimal places to round the computed proportions. Defaults to `undefined` (no rounding).
      * @returns The table, so methods can be chained.
      * @category Analyzing Data
@@ -2947,6 +3065,7 @@ class SimpleTable extends Simple_js_1.default {
      * @param newColumn - The name of the new column where the proportions will be stored.
      * @param options - An optional object with configuration options:
      * @param options.by - The column name or an array of column names to partition by. Proportions are calculated independently within each group.
+     * @param options.base - A finite positive value that the proportions in the column or each group sum to before rounding. Defaults to `1`.
      * @param options.decimals - The number of decimal places to round the computed proportions. Defaults to `undefined` (no rounding).
      * @returns The table, so methods can be chained.
      * @category Analyzing Data
@@ -2965,6 +3084,12 @@ class SimpleTable extends Simple_js_1.default {
      *
      * @example
      * ```ts
+     * // Compute percentages that sum to 100 before rounding
+     * await table.columnProportions("sales", "sales_percentage", { base: 100, decimals: 1 }).log();
+     * ```
+     *
+     * @example
+     * ```ts
      * // Compute proportions for 'sales' by 'region' and 'product_type'
      * await table.columnProportions("sales", "sales_proportion", { by: ["region", "product_type"] }).log();
      * ```
@@ -3475,17 +3600,15 @@ class SimpleTable extends Simple_js_1.default {
      *
      * @example
      * ```ts
-     * // Count words correctly across multilingual article text.
-     * const segmenter = new Intl.Segmenter(undefined, { granularity: "word" });
+     * // Extract hostnames with JavaScript's URL parser.
      * const table = await sdb
      *   .newTable()
-     *   .loadData("articles.csv")
+     *   .loadData("websites.csv")
      *   .updateWithJS((rows) => {
      *     return rows.map((row) => ({
      *       ...row,
-     *       wordCount: typeof row.text === "string"
-     *         ? [...segmenter.segment(row.text)].filter((part) => part.isWordLike)
-     *           .length
+     *       hostname: typeof row.url === "string"
+     *         ? new URL(row.url).hostname
      *         : null,
      *     }));
      *   })
@@ -3634,8 +3757,52 @@ class SimpleTable extends Simple_js_1.default {
         const result = (await (0, getColumns_js_1.default)(this)).length;
         return result;
     }
+    /**
+     * Adds a new column containing the number of characters in each string in the specified column.
+     * Counts are based on Unicode code points, not grapheme clusters. A user-perceived character composed of multiple code points, such as some emoji or decomposed accented letters, counts as multiple characters.
+     * `NULL` input values produce `NULL` counts.
+     *
+     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
+     *
+     * @param column - The name of the column containing the strings to count.
+     * @param newColumn - The name of the new column where the character counts will be stored.
+     * @returns The table, so methods can be chained.
+     * @category Text Processing
+     *
+     * @example
+     * ```ts
+     * // Add a character count for each value in the 'name' column
+     * await table.addCharacterCount("name", "nameCharacterCount").log();
+     * ```
+     */
+    addCharacterCount(column, newColumn) {
+        (0, addCharacterCount_js_1.default)(this, column, newColumn);
+        return this;
+    }
+    /**
+     * Adds a new column containing the word count for each string in the specified column.
+     * A word is any contiguous sequence of non-whitespace characters. Spaces, tabs, and line breaks separate words. Punctuation is not removed, so a standalone punctuation sequence counts as a word. Text without whitespace counts as one word, regardless of language. Empty or whitespace-only strings produce `0`, and `NULL` input values produce `NULL` counts.
+     *
+     * This method queues the operation; it runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
+     *
+     * @param column - The name of the column containing the strings to count.
+     * @param newColumn - The name of the new column where the word counts will be stored.
+     * @returns The table, so methods can be chained.
+     * @category Text Processing
+     *
+     * @example
+     * ```ts
+     * // Add a word count for each value in the 'article' column
+     * await table.addWordCount("article", "wordCount").log();
+     * ```
+     */
+    addWordCount(column, newColumn) {
+        (0, addWordCount_js_1.default)(this, column, newColumn);
+        return this;
+    }
     /**
      * Returns the total number of characters in a column storing strings.
+     * Counts are based on Unicode code points, not grapheme clusters. A user-perceived character composed of multiple code points, such as some emoji or decomposed accented letters, counts as multiple characters.
      *
      * @param column - The name of the string column to count characters from.
      * @returns A promise that resolves to the total number of characters across all rows in the specified column.
@@ -4465,6 +4632,41 @@ class SimpleTable extends Simple_js_1.default {
         (0, flipCoordinates_js_1.default)(this, column);
         return this;
     }
+    /**
+     * Moves EPSG:4326 point geometries to random locations within a maximum great-circle distance of their original positions.
+     *
+     * Points are sampled uniformly within the requested distance using the spherical direct geodesic (destination-point) formula and the same spherical Earth model as DuckDB's `ST_Distance_Sphere()`. This accounts for longitude scale changing with latitude. This method adds random jitter; it does not provide anonymization or differential privacy guarantees.
+     *
+     * This method supports only `POINT` geometries in `EPSG:4326`. Null and empty geometries are preserved. It queues the operation; the operation runs when an async observer method (like `getData()` or `log()`) is awaited, or when `run()` is called.
+     *
+     * @param maxDistance - The maximum great-circle displacement in the selected unit. Must be a finite number greater than or equal to `0` and no greater than half Earth's circumference.
+     * @param options - An optional object with configuration options:
+     * @param options.column - The name of the EPSG:4326 point geometry column. If omitted, the method will automatically attempt to find a geometry column.
+     * @param options.unit - The unit of `maxDistance`: `"m"` for metres or `"km"` for kilometres. Defaults to `"m"`.
+     * @param options.onlyDuplicates - If `true`, moves only points whose complete original geometry occurs more than once in the selected geometry column. Every point in a duplicated group is moved. Defaults to `false`.
+     * @returns The table, so methods can be chained.
+     * @category Geospatial
+     *
+     * @example
+     * ```ts
+     * // Move every point by no more than 500 metres
+     * await table.addGeoNoise(500).log();
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Separate duplicated points by up to 0.1 kilometres
+     * await table.addGeoNoise(0.1, {
+     *   column: "geom",
+     *   unit: "km",
+     *   onlyDuplicates: true,
+     * }).log();
+     * ```
+     */
+    addGeoNoise(maxDistance, options = {}) {
+        (0, addGeoNoise_js_1.default)(this, maxDistance, options);
+        return this;
+    }
     /**
      * Reduces the precision of geometries in a specified column to a given number of decimal places.
      *

package/script/methods/addCharacterCount.d.ts

@@ -0,0 +1,3 @@
+import type SimpleTable from "../class/SimpleTable.js";
+export default function addCharacterCount(simpleTable: SimpleTable, column: string, newColumn: string): void;
+//# sourceMappingURL=addCharacterCount.d.ts.map

package/script/methods/addCharacterCount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addCharacterCount.d.ts","sourceRoot":"","sources":["../../src/methods/addCharacterCount.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAKvD,MAAM,CAAC,OAAO,UAAU,iBAAiB,CACvC,WAAW,EAAE,WAAW,EACxB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,QAclB"}

package/script/methods/addCharacterCount.js

@@ -0,0 +1,21 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = addCharacterCount;
+const assertNewColumns_js_1 = __importDefault(require("../helpers/assertNewColumns.js"));
+const queueOp_js_1 = __importDefault(require("../helpers/queueOp.js"));
+const quoteIdentifier_js_1 = __importDefault(require("../helpers/quoteIdentifier.js"));
+function addCharacterCount(simpleTable, column, newColumn) {
+    (0, queueOp_js_1.default)(simpleTable, {
+        kind: "fusable",
+        method: "addCharacterCount()",
+        parameters: { column, newColumn },
+        needsSchema: true,
+        buildSelect: (input, types) => {
+            (0, assertNewColumns_js_1.default)(types, [newColumn], "addCharacterCount()");
+            return `SELECT *, LENGTH(${(0, quoteIdentifier_js_1.default)(column)}) AS ${(0, quoteIdentifier_js_1.default)(newColumn)} FROM ${input}`;
+        },
+    });
+}

package/script/methods/addGeoNoise.d.ts

@@ -0,0 +1,7 @@
+import type SimpleTable from "../class/SimpleTable.js";
+export default function addGeoNoise(simpleTable: SimpleTable, maxDistance: number, options?: {
+    column?: string;
+    unit?: "m" | "km";
+    onlyDuplicates?: boolean;
+}): void;
+//# sourceMappingURL=addGeoNoise.d.ts.map

package/script/methods/addGeoNoise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addGeoNoise.d.ts","sourceRoot":"","sources":["../../src/methods/addGeoNoise.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAKvD,MAAM,CAAC,OAAO,UAAU,WAAW,CACjC,WAAW,EAAE,WAAW,EACxB,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE;IACP,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;IAClB,cAAc,CAAC,EAAE,OAAO,CAAC;CACrB,QA2CP"}

package/script/methods/addGeoNoise.js

@@ -0,0 +1,141 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = addGeoNoise;
+const findGeoColumnFromSchema_js_1 = __importDefault(require("../helpers/findGeoColumnFromSchema.js"));
+const queueOp_js_1 = __importDefault(require("../helpers/queueOp.js"));
+const quoteIdentifier_js_1 = __importDefault(require("../helpers/quoteIdentifier.js"));
+// This is the mean Earth radius used by DuckDB's ST_Distance_Sphere().
+const EARTH_RADIUS_METERS = 6_371_000;
+function addGeoNoise(simpleTable, maxDistance, options = {}) {
+    // This validation doesn't need the database, so it stays at call time.
+    if (!Number.isFinite(maxDistance) || maxDistance < 0) {
+        throw new Error("addGeoNoise() maxDistance must be a finite number greater than or equal to 0.");
+    }
+    if (options.unit !== undefined && options.unit !== "m" && options.unit !== "km") {
+        throw new Error('addGeoNoise() options.unit must be "m" or "km".');
+    }
+    options = structuredClone(options);
+    const maxDistanceMeters = options.unit === "km"
+        ? maxDistance * 1_000
+        : maxDistance;
+    if (maxDistanceMeters > Math.PI * EARTH_RADIUS_METERS) {
+        throw new Error("addGeoNoise() maxDistance cannot exceed half the Earth's circumference.");
+    }
+    (0, queueOp_js_1.default)(simpleTable, {
+        kind: "fusable",
+        method: "addGeoNoise()",
+        parameters: { maxDistance, options },
+        needsSchema: true,
+        needsSpatial: true,
+        preservesSchema: true,
+        buildSelect: (input, schema) => {
+            const column = options.column ??
+                (0, findGeoColumnFromSchema_js_1.default)(schema, "addGeoNoise()", simpleTable.name);
+            return addGeoNoiseSelect(input, schema, column, maxDistanceMeters, options.onlyDuplicates === true);
+        },
+    });
+}
+function addGeoNoiseSelect(input, schema, column, maxDistanceMeters, onlyDuplicates) {
+    const type = schema[column];
+    if (type === undefined) {
+        throw new Error(`addGeoNoise() could not find column ${(0, quoteIdentifier_js_1.default)(column)}.`);
+    }
+    if (type !== "GEOMETRY('EPSG:4326')") {
+        throw new Error(`addGeoNoise() requires an EPSG:4326 geometry column, but ${(0, quoteIdentifier_js_1.default)(column)} has type ${type}. Reproject it to EPSG:4326 first.`);
+    }
+    const internalNames = makeInternalNames(schema, input);
+    const quotedColumn = (0, quoteIdentifier_js_1.default)(column);
+    const pointError = `error('addGeoNoise() requires POINT geometries in column ${column.replaceAll("'", "''")}.')`;
+    const coordinateGuard = (coordinate) => `CASE
+    WHEN ${quotedColumn} IS NULL OR ST_IsEmpty(${quotedColumn}) THEN NULL
+    WHEN CAST(ST_GeometryType(${quotedColumn}) AS VARCHAR) <> 'POINT'
+      THEN ${pointError}
+    ELSE radians(ST_${coordinate}(${quotedColumn}))
+  END`;
+    const duplicateCount = onlyDuplicates
+        ? `COUNT(*) OVER (PARTITION BY ${quotedColumn})`
+        : "2";
+    const maxAngularDistance = maxDistanceMeters / EARTH_RADIUS_METERS;
+    const latitudeExpression = `asin(
+    sin(${(0, quoteIdentifier_js_1.default)(internalNames.latitude)}) * cos(${(0, quoteIdentifier_js_1.default)(internalNames.angularDistance)}) +
+    cos(${(0, quoteIdentifier_js_1.default)(internalNames.latitude)}) * sin(${(0, quoteIdentifier_js_1.default)(internalNames.angularDistance)}) * cos(${(0, quoteIdentifier_js_1.default)(internalNames.bearing)})
+  )`;
+    const longitudeExpression = `${(0, quoteIdentifier_js_1.default)(internalNames.longitude)} + atan2(
+    sin(${(0, quoteIdentifier_js_1.default)(internalNames.bearing)}) * sin(${(0, quoteIdentifier_js_1.default)(internalNames.angularDistance)}) * cos(${(0, quoteIdentifier_js_1.default)(internalNames.latitude)}),
+    cos(${(0, quoteIdentifier_js_1.default)(internalNames.angularDistance)}) -
+      sin(${(0, quoteIdentifier_js_1.default)(internalNames.latitude)}) * sin(${(0, quoteIdentifier_js_1.default)(internalNames.destinationLatitude)})
+  )`;
+    const replacement = `CASE
+    WHEN ${quotedColumn} IS NULL OR ST_IsEmpty(${quotedColumn}) THEN ${quotedColumn}
+    WHEN ${(0, quoteIdentifier_js_1.default)(internalNames.duplicateCount)} <= 1 THEN ${quotedColumn}
+    ELSE ST_Point(
+      degrees(atan2(
+        sin(${(0, quoteIdentifier_js_1.default)(internalNames.destinationLongitude)}),
+        cos(${(0, quoteIdentifier_js_1.default)(internalNames.destinationLongitude)})
+      )),
+      degrees(${(0, quoteIdentifier_js_1.default)(internalNames.destinationLatitude)})
+    )::GEOMETRY('EPSG:4326')
+  END AS ${quotedColumn}`;
+    const outputColumns = Object.keys(schema).map((outputColumn) => outputColumn === column ? replacement : (0, quoteIdentifier_js_1.default)(outputColumn)).join(", ");
+    return `WITH ${(0, quoteIdentifier_js_1.default)(internalNames.randomValues)} AS MATERIALIZED (
+    SELECT *,
+      random() AS ${(0, quoteIdentifier_js_1.default)(internalNames.distanceRandom)},
+      random() AS ${(0, quoteIdentifier_js_1.default)(internalNames.bearingRandom)},
+      ${duplicateCount} AS ${(0, quoteIdentifier_js_1.default)(internalNames.duplicateCount)}
+    FROM ${input}
+  ),
+  ${(0, quoteIdentifier_js_1.default)(internalNames.start)} AS (
+    SELECT *,
+      ${coordinateGuard("Y")} AS ${(0, quoteIdentifier_js_1.default)(internalNames.latitude)},
+      ${coordinateGuard("X")} AS ${(0, quoteIdentifier_js_1.default)(internalNames.longitude)},
+      2 * pi() * ${(0, quoteIdentifier_js_1.default)(internalNames.bearingRandom)} AS ${(0, quoteIdentifier_js_1.default)(internalNames.bearing)},
+      2 * asin(
+        sqrt(${(0, quoteIdentifier_js_1.default)(internalNames.distanceRandom)}) *
+        sin(${maxAngularDistance} / 2)
+      ) AS ${(0, quoteIdentifier_js_1.default)(internalNames.angularDistance)}
+    FROM ${(0, quoteIdentifier_js_1.default)(internalNames.randomValues)}
+  ),
+  ${(0, quoteIdentifier_js_1.default)(internalNames.destinationLatitudeCte)} AS (
+    SELECT *, ${latitudeExpression} AS ${(0, quoteIdentifier_js_1.default)(internalNames.destinationLatitude)}
+    FROM ${(0, quoteIdentifier_js_1.default)(internalNames.start)}
+  ),
+  ${(0, quoteIdentifier_js_1.default)(internalNames.destination)} AS (
+    SELECT *, ${longitudeExpression} AS ${(0, quoteIdentifier_js_1.default)(internalNames.destinationLongitude)}
+    FROM ${(0, quoteIdentifier_js_1.default)(internalNames.destinationLatitudeCte)}
+  )
+  SELECT ${outputColumns}
+  FROM ${(0, quoteIdentifier_js_1.default)(internalNames.destination)}`;
+}
+function makeInternalNames(schema, input) {
+    const used = new Set(Object.keys(schema));
+    if (input.startsWith('"') && input.endsWith('"')) {
+        used.add(input.slice(1, -1).replaceAll('""', '"'));
+    }
+    const next = (base) => {
+        let name = base;
+        let suffix = 2;
+        while (used.has(name)) {
+            name = `${base}_${suffix++}`;
+        }
+        used.add(name);
+        return name;
+    };
+    return {
+        randomValues: next("__sda_add_geo_noise_random_values"),
+        start: next("__sda_add_geo_noise_start"),
+        destinationLatitudeCte: next("__sda_add_geo_noise_latitude_result"),
+        destination: next("__sda_add_geo_noise_result"),
+        distanceRandom: next("__sda_add_geo_noise_distance_random"),
+        bearingRandom: next("__sda_add_geo_noise_bearing_random"),
+        duplicateCount: next("__sda_add_geo_noise_duplicate_count"),
+        latitude: next("__sda_add_geo_noise_latitude"),
+        longitude: next("__sda_add_geo_noise_longitude"),
+        bearing: next("__sda_add_geo_noise_bearing"),
+        angularDistance: next("__sda_add_geo_noise_angular_distance"),
+        destinationLatitude: next("__sda_add_geo_noise_destination_latitude"),
+        destinationLongitude: next("__sda_add_geo_noise_destination_longitude"),
+    };
+}

package/script/methods/addNoise.d.ts

@@ -0,0 +1,5 @@
+import type SimpleTable from "../class/SimpleTable.js";
+export default function addNoise(simpleTable: SimpleTable, columns: string | string[], max: number, options?: {
+    onlyDuplicates?: boolean;
+}): void;
+//# sourceMappingURL=addNoise.d.ts.map

package/script/methods/addNoise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addNoise.d.ts","sourceRoot":"","sources":["../../src/methods/addNoise.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD,MAAM,CAAC,OAAO,UAAU,QAAQ,CAC9B,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,EAC1B,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;IAAE,cAAc,CAAC,EAAE,OAAO,CAAA;CAAO,QAwC3C"}

package/script/methods/addNoise.js

@@ -0,0 +1,59 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = addNoise;
+const assertColumnsExist_js_1 = __importDefault(require("../helpers/assertColumnsExist.js"));
+const keepNumericalColumns_js_1 = __importDefault(require("../helpers/keepNumericalColumns.js"));
+const queueOp_js_1 = __importDefault(require("../helpers/queueOp.js"));
+const quoteIdentifier_js_1 = __importDefault(require("../helpers/quoteIdentifier.js"));
+const stringToArray_js_1 = __importDefault(require("../helpers/stringToArray.js"));
+function addNoise(simpleTable, columns, max, options = {}) {
+    // This validation doesn't need the database, so it stays at call time.
+    if (!Number.isFinite(max) || max < 0) {
+        throw new Error("addNoise() max must be a finite number greater than or equal to 0.");
+    }
+    const cols = (0, stringToArray_js_1.default)(columns);
+    if (cols.length === 0) {
+        throw new Error("addNoise() requires at least one column.");
+    }
+    const duplicateColumns = cols.filter((column, index) => cols.indexOf(column) !== index);
+    if (duplicateColumns.length > 0) {
+        const duplicates = [...new Set(duplicateColumns)];
+        throw new Error(`addNoise() received duplicate column${duplicates.length === 1 ? "" : "s"} ${duplicates.map(quoteIdentifier_js_1.default).join(", ")}. Include each column only once.`);
+    }
+    options = structuredClone(options);
+    (0, queueOp_js_1.default)(simpleTable, {
+        kind: "fusable",
+        method: "addNoise()",
+        parameters: { columns: cols, max, options },
+        needsSchema: true,
+        outputSchema: (schema) => ({
+            ...schema,
+            ...Object.fromEntries(cols.map((column) => [column, "DOUBLE"])),
+        }),
+        buildSelect: (input, schema) => addNoiseSelect(input, schema, cols, max, options.onlyDuplicates === true),
+    });
+}
+function addNoiseSelect(input, schema, columns, max, onlyDuplicates) {
+    (0, assertColumnsExist_js_1.default)(schema, columns, "addNoise()");
+    const numericalColumns = new Set((0, keepNumericalColumns_js_1.default)(schema));
+    const nonNumericalColumns = columns.filter((column) => !numericalColumns.has(column));
+    if (nonNumericalColumns.length > 0) {
+        throw new Error(`addNoise() requires numeric columns, but ${nonNumericalColumns.map((column) => `${(0, quoteIdentifier_js_1.default)(column)} has type ${schema[column]}`).join(", ")}. Convert ${nonNumericalColumns.length === 1 ? "it" : "them"} to a numeric type first.`);
+    }
+    const replacements = columns.map((column) => {
+        const quotedColumn = (0, quoteIdentifier_js_1.default)(column);
+        const duplicateCondition = onlyDuplicates
+            ? `COUNT(*) OVER (PARTITION BY ${quotedColumn}) > 1`
+            : "TRUE";
+        return `CASE
+      WHEN ${quotedColumn} IS NULL THEN NULL
+      WHEN ${duplicateCondition}
+        THEN CAST(${quotedColumn} AS DOUBLE) + (random() * 2 - 1) * ${max}
+      ELSE CAST(${quotedColumn} AS DOUBLE)
+    END AS ${quotedColumn}`;
+    }).join(", ");
+    return `SELECT * REPLACE (${replacements}) FROM ${input}`;
+}

package/script/methods/addWordCount.d.ts

@@ -0,0 +1,3 @@
+import type SimpleTable from "../class/SimpleTable.js";
+export default function addWordCount(simpleTable: SimpleTable, column: string, newColumn: string): void;
+//# sourceMappingURL=addWordCount.d.ts.map

package/script/methods/addWordCount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addWordCount.d.ts","sourceRoot":"","sources":["../../src/methods/addWordCount.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAKvD,MAAM,CAAC,OAAO,UAAU,YAAY,CAClC,WAAW,EAAE,WAAW,EACxB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,QAclB"}

package/script/methods/addWordCount.js

@@ -0,0 +1,21 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = addWordCount;
+const assertNewColumns_js_1 = __importDefault(require("../helpers/assertNewColumns.js"));
+const queueOp_js_1 = __importDefault(require("../helpers/queueOp.js"));
+const quoteIdentifier_js_1 = __importDefault(require("../helpers/quoteIdentifier.js"));
+function addWordCount(simpleTable, column, newColumn) {
+    (0, queueOp_js_1.default)(simpleTable, {
+        kind: "fusable",
+        method: "addWordCount()",
+        parameters: { column, newColumn },
+        needsSchema: true,
+        buildSelect: (input, types) => {
+            (0, assertNewColumns_js_1.default)(types, [newColumn], "addWordCount()");
+            return `SELECT *, ARRAY_LENGTH(REGEXP_EXTRACT_ALL(${(0, quoteIdentifier_js_1.default)(column)}, '[^[:space:]]+')) AS ${(0, quoteIdentifier_js_1.default)(newColumn)} FROM ${input}`;
+        },
+    });
+}

package/script/methods/columnProportions.d.ts

@@ -1,6 +1,7 @@
 import type SimpleTable from "../class/SimpleTable.js";
 export default function columnProportions(simpleTable: SimpleTable, column: string, newColumn: string, options?: {
     by?: string | string[];
+    base?: number;
     decimals?: number;
 }): void;
 //# sourceMappingURL=columnProportions.d.ts.map

package/script/methods/columnProportions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"columnProportions.d.ts","sourceRoot":"","sources":["../../src/methods/columnProportions.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD,MAAM,CAAC,OAAO,UAAU,iBAAiB,CACvC,WAAW,EAAE,WAAW,EACxB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;IACP,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACd,QA4BP"}
+{"version":3,"file":"columnProportions.d.ts","sourceRoot":"","sources":["../../src/methods/columnProportions.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD,MAAM,CAAC,OAAO,UAAU,iBAAiB,CACvC,WAAW,EAAE,WAAW,EACxB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;IACP,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACd,QAqCP"}