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

package/esm/class/SimpleTable.js

@@ -17,6 +17,8 @@ import removeMissing from "../methods/removeMissing.js";
 import getColumns from "../methods/getColumns.js";
 import getRowCount from "../methods/getRowCount.js";
 import getCharacterCount from "../methods/getCharacterCount.js";
+import addCharacterCount from "../methods/addCharacterCount.js";
+import addWordCount from "../methods/addWordCount.js";
 import getTypes from "../methods/getTypes.js";
 import getHash from "../methods/getHash.js";
 import getValues from "../methods/getValues.js";
@@ -118,6 +120,7 @@ import length from "../methods/length.js";
 import area from "../methods/area.js";
 import reproject from "../methods/reproject.js";
 import reducePrecision from "../methods/reducePrecision.js";
+import addGeoNoise from "../methods/addGeoNoise.js";
 import flipCoordinates from "../methods/flipCoordinates.js";
 import addGeoType from "../methods/addGeoType.js";
 import addGeoClosedStatus from "../methods/addGeoClosedStatus.js";
@@ -132,6 +135,7 @@ import getSchema from "../methods/getSchema.js";
 import outliersIQR from "../methods/outliersIQR.js";
 import bins from "../methods/bins.js";
 import round from "../methods/round.js";
+import addNoise from "../methods/addNoise.js";
 import rowToText from "../methods/rowToText.js";
 import replaceNulls from "../methods/replaceNulls.js";
 import pad from "../methods/pad.js";
@@ -153,6 +157,7 @@ import insertRows from "../methods/insertRows.js";
 import loadGeoData from "../methods/loadGeoData.js";
 import loadOpenStreetMap from "../methods/loadOpenStreetMap.js";
 import loadStatCanData from "../methods/loadStatCanData.js";
+import loadYahooFinanceData from "../methods/loadYahooFinanceData.js";
 import setTypes from "../methods/setTypes.js";
 import flushAllTables from "../helpers/flushAllTables.js";
 import queueOp from "../helpers/queueOp.js";
@@ -336,7 +341,7 @@ class SimpleTable extends Simple {
         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
@@ -344,6 +349,8 @@ class SimpleTable extends Simple {
      * 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
      *
@@ -359,6 +366,15 @@ class SimpleTable extends Simple {
      *
      * @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([{
@@ -366,8 +382,8 @@ class SimpleTable extends Simple {
      * }]).log();
      * ```
      */
-    loadArray(rows) {
-        loadArray(this, rows);
+    loadArray(rows, options = {}) {
+        loadArray(this, rows, options);
         return this;
     }
     /**
@@ -498,6 +514,70 @@ class SimpleTable extends Simple {
         loadStatCanData(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) {
+        loadYahooFinanceData(this, symbol, startDate, endDate, interval);
+        return this;
+    }
     /**
      * Loads geospatial data from an external file or URL into the table.
      *
@@ -2690,6 +2770,37 @@ class SimpleTable extends Simple {
         round(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 = {}) {
+        addNoise(this, columns, max, options);
+        return this;
+    }
     /**
      * Updates values in a specified column using a SQL expression.
      *
@@ -2873,11 +2984,18 @@ class SimpleTable extends Simple {
      * | 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
@@ -2942,6 +3060,7 @@ class SimpleTable extends Simple {
      * @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
@@ -2960,6 +3079,12 @@ class SimpleTable extends Simple {
      *
      * @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();
      * ```
@@ -3470,17 +3595,15 @@ class SimpleTable extends Simple {
      *
      * @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,
      *     }));
      *   })
@@ -3629,8 +3752,52 @@ class SimpleTable extends Simple {
         const result = (await getColumns(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) {
+        addCharacterCount(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) {
+        addWordCount(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.
@@ -4460,6 +4627,41 @@ class SimpleTable extends Simple {
         flipCoordinates(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 = {}) {
+        addGeoNoise(this, maxDistance, options);
+        return this;
+    }
     /**
      * Reduces the precision of geometries in a specified column to a given number of decimal places.
      *

package/esm/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/esm/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/esm/methods/addCharacterCount.js

@@ -0,0 +1,15 @@
+import assertNewColumns from "../helpers/assertNewColumns.js";
+import queueOp from "../helpers/queueOp.js";
+import quoteIdentifier from "../helpers/quoteIdentifier.js";
+export default function addCharacterCount(simpleTable, column, newColumn) {
+    queueOp(simpleTable, {
+        kind: "fusable",
+        method: "addCharacterCount()",
+        parameters: { column, newColumn },
+        needsSchema: true,
+        buildSelect: (input, types) => {
+            assertNewColumns(types, [newColumn], "addCharacterCount()");
+            return `SELECT *, LENGTH(${quoteIdentifier(column)}) AS ${quoteIdentifier(newColumn)} FROM ${input}`;
+        },
+    });
+}

package/esm/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/esm/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/esm/methods/addGeoNoise.js

@@ -0,0 +1,135 @@
+import findGeoColumnFromSchema from "../helpers/findGeoColumnFromSchema.js";
+import queueOp from "../helpers/queueOp.js";
+import quoteIdentifier from "../helpers/quoteIdentifier.js";
+// This is the mean Earth radius used by DuckDB's ST_Distance_Sphere().
+const EARTH_RADIUS_METERS = 6_371_000;
+export default 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.");
+    }
+    queueOp(simpleTable, {
+        kind: "fusable",
+        method: "addGeoNoise()",
+        parameters: { maxDistance, options },
+        needsSchema: true,
+        needsSpatial: true,
+        preservesSchema: true,
+        buildSelect: (input, schema) => {
+            const column = options.column ??
+                findGeoColumnFromSchema(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 ${quoteIdentifier(column)}.`);
+    }
+    if (type !== "GEOMETRY('EPSG:4326')") {
+        throw new Error(`addGeoNoise() requires an EPSG:4326 geometry column, but ${quoteIdentifier(column)} has type ${type}. Reproject it to EPSG:4326 first.`);
+    }
+    const internalNames = makeInternalNames(schema, input);
+    const quotedColumn = quoteIdentifier(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(${quoteIdentifier(internalNames.latitude)}) * cos(${quoteIdentifier(internalNames.angularDistance)}) +
+    cos(${quoteIdentifier(internalNames.latitude)}) * sin(${quoteIdentifier(internalNames.angularDistance)}) * cos(${quoteIdentifier(internalNames.bearing)})
+  )`;
+    const longitudeExpression = `${quoteIdentifier(internalNames.longitude)} + atan2(
+    sin(${quoteIdentifier(internalNames.bearing)}) * sin(${quoteIdentifier(internalNames.angularDistance)}) * cos(${quoteIdentifier(internalNames.latitude)}),
+    cos(${quoteIdentifier(internalNames.angularDistance)}) -
+      sin(${quoteIdentifier(internalNames.latitude)}) * sin(${quoteIdentifier(internalNames.destinationLatitude)})
+  )`;
+    const replacement = `CASE
+    WHEN ${quotedColumn} IS NULL OR ST_IsEmpty(${quotedColumn}) THEN ${quotedColumn}
+    WHEN ${quoteIdentifier(internalNames.duplicateCount)} <= 1 THEN ${quotedColumn}
+    ELSE ST_Point(
+      degrees(atan2(
+        sin(${quoteIdentifier(internalNames.destinationLongitude)}),
+        cos(${quoteIdentifier(internalNames.destinationLongitude)})
+      )),
+      degrees(${quoteIdentifier(internalNames.destinationLatitude)})
+    )::GEOMETRY('EPSG:4326')
+  END AS ${quotedColumn}`;
+    const outputColumns = Object.keys(schema).map((outputColumn) => outputColumn === column ? replacement : quoteIdentifier(outputColumn)).join(", ");
+    return `WITH ${quoteIdentifier(internalNames.randomValues)} AS MATERIALIZED (
+    SELECT *,
+      random() AS ${quoteIdentifier(internalNames.distanceRandom)},
+      random() AS ${quoteIdentifier(internalNames.bearingRandom)},
+      ${duplicateCount} AS ${quoteIdentifier(internalNames.duplicateCount)}
+    FROM ${input}
+  ),
+  ${quoteIdentifier(internalNames.start)} AS (
+    SELECT *,
+      ${coordinateGuard("Y")} AS ${quoteIdentifier(internalNames.latitude)},
+      ${coordinateGuard("X")} AS ${quoteIdentifier(internalNames.longitude)},
+      2 * pi() * ${quoteIdentifier(internalNames.bearingRandom)} AS ${quoteIdentifier(internalNames.bearing)},
+      2 * asin(
+        sqrt(${quoteIdentifier(internalNames.distanceRandom)}) *
+        sin(${maxAngularDistance} / 2)
+      ) AS ${quoteIdentifier(internalNames.angularDistance)}
+    FROM ${quoteIdentifier(internalNames.randomValues)}
+  ),
+  ${quoteIdentifier(internalNames.destinationLatitudeCte)} AS (
+    SELECT *, ${latitudeExpression} AS ${quoteIdentifier(internalNames.destinationLatitude)}
+    FROM ${quoteIdentifier(internalNames.start)}
+  ),
+  ${quoteIdentifier(internalNames.destination)} AS (
+    SELECT *, ${longitudeExpression} AS ${quoteIdentifier(internalNames.destinationLongitude)}
+    FROM ${quoteIdentifier(internalNames.destinationLatitudeCte)}
+  )
+  SELECT ${outputColumns}
+  FROM ${quoteIdentifier(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/esm/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/esm/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/esm/methods/addNoise.js

@@ -0,0 +1,53 @@
+import assertColumnsExist from "../helpers/assertColumnsExist.js";
+import keepNumericalColumns from "../helpers/keepNumericalColumns.js";
+import queueOp from "../helpers/queueOp.js";
+import quoteIdentifier from "../helpers/quoteIdentifier.js";
+import stringToArray from "../helpers/stringToArray.js";
+export default 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 = stringToArray(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).join(", ")}. Include each column only once.`);
+    }
+    options = structuredClone(options);
+    queueOp(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) {
+    assertColumnsExist(schema, columns, "addNoise()");
+    const numericalColumns = new Set(keepNumericalColumns(schema));
+    const nonNumericalColumns = columns.filter((column) => !numericalColumns.has(column));
+    if (nonNumericalColumns.length > 0) {
+        throw new Error(`addNoise() requires numeric columns, but ${nonNumericalColumns.map((column) => `${quoteIdentifier(column)} has type ${schema[column]}`).join(", ")}. Convert ${nonNumericalColumns.length === 1 ? "it" : "them"} to a numeric type first.`);
+    }
+    const replacements = columns.map((column) => {
+        const quotedColumn = quoteIdentifier(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/esm/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/esm/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/esm/methods/addWordCount.js

@@ -0,0 +1,15 @@
+import assertNewColumns from "../helpers/assertNewColumns.js";
+import queueOp from "../helpers/queueOp.js";
+import quoteIdentifier from "../helpers/quoteIdentifier.js";
+export default function addWordCount(simpleTable, column, newColumn) {
+    queueOp(simpleTable, {
+        kind: "fusable",
+        method: "addWordCount()",
+        parameters: { column, newColumn },
+        needsSchema: true,
+        buildSelect: (input, types) => {
+            assertNewColumns(types, [newColumn], "addWordCount()");
+            return `SELECT *, ARRAY_LENGTH(REGEXP_EXTRACT_ALL(${quoteIdentifier(column)}, '[^[:space:]]+')) AS ${quoteIdentifier(newColumn)} FROM ${input}`;
+        },
+    });
+}

package/esm/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/esm/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"}

package/esm/methods/columnProportions.js

@@ -3,6 +3,10 @@ import assertNewColumns from "../helpers/assertNewColumns.js";
 import queueOp from "../helpers/queueOp.js";
 import stringToArray from "../helpers/stringToArray.js";
 export default function columnProportions(simpleTable, column, newColumn, options = {}) {
+    if (options.base !== undefined &&
+        (!Number.isFinite(options.base) || options.base <= 0)) {
+        throw new Error("columnProportions() options.base must be a finite number greater than 0.");
+    }
     options = structuredClone(options);
     queueOp(simpleTable, {
         kind: "fusable",
@@ -15,9 +19,10 @@ export default function columnProportions(simpleTable, column, newColumn, option
             const partition = by.length === 0
                 ? ""
                 : `PARTITION BY ${by.map((d) => `${quoteIdentifier(d)}`).join(",")}`;
+            const proportion = `${quoteIdentifier(column)} / sum(${quoteIdentifier(column)}) OVER(${partition}) * ${options.base ?? 1}`;
             return typeof options.decimals === "number"
-                ? `SELECT *, ROUND(${quoteIdentifier(column)} / sum(${quoteIdentifier(column)}) OVER(${partition}), ${options.decimals}) AS ${quoteIdentifier(newColumn)} FROM ${input}`
-                : `SELECT *, ${quoteIdentifier(column)} / sum(${quoteIdentifier(column)}) OVER(${partition}) AS ${quoteIdentifier(newColumn)} FROM ${input}`;
+                ? `SELECT *, ROUND(${proportion}, ${options.decimals}) AS ${quoteIdentifier(newColumn)} FROM ${input}`
+                : `SELECT *, ${proportion} AS ${quoteIdentifier(newColumn)} FROM ${input}`;
         },
     });
 }