@mostlyrightmd/core 0.1.0-rc.7

package/dist/transforms/index.d.cts

@@ -0,0 +1,193 @@
+/**
+ * Shift a column by `n` rows.
+ *
+ * Mirrors Python `pd.Series.shift(periods=n)` semantics: at output index `i`,
+ * the derived column carries `rows[i-n][col]` if available, else `null`.
+ *
+ * @param rows  input rows (NOT mutated; pure function)
+ * @param col   column name to lag
+ * @param n     positive integer; rows at index `< n` get `null` in the derived column
+ * @returns     new array of rows, each carrying `{col}_lag_{n}` derived column
+ * @throws RangeError if `n < 1` or `!Number.isInteger(n)`
+ */
+declare function lag<Row extends Record<string, unknown>>(rows: ReadonlyArray<Row>, col: string, n?: number): ReadonlyArray<Row & Record<string, number | null>>;
+
+/**
+ * First (or nth-order) discrete difference of a column.
+ *
+ * At output index `i`, the derived column carries
+ * `rows[i][col] - rows[i-n][col]` if both are finite numbers, else `null`.
+ *
+ * @param rows  input rows (NOT mutated; pure function)
+ * @param col   column name to difference
+ * @param n     positive integer step (default 1)
+ * @returns     new array of rows, each carrying `{col}_diff_{n}` derived column
+ * @throws RangeError if `n < 1` or `!Number.isInteger(n)`
+ */
+declare function diff<Row extends Record<string, unknown>>(rows: ReadonlyArray<Row>, col: string, n?: number): ReadonlyArray<Row & Record<string, number | null>>;
+/**
+ * Second discrete difference of a column.
+ *
+ * Equivalent to `diff(diff(col))`. The first two output rows carry `null`
+ * (no prior diff available). Mirrors Python `df[column].diff().diff()` which
+ * returns a single Series — so the TS output carries ONLY `{col}_diff2`,
+ * NOT the intermediate `{col}_diff_1` from the first pass.
+ *
+ * @param rows  input rows (NOT mutated; pure function)
+ * @param col   column name to second-difference
+ * @returns     new array of rows, each carrying `{col}_diff2` derived column
+ */
+declare function diff2<Row extends Record<string, unknown>>(rows: ReadonlyArray<Row>, col: string): ReadonlyArray<Row & Record<string, number | null>>;
+
+/** The set of reducer names accepted by `rolling`. Ordering is API surface. */
+declare const ROLLING_FNS: readonly ["mean", "median", "min", "max", "std", "count"];
+/** Union of the six reducer-name string literals. */
+type RollingFn = (typeof ROLLING_FNS)[number];
+/**
+ * Windowed reduction over a numeric column.
+ *
+ * At each output row `i`, the window covers
+ * `rows[max(0, i-window+1) .. i]` (inclusive both ends), so the first
+ * `window-1` rows compute against a partial (still-filling) window —
+ * `min_periods=1` semantics from Python.
+ *
+ * @param rows    input rows (NOT mutated; pure function)
+ * @param col     column name to reduce over
+ * @param window  positive integer window size (≥ 1)
+ * @param fn      one of `'mean' | 'median' | 'min' | 'max' | 'std' | 'count'`
+ * @returns       new array of rows, each carrying `{col}_rolling_{window}_{fn}`
+ * @throws RangeError if `window < 1`, non-integer, or `fn` is not a `RollingFn`
+ */
+declare function rolling<Row extends Record<string, unknown>>(rows: ReadonlyArray<Row>, col: string, window: number, fn?: RollingFn): ReadonlyArray<Row & Record<string, number | null>>;
+
+/**
+ * Add 8 cyclical-pair calendar features to each row.
+ *
+ * Pairs (sin²+cos² ≈ 1, so a model sees wraparound — Dec→Jan is 1 month
+ * apart, not 11):
+ *
+ * - `month_sin` / `month_cos`            (period 12)
+ * - `dow_sin` / `dow_cos`                (period 7, ISO Mon=0..Sun=6)
+ * - `hour_sin` / `hour_cos`              (period 24)
+ * - `day_of_year_sin` / `day_of_year_cos` (period 365.0, NOT 365.25)
+ *
+ * TZ handling: when `tz` is an IANA zone name like 'America/New_York',
+ * month/dow/hour/dayOfYear come from the LOCAL clock in that tz (via
+ * `Intl.DateTimeFormat`). When `tz` is omitted, UTC parts are used.
+ *
+ * Invalid `tz` throws `RangeError` BEFORE any row processing (fail-fast).
+ *
+ * @param rows    input rows (NOT mutated)
+ * @param dateCol column name containing a date — accepted as ISO string,
+ *                `Date` instance, or finite epoch-ms number
+ * @param tz      optional IANA timezone name (validated upfront)
+ * @returns       new array of rows, each carrying 8 new derived columns
+ *                (each value is a `number` from sin/cos, or `null` when
+ *                the row's date is non-parseable)
+ * @throws RangeError if `tz` is provided but not a valid IANA zone
+ */
+declare function calendarFeatures<Row extends Record<string, unknown>>(rows: ReadonlyArray<Row>, dateCol: string, tz?: string): ReadonlyArray<Row & Record<string, number | null>>;
+
+/**
+ * Pairwise difference between two numeric columns.
+ *
+ * Mirrors Python `transforms.spread(df, col_a, col_b)`. Derived column name
+ * is exactly `{colA}_minus_{colB}`. Value at index i is `rows[i][colA] -
+ * rows[i][colB]` when both are finite numbers; otherwise `null`.
+ *
+ * @param rows  input rows (NOT mutated; pure function)
+ * @param colA  minuend column
+ * @param colB  subtrahend column
+ * @returns     new array of rows, each carrying `{colA}_minus_{colB}` column
+ */
+declare function spread<Row extends Record<string, unknown>>(rows: ReadonlyArray<Row>, colA: string, colB: string): ReadonlyArray<Row & Record<string, number | null>>;
+
+/**
+ * NWS wind-chill formula (°F). Domain: `tempF ≤ 50 AND windMph > 3`.
+ *
+ * Mirrors Python `transforms.wind_chill` at transforms.py:108-116. The
+ * formula is the 2001 NWS standard:
+ *
+ *   wc = 35.74 + 0.6215 * T - 35.75 * V^0.16 + 0.4275 * T * V^0.16
+ *
+ * where T is air temperature in °F and V is wind speed in mph.
+ *
+ * **Out-of-domain (NOT null — Python parity):** when the domain bounds are
+ * not satisfied, returns `tempF` unchanged — physically "wind chill equals
+ * air temperature when wind is calm or air is warm". Null is reserved for
+ * null / undefined / non-finite inputs.
+ *
+ * Reference: https://www.weather.gov/safety/cold-wind-chill-chart
+ * Sanity: `windChill(20, 15) ≈ 6 °F` matches the NWS chart.
+ */
+declare function windChill(tempF: number | null | undefined, windMph: number | null | undefined): number | null;
+/**
+ * NWS heat index (°F) using the Rothfusz regression. Domain: `tempF ≥ 80`.
+ *
+ * Mirrors Python `transforms.heat_index` at transforms.py:119-147. Includes:
+ *
+ *  1. A simple approximation `simple = 0.5*(T + 61 + (T-68)*1.2 + RH*0.094)`
+ *     used when `(simple + T)/2 < 80` (low-effective-temperature fast path).
+ *  2. The Rothfusz 9-term polynomial:
+ *     hi = -42.379 + 2.04901523*T + 10.14333127*RH - 0.22475541*T*RH
+ *          - 0.00683783*T² - 0.05481717*RH² + 0.00122874*T²*RH
+ *          + 0.00085282*T*RH² - 0.00000199*T²*RH²
+ *  3. A dry-air adjustment when `RH < 13 && 80 ≤ T ≤ 112`:
+ *     hi -= ((13 - RH) / 4) * sqrt((17 - |T - 95|) / 17)
+ *  4. A humid-air adjustment when `RH > 85 && 80 ≤ T ≤ 87`:
+ *     hi += ((RH - 85) / 10) * ((87 - T) / 5)
+ *
+ * **Out-of-domain (NOT null — Python parity):** when `tempF < 80`, returns
+ * `tempF` unchanged. Null is reserved for null / undefined / non-finite
+ * inputs.
+ *
+ * Reference: https://www.wpc.ncep.noaa.gov/html/heatindex.shtml
+ * Sanity: `heatIndex(90, 70) ≈ 106 °F` matches the NWS Rothfusz table.
+ */
+declare function heatIndex(tempF: number | null | undefined, rhPct: number | null | undefined): number | null;
+
+/**
+ * Physics-based clipping defaults for canonical observation columns.
+ *
+ * Mirrors Python `mostlyright.preprocessing.PHYSICS_BOUNDS` (preprocessing.py:34-46).
+ * Values are `[min, max]` tuples in canonical units (°C for temp, m/s and kt
+ * for wind, hPa for pressure, percent for humidity, mm for precip).
+ *
+ * Both `dew_point_c`/`dewpoint_c` and `wind_dir_deg`/`wind_dir_degrees` are
+ * aliased to support legacy + canonical column names.
+ */
+declare const PHYSICS_BOUNDS: ReadonlyMap<string, readonly [number, number]>;
+interface ClipOutliersOptions {
+    /** Explicit `[lo, hi]` range. Overrides PHYSICS_BOUNDS and sigma fallback. */
+    bounds?: readonly [number, number];
+    /** Sigma multiplier for the fallback branch. Default 3.0. Must be > 0. */
+    std?: number;
+}
+/**
+ * Winsorize a numeric column.
+ *
+ * Mirrors Python `mostlyright.preprocessing.clip_outliers`. Returns rows with
+ * a derived `{col}_clipped` column; the source `col` is preserved unchanged.
+ *
+ * Decision tree:
+ *  - `opts.bounds` set            → clip to explicit `[lo, hi]`
+ *  - `PHYSICS_BOUNDS.has(col)`    → clip to physics defaults
+ *  - else                         → sigma fallback (`mu ± std*sigma`)
+ *
+ * **Phase 3.5 review-iter fixes:**
+ *  - Throws `RangeError` if `std ≤ 0` in the sigma fallback (matches Python
+ *    `ValueError` at preprocessing.py:84-88; silent dataset corruption
+ *    otherwise).
+ *  - Sigma=0 pass-through: when all values are identical, sample sigma is
+ *    zero and the clamp `[mu, mu]` would collapse the column. Pass values
+ *    through unchanged instead.
+ *
+ * @param rows  input rows (NOT mutated; pure function)
+ * @param col   column to clip
+ * @param opts  optional bounds / std overrides; defaults: PHYSICS_BOUNDS or sigma=3
+ * @returns     new array of rows, each carrying `{col}_clipped`
+ * @throws RangeError  if sigma fallback would use `std <= 0` or non-finite std
+ */
+declare function clipOutliers<Row extends Record<string, unknown>>(rows: ReadonlyArray<Row>, col: string, opts?: ClipOutliersOptions): ReadonlyArray<Row & Record<string, number | null>>;
+
+export { type ClipOutliersOptions, PHYSICS_BOUNDS, ROLLING_FNS, type RollingFn, calendarFeatures, clipOutliers, diff, diff2, heatIndex, lag, rolling, spread, windChill };

package/dist/transforms/index.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Shift a column by `n` rows.
+ *
+ * Mirrors Python `pd.Series.shift(periods=n)` semantics: at output index `i`,
+ * the derived column carries `rows[i-n][col]` if available, else `null`.
+ *
+ * @param rows  input rows (NOT mutated; pure function)
+ * @param col   column name to lag
+ * @param n     positive integer; rows at index `< n` get `null` in the derived column
+ * @returns     new array of rows, each carrying `{col}_lag_{n}` derived column
+ * @throws RangeError if `n < 1` or `!Number.isInteger(n)`
+ */
+declare function lag<Row extends Record<string, unknown>>(rows: ReadonlyArray<Row>, col: string, n?: number): ReadonlyArray<Row & Record<string, number | null>>;
+
+/**
+ * First (or nth-order) discrete difference of a column.
+ *
+ * At output index `i`, the derived column carries
+ * `rows[i][col] - rows[i-n][col]` if both are finite numbers, else `null`.
+ *
+ * @param rows  input rows (NOT mutated; pure function)
+ * @param col   column name to difference
+ * @param n     positive integer step (default 1)
+ * @returns     new array of rows, each carrying `{col}_diff_{n}` derived column
+ * @throws RangeError if `n < 1` or `!Number.isInteger(n)`
+ */
+declare function diff<Row extends Record<string, unknown>>(rows: ReadonlyArray<Row>, col: string, n?: number): ReadonlyArray<Row & Record<string, number | null>>;
+/**
+ * Second discrete difference of a column.
+ *
+ * Equivalent to `diff(diff(col))`. The first two output rows carry `null`
+ * (no prior diff available). Mirrors Python `df[column].diff().diff()` which
+ * returns a single Series — so the TS output carries ONLY `{col}_diff2`,
+ * NOT the intermediate `{col}_diff_1` from the first pass.
+ *
+ * @param rows  input rows (NOT mutated; pure function)
+ * @param col   column name to second-difference
+ * @returns     new array of rows, each carrying `{col}_diff2` derived column
+ */
+declare function diff2<Row extends Record<string, unknown>>(rows: ReadonlyArray<Row>, col: string): ReadonlyArray<Row & Record<string, number | null>>;
+
+/** The set of reducer names accepted by `rolling`. Ordering is API surface. */
+declare const ROLLING_FNS: readonly ["mean", "median", "min", "max", "std", "count"];
+/** Union of the six reducer-name string literals. */
+type RollingFn = (typeof ROLLING_FNS)[number];
+/**
+ * Windowed reduction over a numeric column.
+ *
+ * At each output row `i`, the window covers
+ * `rows[max(0, i-window+1) .. i]` (inclusive both ends), so the first
+ * `window-1` rows compute against a partial (still-filling) window —
+ * `min_periods=1` semantics from Python.
+ *
+ * @param rows    input rows (NOT mutated; pure function)
+ * @param col     column name to reduce over
+ * @param window  positive integer window size (≥ 1)
+ * @param fn      one of `'mean' | 'median' | 'min' | 'max' | 'std' | 'count'`
+ * @returns       new array of rows, each carrying `{col}_rolling_{window}_{fn}`
+ * @throws RangeError if `window < 1`, non-integer, or `fn` is not a `RollingFn`
+ */
+declare function rolling<Row extends Record<string, unknown>>(rows: ReadonlyArray<Row>, col: string, window: number, fn?: RollingFn): ReadonlyArray<Row & Record<string, number | null>>;
+
+/**
+ * Add 8 cyclical-pair calendar features to each row.
+ *
+ * Pairs (sin²+cos² ≈ 1, so a model sees wraparound — Dec→Jan is 1 month
+ * apart, not 11):
+ *
+ * - `month_sin` / `month_cos`            (period 12)
+ * - `dow_sin` / `dow_cos`                (period 7, ISO Mon=0..Sun=6)
+ * - `hour_sin` / `hour_cos`              (period 24)
+ * - `day_of_year_sin` / `day_of_year_cos` (period 365.0, NOT 365.25)
+ *
+ * TZ handling: when `tz` is an IANA zone name like 'America/New_York',
+ * month/dow/hour/dayOfYear come from the LOCAL clock in that tz (via
+ * `Intl.DateTimeFormat`). When `tz` is omitted, UTC parts are used.
+ *
+ * Invalid `tz` throws `RangeError` BEFORE any row processing (fail-fast).
+ *
+ * @param rows    input rows (NOT mutated)
+ * @param dateCol column name containing a date — accepted as ISO string,
+ *                `Date` instance, or finite epoch-ms number
+ * @param tz      optional IANA timezone name (validated upfront)
+ * @returns       new array of rows, each carrying 8 new derived columns
+ *                (each value is a `number` from sin/cos, or `null` when
+ *                the row's date is non-parseable)
+ * @throws RangeError if `tz` is provided but not a valid IANA zone
+ */
+declare function calendarFeatures<Row extends Record<string, unknown>>(rows: ReadonlyArray<Row>, dateCol: string, tz?: string): ReadonlyArray<Row & Record<string, number | null>>;
+
+/**
+ * Pairwise difference between two numeric columns.
+ *
+ * Mirrors Python `transforms.spread(df, col_a, col_b)`. Derived column name
+ * is exactly `{colA}_minus_{colB}`. Value at index i is `rows[i][colA] -
+ * rows[i][colB]` when both are finite numbers; otherwise `null`.
+ *
+ * @param rows  input rows (NOT mutated; pure function)
+ * @param colA  minuend column
+ * @param colB  subtrahend column
+ * @returns     new array of rows, each carrying `{colA}_minus_{colB}` column
+ */
+declare function spread<Row extends Record<string, unknown>>(rows: ReadonlyArray<Row>, colA: string, colB: string): ReadonlyArray<Row & Record<string, number | null>>;
+
+/**
+ * NWS wind-chill formula (°F). Domain: `tempF ≤ 50 AND windMph > 3`.
+ *
+ * Mirrors Python `transforms.wind_chill` at transforms.py:108-116. The
+ * formula is the 2001 NWS standard:
+ *
+ *   wc = 35.74 + 0.6215 * T - 35.75 * V^0.16 + 0.4275 * T * V^0.16
+ *
+ * where T is air temperature in °F and V is wind speed in mph.
+ *
+ * **Out-of-domain (NOT null — Python parity):** when the domain bounds are
+ * not satisfied, returns `tempF` unchanged — physically "wind chill equals
+ * air temperature when wind is calm or air is warm". Null is reserved for
+ * null / undefined / non-finite inputs.
+ *
+ * Reference: https://www.weather.gov/safety/cold-wind-chill-chart
+ * Sanity: `windChill(20, 15) ≈ 6 °F` matches the NWS chart.
+ */
+declare function windChill(tempF: number | null | undefined, windMph: number | null | undefined): number | null;
+/**
+ * NWS heat index (°F) using the Rothfusz regression. Domain: `tempF ≥ 80`.
+ *
+ * Mirrors Python `transforms.heat_index` at transforms.py:119-147. Includes:
+ *
+ *  1. A simple approximation `simple = 0.5*(T + 61 + (T-68)*1.2 + RH*0.094)`
+ *     used when `(simple + T)/2 < 80` (low-effective-temperature fast path).
+ *  2. The Rothfusz 9-term polynomial:
+ *     hi = -42.379 + 2.04901523*T + 10.14333127*RH - 0.22475541*T*RH
+ *          - 0.00683783*T² - 0.05481717*RH² + 0.00122874*T²*RH
+ *          + 0.00085282*T*RH² - 0.00000199*T²*RH²
+ *  3. A dry-air adjustment when `RH < 13 && 80 ≤ T ≤ 112`:
+ *     hi -= ((13 - RH) / 4) * sqrt((17 - |T - 95|) / 17)
+ *  4. A humid-air adjustment when `RH > 85 && 80 ≤ T ≤ 87`:
+ *     hi += ((RH - 85) / 10) * ((87 - T) / 5)
+ *
+ * **Out-of-domain (NOT null — Python parity):** when `tempF < 80`, returns
+ * `tempF` unchanged. Null is reserved for null / undefined / non-finite
+ * inputs.
+ *
+ * Reference: https://www.wpc.ncep.noaa.gov/html/heatindex.shtml
+ * Sanity: `heatIndex(90, 70) ≈ 106 °F` matches the NWS Rothfusz table.
+ */
+declare function heatIndex(tempF: number | null | undefined, rhPct: number | null | undefined): number | null;
+
+/**
+ * Physics-based clipping defaults for canonical observation columns.
+ *
+ * Mirrors Python `mostlyright.preprocessing.PHYSICS_BOUNDS` (preprocessing.py:34-46).
+ * Values are `[min, max]` tuples in canonical units (°C for temp, m/s and kt
+ * for wind, hPa for pressure, percent for humidity, mm for precip).
+ *
+ * Both `dew_point_c`/`dewpoint_c` and `wind_dir_deg`/`wind_dir_degrees` are
+ * aliased to support legacy + canonical column names.
+ */
+declare const PHYSICS_BOUNDS: ReadonlyMap<string, readonly [number, number]>;
+interface ClipOutliersOptions {
+    /** Explicit `[lo, hi]` range. Overrides PHYSICS_BOUNDS and sigma fallback. */
+    bounds?: readonly [number, number];
+    /** Sigma multiplier for the fallback branch. Default 3.0. Must be > 0. */
+    std?: number;
+}
+/**
+ * Winsorize a numeric column.
+ *
+ * Mirrors Python `mostlyright.preprocessing.clip_outliers`. Returns rows with
+ * a derived `{col}_clipped` column; the source `col` is preserved unchanged.
+ *
+ * Decision tree:
+ *  - `opts.bounds` set            → clip to explicit `[lo, hi]`
+ *  - `PHYSICS_BOUNDS.has(col)`    → clip to physics defaults
+ *  - else                         → sigma fallback (`mu ± std*sigma`)
+ *
+ * **Phase 3.5 review-iter fixes:**
+ *  - Throws `RangeError` if `std ≤ 0` in the sigma fallback (matches Python
+ *    `ValueError` at preprocessing.py:84-88; silent dataset corruption
+ *    otherwise).
+ *  - Sigma=0 pass-through: when all values are identical, sample sigma is
+ *    zero and the clamp `[mu, mu]` would collapse the column. Pass values
+ *    through unchanged instead.
+ *
+ * @param rows  input rows (NOT mutated; pure function)
+ * @param col   column to clip
+ * @param opts  optional bounds / std overrides; defaults: PHYSICS_BOUNDS or sigma=3
+ * @returns     new array of rows, each carrying `{col}_clipped`
+ * @throws RangeError  if sigma fallback would use `std <= 0` or non-finite std
+ */
+declare function clipOutliers<Row extends Record<string, unknown>>(rows: ReadonlyArray<Row>, col: string, opts?: ClipOutliersOptions): ReadonlyArray<Row & Record<string, number | null>>;
+
+export { type ClipOutliersOptions, PHYSICS_BOUNDS, ROLLING_FNS, type RollingFn, calendarFeatures, clipOutliers, diff, diff2, heatIndex, lag, rolling, spread, windChill };