diff --git a/playground/index.html b/playground/index.html index 48bfbcb9..10ce3c3b 100644 --- a/playground/index.html +++ b/playground/index.html @@ -254,6 +254,11 @@

Element-wise transformations. clip(), seriesAbs(), seriesRound() for Series and DataFrame with min/max bounds, decimal precision, and axis support.

βœ… Complete
+
+

πŸ” missing-value ops

+

Detect and fill missing values. isna(), notna(), isnull(), notnull() for scalars/Series/DataFrame. ffillSeries(), bfillSeries(), dataFrameFfill(), dataFrameBfill() with optional limit and axis support.

+
βœ… Complete
+

πŸ”’ value_counts

Count unique values. valueCounts() for Series and dataFrameValueCounts() for DataFrame with normalize, sort, ascending, and dropna options.

@@ -264,6 +269,91 @@

βœ… Complete

+
+

πŸ“Š pct_change

+

Fractional change between elements. pctChangeSeries() and pctChangeDataFrame() with periods, fillMethod (pad/bfill), limit, and axis options.

+
βœ… Complete
+
+
+

πŸ“₯ insertColumn / popColumn

+

Insert and remove DataFrame columns at precise positions. insertColumn(df, loc, col, values) inserts at integer position, popColumn(df, col) returns { series, df }. Also includes reorderColumns and moveColumn. Mirrors pandas.DataFrame.insert() and .pop().

+
βœ… Complete
+
+
+

βœ‚οΈ cut / qcut

+

Bin continuous numeric data into discrete intervals. cut() uses fixed-width or explicit bin edges; qcut() uses quantile-based bins of equal population. Both return codes, labels, and bin edges. Mirrors pandas.cut and pandas.qcut.

+
βœ… Complete
+
+
+

πŸ“Š Rolling Extended Stats

+

Higher-order rolling window statistics: rollingSem (standard error of mean), rollingSkew (Fisher-Pearson skewness), rollingKurt (excess kurtosis), and rollingQuantile (arbitrary percentile with 5 interpolation methods). Mirrors pandas.Series.rolling().sem/skew/kurt/quantile().

+
βœ… Complete
+
+
+

πŸ”§ Rolling Apply & Multi-Agg

+

Standalone custom rolling-window functions: rollingApply (custom fn per window), rollingAgg (multiple named aggregations β†’ DataFrame), dataFrameRollingApply, dataFrameRollingAgg. Supports minPeriods, center, and raw mode. Mirrors pandas.Rolling.apply() and Rolling.agg().

+
βœ… Complete
+
+
+

🎭 where / mask

+

Element-wise conditional selection: seriesWhere / seriesMask and dataFrameWhere / dataFrameMask. Accepts boolean arrays, label-aligned boolean Series/DataFrame, or callables. Mirrors pandas.Series.where, pandas.DataFrame.where, and their .mask() inverses.

+
βœ… Complete
+
+
+

πŸ” isna / notna

+

Module-level missing-value detection: isna, notna, isnull, notnull work on scalars, arrays, Series, and DataFrames. Plus standalone fillna, dropna, countna, and countValid. Mirrors pandas.isna, pandas.notna, pandas.isnull, pandas.notnull.

+
βœ… Complete
+
+
+

🏷️ attrs β€” User Metadata

+

Attach arbitrary key→value metadata to any Series or DataFrame via a WeakMap registry. Provides getAttrs, setAttrs, updateAttrs, copyAttrs, withAttrs, mergeAttrs, clearAttrs, getAttr, setAttr, deleteAttr, attrsCount, attrsKeys. Mirrors pandas.DataFrame.attrs / pandas.Series.attrs.

+
βœ… Complete
+
+
+

πŸ”€ string_ops β€” Standalone String Ops

+

Module-level string utilities: strNormalize (Unicode NFC/NFD/NFKC/NFKD), strGetDummies (one-hot DataFrame), strExtractAll (all regex matches), strRemovePrefix, strRemoveSuffix, strTranslate (char-level substitution), strCharWidth (CJK-aware display width), strByteLength. Works on Series, arrays, or scalars.

+
βœ… Complete
+
+
+

πŸ”€ string_ops_extended β€” Extended String Ops

+

Advanced string utilities: strSplitExpand (split β†’ DataFrame columns), strExtractGroups (regex capture groups β†’ DataFrame), strPartition / strRPartition (split into before/sep/after), strMultiReplace (batch replacements), strIndent / strDedent (line-level indentation). Works on Series, arrays, or scalars.

+
βœ… Complete
+
+
+

πŸ”— pipe_apply β€” Pipeline & Apply Utilities

+

Standalone equivalents of pandas' pipe() / apply() / applymap(): pipe (variadic type-safe pipeline), seriesApply (element-wise with label/pos context), seriesTransform, dataFrameApply (axis 0/1), dataFrameApplyMap (cell-wise), dataFrameTransform (column-wise), dataFrameTransformRows (row-wise).

+
βœ… Complete
+
+
+

πŸ”’ numeric_extended β€” Numeric Utilities

+

numpy/scipy-style numeric utilities: digitize (bin values), histogram (frequency counts with density option), linspace / arange (number sequences), percentileOfScore (percentile rank of a score), zscore (z-score standardisation), minMaxNormalize (scale to [0,1] or custom range), coefficientOfVariation (std/mean). Series-aware variants included.

+
βœ… Complete
+
+ +
+
+

🏷️ categorical_ops β€” Categorical Utilities

+

Standalone categorical helpers: catFromCodes (from integer codes), set operations (catUnionCategories, catIntersectCategories, catDiffCategories, catEqualCategories), catSortByFreq, catToOrdinal, catFreqTable, catCrossTab, catRecode.

+
βœ… Complete
+
+
+
+
+

πŸ”’ format_ops β€” Number Formatting

+

Number-formatting helpers for Series and DataFrame. Scalar formatters: formatFloat, formatPercent, formatScientific, formatEngineering, formatThousands, formatCurrency, formatCompact. Formatter factories: makeFloatFormatter, makePercentFormatter, makeCurrencyFormatter. Apply to collections: applySeriesFormatter, applyDataFrameFormatter. Render to string: seriesToString, dataFrameToString.

+
βœ… Complete
+
+
+ + +
+

Performance

+
+
+

⚑ Benchmarks

+

Side-by-side performance comparison of tsb (TypeScript/Bun) vs pandas (Python). Timing metrics for each function.

+
πŸ—οΈ In Progress
+
diff --git a/playground/na_ops.html b/playground/na_ops.html new file mode 100644 index 00000000..c321438f --- /dev/null +++ b/playground/na_ops.html @@ -0,0 +1,480 @@ + + + + + + tsb β€” missing-value operations (isna, ffill, bfill) + + + +
+ +
Loading tsb runtime…
+
+ + ← Back to playground index + +

Missing-value operations

+

+ isna / notna β€” detect missing values in scalars, + Series, and DataFrames.
+ ffill / bfill β€” propagate the last (or next) valid + value to fill gaps.
+ Mirrors pd.isna(), Series.ffill(), and + DataFrame.bfill() from pandas. +

+ + +
+

1 Β· isna / notna on scalars

+

+ Returns true / false for individual values. + null, undefined, and NaN are all + considered "missing". +

+
+
+
+ + +
+
+ + +
+
+ + +
Click β–Ά Run to execute
+
Ctrl+Enter to run Β· Tab to indent
+
+
+ + +
+

2 Β· isna on a Series

+

+ When passed a Series, isna returns a boolean Series of the + same length β€” true where values are missing. +

+
+
+
+ + +
+
+ + +
+
+ + +
Click β–Ά Run to execute
+
Ctrl+Enter to run Β· Tab to indent
+
+
+ + +
+

3 Β· isna on a DataFrame

+

+ Returns a DataFrame of booleans with the same shape β€” one column per + original column, true where missing. +

+
+
+
+ + +
+
+ + +
+
+ + +
Click β–Ά Run to execute
+
Ctrl+Enter to run Β· Tab to indent
+
+
+ + +
+

4 Β· Forward-fill (ffillSeries)

+

+ Propagates the last valid value forward to fill gaps. Leading + nulls that have no preceding value remain null. + Use the optional limit to cap consecutive fills. +

+
+
+
+ + +
+
+ + +
+
+ + +
Click β–Ά Run to execute
+
Ctrl+Enter to run Β· Tab to indent
+
+
+ + +
+

5 Β· Backward-fill (bfillSeries)

+

+ Propagates the next valid value backward to fill gaps. Trailing + nulls that have no following value remain null. +

+
+
+
+ + +
+
+ + +
+
+ + +
Click β–Ά Run to execute
+
Ctrl+Enter to run Β· Tab to indent
+
+
+ + +
+

6 Β· DataFrame forward-fill & backward-fill

+

+ dataFrameFfill and dataFrameBfill apply fill + column-wise by default (axis=0). Pass axis: 1 to fill + row-wise across columns. +

+
+
+
+ + +
+
+ + +
+
+ + +
Click β–Ά Run to execute
+
Ctrl+Enter to run Β· Tab to indent
+
+
+ + +
+

API Reference

+ 
// Module-level missing-value detection
+isna(value: Scalar): boolean
+isna(value: Series): Series<boolean>
+isna(value: DataFrame): DataFrame
+
+notna(value: Scalar): boolean
+notna(value: Series): Series<boolean>
+notna(value: DataFrame): DataFrame
+
+// Aliases
+isnull(...)  // same as isna
+notnull(...) // same as notna
+
+// Series forward / backward fill
+ffillSeries(series, options?: { limit?: number | null }): Series
+bfillSeries(series, options?: { limit?: number | null }): Series
+
+// DataFrame forward / backward fill
+dataFrameFfill(df, options?: {
+  limit?: number | null,   // max consecutive fills (default: no limit)
+  axis?: 0 | 1 | "index" | "columns",  // default 0 (column-wise)
+}): DataFrame
+
+dataFrameBfill(df, options?: {
+  limit?: number | null,
+  axis?: 0 | 1 | "index" | "columns",
+}): DataFrame
+
+ + + + + diff --git a/playground/pct_change.html b/playground/pct_change.html new file mode 100644 index 00000000..ec1b4e3b --- /dev/null +++ b/playground/pct_change.html @@ -0,0 +1,452 @@ + + + + + + tsb β€” pct_change + + + +
+ +
Initializing playground…
+
+ ← Back to roadmap +

πŸ“Š pct_change β€” Interactive Playground

+

Compute the fractional change between each element and a prior element. + Mirrors pandas.Series.pct_change() / + pandas.DataFrame.pct_change().
+ Edit any code block below and press β–Ά Run + (or Ctrl+Enter) to execute it live in your browser. +

+ + +
+

1 Β· Basic pct_change on a Series

+

pctChangeSeries(series) returns the fractional (not percentage) change + from each previous element. The first element is always null.

+
+
+ TypeScript +
+ + +
+
+ + +
Click β–Ά Run to execute
+
Ctrl+Enter to run Β· Tab to indent
+
+
+ + +
+

2 Β· Multi-period change

+

The periods option controls the lag. Use periods: 2 to + compare each value to the one two steps earlier β€” useful for month-over-month + comparisons in quarterly data.

+
+
+ TypeScript +
+ + +
+
+ + +
Click β–Ά Run to execute
+
Ctrl+Enter to run Β· Tab to indent
+
+
+ + +
+

3 Β· Handling missing values

+

By default, pctChangeSeries forward-fills (fillMethod: "pad") + NaN/null values before computing the ratio β€” so gaps don't break the chain. + Set fillMethod: null to propagate NaN instead.

+
+
+ TypeScript +
+ + +
+
+ + +
Click β–Ά Run to execute
+
Ctrl+Enter to run Β· Tab to indent
+
+
+ + +
+

4 Β· Limit consecutive fills

+

The limit option caps how many consecutive NaN values get forward-filled. + Useful when you want to tolerate short gaps but not bridge large ones.

+
+
+ TypeScript +
+ + +
+
+ + +
Click β–Ά Run to execute
+
Ctrl+Enter to run Β· Tab to indent
+
+
+ + +
+

5 Β· DataFrame column-wise pct_change

+

pctChangeDataFrame(df) applies pctChangeSeries to every + column independently. Ideal for comparing multiple assets or metrics simultaneously.

+
+
+ TypeScript +
+ + +
+
+ + +
Click β–Ά Run to execute
+
Ctrl+Enter to run Β· Tab to indent
+
+
+ + +
+

6 Β· Negative periods (look-forward change)

+

A negative periods value computes the forward change: how much will + this element change by the time we reach |periods| steps ahead. + Useful for computing returns on a "hold for N periods" strategy.

+
+
+ TypeScript +
+ + +
+
+ + +
Click β–Ά Run to execute
+
Ctrl+Enter to run Β· Tab to indent
+
+
+ + +
+

API Reference

+

All functions return a new Series/DataFrame of the same shape β€” inputs are never mutated.

+ 
// Series
+pctChangeSeries(series, {
+  periods?: number,           // default 1 (positive = look back, negative = look forward)
+  fillMethod?: "pad" | "bfill" | null,  // default "pad"
+  limit?: number | null,      // max consecutive fills; default unlimited
+}): Series
+
+// DataFrame
+pctChangeDataFrame(df, {
+  periods?: number,
+  fillMethod?: "pad" | "bfill" | null,
+  limit?: number | null,
+  axis?: 0 | 1 | "index" | "columns",  // default 0 (column-wise)
+}): DataFrame
+
+ + + + + diff --git a/src/index.ts b/src/index.ts index 1dd0aa57..22723aa2 100644 --- a/src/index.ts +++ b/src/index.ts @@ -3,6 +3,7 @@ * * @packageDocumentation */ +// merged: 2026-04-09T19:37Z (re-merge main into PR branch, barrel-export conflicts resolved by keeping PR superset) // Core exports will be added here as features are implemented. // Each module is imported and re-exported from its feature file in src/. @@ -45,12 +46,16 @@ export { DatetimeAccessor } from "./core/index.ts"; export type { DatetimeSeriesLike } from "./core/index.ts"; export { DataFrameGroupBy, SeriesGroupBy } from "./groupby/index.ts"; export type { AggFn, AggName, AggSpec } from "./groupby/index.ts"; +export { NamedAgg, namedAgg, isNamedAggSpec } from "./groupby/index.ts"; +export type { NamedAggSpec } from "./groupby/index.ts"; export { describe, quantile } from "./stats/index.ts"; export type { DescribeOptions } from "./stats/index.ts"; export { readCsv, toCsv } from "./io/index.ts"; export type { ReadCsvOptions, ToCsvOptions } from "./io/index.ts"; export { readJson, toJson } from "./io/index.ts"; export type { ReadJsonOptions, ToJsonOptions, JsonOrient } from "./io/index.ts"; +export { jsonNormalize } from "./io/index.ts"; +export type { JsonNormalizeOptions, JsonPath } from "./io/index.ts"; export { pearsonCorr, dataFrameCorr, dataFrameCov } from "./stats/index.ts"; export type { CorrMethod, CorrOptions, CovOptions } from "./stats/index.ts"; export { Rolling } from "./window/index.ts"; @@ -61,6 +66,13 @@ export type { ExpandingOptions, ExpandingSeriesLike } from "./window/index.ts"; export { DataFrameExpanding } from "./core/index.ts"; export { EWM } from "./window/index.ts"; export type { EwmOptions, EwmSeriesLike } from "./window/index.ts"; +export { + rollingApply, + rollingAgg, + dataFrameRollingApply, + dataFrameRollingAgg, +} from "./window/index.ts"; +export type { RollingApplyOptions, RollingAggOptions, AggFunctions } from "./window/index.ts"; export { DataFrameEwm } from "./core/index.ts"; export { CategoricalAccessor } from "./core/index.ts"; export type { CatSeriesLike } from "./core/index.ts"; @@ -74,6 +86,10 @@ export type { } from "./reshape/index.ts"; export { stack, unstack, STACK_DEFAULT_SEP } from "./reshape/index.ts"; export type { StackOptions, UnstackOptions } from "./reshape/index.ts"; +export { wideToLong } from "./reshape/index.ts"; +export type { WideToLongOptions } from "./reshape/index.ts"; +export { pivotTableFull } from "./reshape/index.ts"; +export type { PivotTableFullOptions } from "./reshape/index.ts"; export { MultiIndex } from "./core/index.ts"; export type { MultiIndexOptions } from "./core/index.ts"; export { rankSeries, rankDataFrame } from "./stats/index.ts"; @@ -107,3 +123,418 @@ export { export type { ClipOptions, RoundOptions, DataFrameElemOptions } from "./stats/index.ts"; export { valueCounts, dataFrameValueCounts } from "./stats/index.ts"; export type { ValueCountsOptions, DataFrameValueCountsOptions } from "./stats/index.ts"; +export { whereSeries, maskSeries, whereDataFrame, maskDataFrame } from "./stats/index.ts"; +export type { + WherePredicate, + SeriesCond, + DataFrameCond, + WhereMaskOptions, +} from "./stats/index.ts"; +export { + seriesEq, + seriesNe, + seriesLt, + seriesGt, + seriesLe, + seriesGe, + dataFrameEq, + dataFrameNe, + dataFrameLt, + dataFrameGt, + dataFrameLe, + dataFrameGe, +} from "./stats/index.ts"; +export type { CompareOp, SeriesOther, DataFrameOther } from "./stats/index.ts"; +export { shiftSeries, diffSeries, dataFrameShift, dataFrameDiff } from "./stats/index.ts"; +export type { ShiftDiffDataFrameOptions } from "./stats/index.ts"; +export { interpolateSeries, dataFrameInterpolate } from "./stats/index.ts"; +export type { + InterpolateMethod, + LimitDirection, + InterpolateOptions, + DataFrameInterpolateOptions, +} from "./stats/index.ts"; +export { fillnaSeries, fillnaDataFrame } from "./stats/index.ts"; +export type { + FillnaMethod, + FillnaSeriesOptions, + ColumnFillMap, + FillnaDataFrameOptions, +} from "./stats/index.ts"; +export { Interval, IntervalIndex } from "./core/index.ts"; +export type { IntervalClosed, IntervalIndexOptions } from "./core/index.ts"; +export { cut, qcut, cutIntervalIndex, qcutIntervalIndex } from "./stats/index.ts"; +export type { CutOptions, QCutOptions } from "./stats/index.ts"; +export { sampleSeries, sampleDataFrame } from "./stats/index.ts"; +export type { SampleSeriesOptions, SampleDataFrameOptions } from "./stats/index.ts"; +export { applySeries, applymap, dataFrameApply } from "./stats/index.ts"; +export type { DataFrameApplyOptions } from "./stats/index.ts"; +export { CategoricalIndex } from "./core/index.ts"; +export type { CategoricalIndexOptions } from "./core/index.ts"; +export { + pipeSeries, + dataFramePipe, + pipeTo, + dataFramePipeTo, + pipeChain, + dataFramePipeChain, +} from "./stats/index.ts"; + +export { Period, PeriodIndex } from "./core/index.ts"; +export type { PeriodFreq, PeriodIndexOptions } from "./core/index.ts"; +export { Timedelta, TimedeltaIndex } from "./core/index.ts"; +export type { TimedeltaComponents, TimedeltaIndexOptions } from "./core/index.ts"; +export { + Day, + Hour, + Minute, + Second, + Milli, + Week, + MonthEnd, + MonthBegin, + YearEnd, + YearBegin, + BusinessDay, +} from "./core/index.ts"; +export type { DateOffset, WeekOptions } from "./core/index.ts"; +export { DatetimeIndex, date_range, bdate_range, resolveFreq } from "./core/index.ts"; +export type { DateRangeFreq, DateRangeOptions, DatetimeIndexOptions } from "./core/index.ts"; +export { TZDatetimeIndex, tz_localize, tz_convert } from "./core/index.ts"; +export { + seriesFloor, + dataFrameFloor, + seriesCeil, + dataFrameCeil, + seriesTrunc, + dataFrameTrunc, + seriesSqrt, + dataFrameSqrt, + seriesExp, + dataFrameExp, + seriesLog, + dataFrameLog, + seriesLog2, + dataFrameLog2, + seriesLog10, + dataFrameLog10, + seriesSign, + dataFrameSign, +} from "./stats/index.ts"; +export { + seriesPow, + dataFramePow, + seriesMod, + dataFrameMod, + seriesFloorDiv, + dataFrameFloorDiv, +} from "./stats/index.ts"; +export { + seriesAdd, + seriesRadd, + seriesSub, + seriesRsub, + seriesMul, + seriesRmul, + seriesDiv, + seriesRdiv, + dataFrameAdd, + dataFrameRadd, + dataFrameSub, + dataFrameRsub, + dataFrameMul, + dataFrameRmul, + dataFrameDiv, + dataFrameRdiv, +} from "./stats/index.ts"; +export { getDummies, dataFrameGetDummies } from "./stats/index.ts"; +export type { GetDummiesOptions, DataFrameGetDummiesOptions } from "./stats/index.ts"; +export { factorize, seriesFactorize } from "./stats/index.ts"; +export type { FactorizeOptions, FactorizeResult } from "./stats/index.ts"; +export { crosstab, seriesCrosstab } from "./stats/index.ts"; +export type { AggFunc, Normalize, CrosstabOptions } from "./stats/index.ts"; +export { toNumeric, toNumericArray, toNumericScalar, toNumericSeries } from "./stats/index.ts"; +export type { ToNumericDowncast, ToNumericErrors, ToNumericOptions } from "./stats/index.ts"; +export { seriesMemoryUsage, dataFrameMemoryUsage } from "./stats/index.ts"; +export type { MemoryUsageOptions } from "./stats/index.ts"; +export { selectDtypes } from "./stats/index.ts"; +export type { DtypeSelector, SelectDtypesOptions } from "./stats/index.ts"; +export { clipSeriesWithBounds, clipDataFrameWithBounds } from "./stats/index.ts"; +export type { + BoundArg, + SeriesClipBoundsOptions, + DataFrameClipBoundsOptions, +} from "./stats/index.ts"; +export { Timestamp } from "./core/index.ts"; +export type { TimestampOptions, TimestampComponents, TimestampUnit } from "./core/index.ts"; +export { dataFrameAssign } from "./core/index.ts"; +export type { AssignColSpec, AssignSpec } from "./core/index.ts"; +export { inferDtype } from "./stats/index.ts"; +export type { InferredDtype, InferDtypeOptions } from "./stats/index.ts"; +export { isna, notna, isnull, notnull } from "./stats/index.ts"; +export { dropna, dropnaSeries, dropnaDataFrame } from "./stats/index.ts"; +export type { DropnaHow, DropnaDataFrameOptions } from "./stats/index.ts"; +export { combineFirstSeries, combineFirstDataFrame } from "./stats/index.ts"; +export { natCompare, natSorted, natSortKey, natArgSort } from "./core/index.ts"; +export type { NatSortOptions, NatSortedOptions } from "./core/index.ts"; +export { searchsorted, searchsortedMany, argsortScalars } from "./core/index.ts"; +export type { SearchSortedSide, SearchSortedOptions } from "./core/index.ts"; +export { valueCountsBinned } from "./stats/index.ts"; +export type { ValueCountsBinnedOptions } from "./stats/index.ts"; + +export { + duplicatedSeries, + duplicatedDataFrame, + dropDuplicatesSeries, + dropDuplicatesDataFrame, +} from "./stats/index.ts"; +export type { + KeepPolicy, + DuplicatedDataFrameOptions, + DuplicatedSeriesOptions, +} from "./stats/index.ts"; +export { reindexSeries, reindexDataFrame } from "./core/index.ts"; +export type { ReindexMethod, ReindexSeriesOptions, ReindexDataFrameOptions } from "./core/index.ts"; + +export { alignSeries, alignDataFrame } from "./core/index.ts"; +export type { AlignSeriesOptions, AlignDataFrameOptions } from "./core/index.ts"; + +export { explodeSeries, explodeDataFrame } from "./stats/index.ts"; +export type { ExplodeOptions, ExplodeDataFrameOptions } from "./stats/index.ts"; + +export { isin, dataFrameIsin } from "./stats/index.ts"; +export type { IsinValues, IsinDict, DataFrameIsinValues } from "./stats/index.ts"; + +export { + insertColumn, + popColumn, + reorderColumns, + moveColumn, + dataFrameFromPairs, +} from "./core/index.ts"; +export type { PopResult } from "./core/index.ts"; +export { toDictOriented, fromDictOriented } from "./core/index.ts"; +export type { + ToDictOrient, + FromDictOrient, + DictSplit, + DictTight, + SplitInput, +} from "./core/index.ts"; +export { rollingSem, rollingSkew, rollingKurt, rollingQuantile } from "./stats/index.ts"; +export type { WindowExtOptions, RollingQuantileOptions } from "./stats/index.ts"; +export { fillna, countna, countValid } from "./stats/index.ts"; +export type { IsnaInput, FillnaOptions, DropnaOptions } from "./stats/index.ts"; +export { + getAttrs, + setAttrs, + updateAttrs, + copyAttrs, + withAttrs, + clearAttrs, + hasAttrs, + getAttr, + setAttr, + deleteAttr, + attrsCount, + attrsKeys, + mergeAttrs, +} from "./core/index.ts"; +export type { Attrs } from "./core/index.ts"; +export { + pipe, + seriesApply, + seriesTransform, + dataFrameApplyMap, + dataFrameTransform, + dataFrameTransformRows, +} from "./core/index.ts"; +export { + isScalar, + isListLike, + isArrayLike, + isDictLike, + isIterator, + isNumber, + isBool, + isStringValue, + isFloat, + isInteger, + isBigInt, + isRegExp, + isReCompilable, + isMissing, + isHashable, + isDate, + isNumericDtype, + isIntegerDtype, + isSignedIntegerDtype, + isUnsignedIntegerDtype, + isFloatDtype, + isBoolDtype, + isStringDtype, + isDatetimeDtype, + isTimedeltaDtype, + isCategoricalDtype, + isObjectDtype, + isComplexDtype, + isExtensionArrayDtype, + isPeriodDtype, + isIntervalDtype, +} from "./core/index.ts"; +export { + strNormalize, + strGetDummies, + strExtractAll, + strRemovePrefix, + strRemoveSuffix, + strTranslate, + strCharWidth, + strByteLength, + strSplitExpand, + strExtractGroups, + strPartition, + strRPartition, + strMultiReplace, + strIndent, + strDedent, +} from "./stats/index.ts"; +export type { + NormalizeForm, + StrInput, + ExtractAllOptions, + SplitExpandOptions, + ExtractGroupsOptions, + PartitionResult, + ReplacePair, + IndentOptions, +} from "./stats/index.ts"; +export { + digitize, + histogram, + linspace, + arange, + percentileOfScore, + zscore, + minMaxNormalize, + coefficientOfVariation, + seriesDigitize, +} from "./stats/index.ts"; +export type { + HistogramOptions, + HistogramResult, + ZscoreOptions, + MinMaxOptions, + CvOptions, +} from "./stats/index.ts"; +export { + catFromCodes, + catUnionCategories, + catIntersectCategories, + catDiffCategories, + catEqualCategories, + catSortByFreq, + catToOrdinal, + catFreqTable, + catCrossTab, + catRecode, +} from "./stats/index.ts"; +export type { + CatFromCodesOptions, + CatSortByFreqOptions, + CatCrossTabOptions, +} from "./stats/index.ts"; +export { + formatFloat, + formatPercent, + formatScientific, + formatEngineering, + formatThousands, + formatCurrency, + formatCompact, + makeFloatFormatter, + makePercentFormatter, + makeCurrencyFormatter, + applySeriesFormatter, + applyDataFrameFormatter, + seriesToString, + dataFrameToString, +} from "./stats/index.ts"; +export type { + Formatter, + SeriesToStringOptions, + DataFrameToStringOptions, +} from "./stats/index.ts"; + +// PR #120 unique modules β€” re-exported from sub-barrels +export { astypeSeries, astype, castScalar } from "./core/index.ts"; +export type { AstypeOptions, DataFrameAstypeOptions } from "./core/index.ts"; +// readExcel / xlsxSheetNames use node:zlib β€” import from "tsb/io/read_excel" directly +export { clipAdvancedSeries, clipAdvancedDataFrame } from "./stats/index.ts"; +export type { + SeriesBound, + DataFrameBound, + ClipAdvancedSeriesOptions, + ClipAdvancedDataFrameOptions, +} from "./stats/index.ts"; +export { idxminSeries, idxmaxSeries, idxminDataFrame, idxmaxDataFrame } from "./stats/index.ts"; +export type { IdxOptions, IdxDataFrameOptions } from "./stats/index.ts"; +export { modeSeries, modeDataFrame } from "./stats/index.ts"; +export type { ModeSeriesOptions, ModeDataFrameOptions } from "./stats/index.ts"; +export { + nancount, + nansum, + nanmean, + nanmedian, + nanvar, + nanstd, + nanmin, + nanmax, + nanprod, +} from "./stats/index.ts"; +export type { NanInput, NanAggOptions } from "./stats/index.ts"; +export { + nuniqueSeries, + nuniqueDataFrame, + anySeries, + allSeries, + anyDataFrame, + allDataFrame, +} from "./stats/index.ts"; +export type { + NuniqueSeriesOptions, + NuniqueDataFrameOptions, + AnyAllSeriesOptions, + AnyAllDataFrameOptions, +} from "./stats/index.ts"; +export { pctChangeSeries, pctChangeDataFrame } from "./stats/index.ts"; +export type { + PctChangeFillMethod, + PctChangeOptions, + DataFramePctChangeOptions, +} from "./stats/index.ts"; +export { quantileSeries, quantileDataFrame } from "./stats/index.ts"; +export type { + QuantileInterpolation, + QuantileSeriesOptions, + QuantileDataFrameOptions, +} from "./stats/index.ts"; +export { replaceSeries, replaceDataFrame } from "./stats/index.ts"; +export type { + ReplaceMapping, + ReplaceSpec, + ReplaceOptions, + DataFrameReplaceOptions, +} from "./stats/index.ts"; +export { varSeries, semSeries, varDataFrame, semDataFrame } from "./stats/index.ts"; +export type { VarSemSeriesOptions, VarSemDataFrameOptions } from "./stats/index.ts"; +export { skewSeries, kurtSeries, skewDataFrame, kurtDataFrame } from "./stats/index.ts"; +export type { + SkewKurtSeriesOptions, + SkewKurtDataFrameOptions, +} from "./stats/index.ts"; +export { toDatetime } from "./stats/index.ts"; +export type { DatetimeUnit, DatetimeErrors, ToDatetimeOptions } from "./stats/index.ts"; + +export { ffillSeries, bfillSeries, dataFrameFfill, dataFrameBfill } from "./stats/index.ts"; +export type { FillDirectionOptions, DataFrameFillOptions } from "./stats/index.ts"; diff --git a/src/stats/index.ts b/src/stats/index.ts index b1de48eb..3e580371 100644 --- a/src/stats/index.ts +++ b/src/stats/index.ts @@ -39,3 +39,327 @@ export { nsmallestDataFrame, } from "./nlargest.ts"; export type { NKeep, NTopOptions, NTopDataFrameOptions } from "./nlargest.ts"; +export { whereSeries, maskSeries, whereDataFrame, maskDataFrame } from "./where_mask.ts"; +export type { + WherePredicate, + SeriesCond, + DataFrameCond, + WhereMaskOptions, +} from "./where_mask.ts"; +export { + seriesEq, + seriesNe, + seriesLt, + seriesGt, + seriesLe, + seriesGe, + dataFrameEq, + dataFrameNe, + dataFrameLt, + dataFrameGt, + dataFrameLe, + dataFrameGe, +} from "./compare.ts"; +export type { CompareOp, SeriesOther, DataFrameOther } from "./compare.ts"; +export { shiftSeries, diffSeries, dataFrameShift, dataFrameDiff } from "./shift_diff.ts"; +export type { ShiftDiffDataFrameOptions } from "./shift_diff.ts"; +export { interpolateSeries, dataFrameInterpolate } from "./interpolate.ts"; +export type { + InterpolateMethod, + LimitDirection, + InterpolateOptions, + DataFrameInterpolateOptions, +} from "./interpolate.ts"; +export { fillnaSeries, fillnaDataFrame } from "./fillna.ts"; +export type { + FillnaMethod, + FillnaSeriesOptions, + ColumnFillMap, + FillnaDataFrameOptions, +} from "./fillna.ts"; +export { cut, qcut, cutIntervalIndex, qcutIntervalIndex } from "./cut.ts"; +export type { CutOptions, QCutOptions } from "./cut.ts"; +export { sampleSeries, sampleDataFrame } from "./sample.ts"; +export type { SampleSeriesOptions, SampleDataFrameOptions } from "./sample.ts"; +export { applySeries, applymap, dataFrameApply } from "./apply.ts"; +export type { DataFrameApplyOptions } from "./apply.ts"; + +export { + pipeSeries, + dataFramePipe, + pipeTo, + dataFramePipeTo, + pipeChain, + dataFramePipeChain, +} from "./pipe.ts"; +export { + seriesFloor, + dataFrameFloor, + seriesCeil, + dataFrameCeil, + seriesTrunc, + dataFrameTrunc, + seriesSqrt, + dataFrameSqrt, + seriesExp, + dataFrameExp, + seriesLog, + dataFrameLog, + seriesLog2, + dataFrameLog2, + seriesLog10, + dataFrameLog10, + seriesSign, + dataFrameSign, +} from "./numeric_ops.ts"; + +export { + seriesPow, + dataFramePow, + seriesMod, + dataFrameMod, + seriesFloorDiv, + dataFrameFloorDiv, +} from "./pow_mod.ts"; + +export { + seriesAdd, + seriesRadd, + seriesSub, + seriesRsub, + seriesMul, + seriesRmul, + seriesDiv, + seriesRdiv, + dataFrameAdd, + dataFrameRadd, + dataFrameSub, + dataFrameRsub, + dataFrameMul, + dataFrameRmul, + dataFrameDiv, + dataFrameRdiv, +} from "./add_sub_mul_div.ts"; + +export { getDummies, dataFrameGetDummies } from "./get_dummies.ts"; +export type { GetDummiesOptions, DataFrameGetDummiesOptions } from "./get_dummies.ts"; + +export { factorize, seriesFactorize } from "./factorize.ts"; +export type { FactorizeOptions, FactorizeResult } from "./factorize.ts"; + +export { crosstab, seriesCrosstab } from "./crosstab.ts"; +export type { AggFunc, Normalize, CrosstabOptions } from "./crosstab.ts"; + +export { toNumeric, toNumericArray, toNumericScalar, toNumericSeries } from "./to_numeric.ts"; +export type { ToNumericDowncast, ToNumericErrors, ToNumericOptions } from "./to_numeric.ts"; + +export { seriesMemoryUsage, dataFrameMemoryUsage } from "./memory_usage.ts"; +export type { MemoryUsageOptions } from "./memory_usage.ts"; + +export { selectDtypes } from "./select_dtypes.ts"; +export type { DtypeSelector, SelectDtypesOptions } from "./select_dtypes.ts"; + +export { clipSeriesWithBounds, clipDataFrameWithBounds } from "./clip_with_bounds.ts"; +export type { + BoundArg, + SeriesClipBoundsOptions, + DataFrameClipBoundsOptions, +} from "./clip_with_bounds.ts"; + +export { inferDtype } from "./infer_dtype.ts"; +export type { InferredDtype, InferDtypeOptions } from "./infer_dtype.ts"; + +export { isna, notna, isnull, notnull } from "./notna.ts"; + +export { dropna, dropnaSeries, dropnaDataFrame } from "./dropna.ts"; +export type { DropnaHow, DropnaDataFrameOptions } from "./dropna.ts"; + +export { combineFirstSeries, combineFirstDataFrame } from "./combine_first.ts"; + +export { valueCountsBinned } from "./value_counts_full.ts"; +export type { ValueCountsBinnedOptions } from "./value_counts_full.ts"; + +export { + duplicatedSeries, + duplicatedDataFrame, + dropDuplicatesSeries, + dropDuplicatesDataFrame, +} from "./duplicated.ts"; +export type { + KeepPolicy, + DuplicatedDataFrameOptions, + DuplicatedSeriesOptions, +} from "./duplicated.ts"; + +export { explodeSeries, explodeDataFrame } from "./explode.ts"; +export type { ExplodeOptions, ExplodeDataFrameOptions } from "./explode.ts"; + +export { isin, dataFrameIsin } from "./isin.ts"; +export type { IsinValues, IsinDict, DataFrameIsinValues } from "./isin.ts"; + +export { rollingSem, rollingSkew, rollingKurt, rollingQuantile } from "./window_extended.ts"; +export type { WindowExtOptions, RollingQuantileOptions } from "./window_extended.ts"; +export { fillna, countna, countValid } from "./notna_isna.ts"; +export type { IsnaInput, FillnaOptions, DropnaOptions } from "./notna_isna.ts"; +export { + strNormalize, + strGetDummies, + strExtractAll, + strRemovePrefix, + strRemoveSuffix, + strTranslate, + strCharWidth, + strByteLength, +} from "./string_ops.ts"; +export type { NormalizeForm, StrInput, ExtractAllOptions } from "./string_ops.ts"; +export { + strSplitExpand, + strExtractGroups, + strPartition, + strRPartition, + strMultiReplace, + strIndent, + strDedent, +} from "./string_ops_extended.ts"; +export type { + SplitExpandOptions, + ExtractGroupsOptions, + PartitionResult, + ReplacePair, + IndentOptions, +} from "./string_ops_extended.ts"; +export { + digitize, + histogram, + linspace, + arange, + percentileOfScore, + zscore, + minMaxNormalize, + coefficientOfVariation, + seriesDigitize, +} from "./numeric_extended.ts"; +export type { + HistogramOptions, + HistogramResult, + ZscoreOptions, + MinMaxOptions, + CvOptions, +} from "./numeric_extended.ts"; +export { + catFromCodes, + catUnionCategories, + catIntersectCategories, + catDiffCategories, + catEqualCategories, + catSortByFreq, + catToOrdinal, + catFreqTable, + catCrossTab, + catRecode, +} from "./categorical_ops.ts"; +export type { + CatFromCodesOptions, + CatSortByFreqOptions, + CatCrossTabOptions, +} from "./categorical_ops.ts"; +export { + formatFloat, + formatPercent, + formatScientific, + formatEngineering, + formatThousands, + formatCurrency, + formatCompact, + makeFloatFormatter, + makePercentFormatter, + makeCurrencyFormatter, + applySeriesFormatter, + applyDataFrameFormatter, + seriesToString, + dataFrameToString, +} from "./format_ops.ts"; +export type { + Formatter, + SeriesToStringOptions, + DataFrameToStringOptions, +} from "./format_ops.ts"; + +export { clipAdvancedSeries, clipAdvancedDataFrame } from "./clip_advanced.ts"; +export type { + SeriesBound, + DataFrameBound, + ClipAdvancedSeriesOptions, + ClipAdvancedDataFrameOptions, +} from "./clip_advanced.ts"; + +export { idxminSeries, idxmaxSeries, idxminDataFrame, idxmaxDataFrame } from "./idxmin_idxmax.ts"; +export type { IdxOptions, IdxDataFrameOptions } from "./idxmin_idxmax.ts"; + +export { modeSeries, modeDataFrame } from "./mode.ts"; +export type { ModeSeriesOptions, ModeDataFrameOptions } from "./mode.ts"; + +export { + nancount, + nansum, + nanmean, + nanmedian, + nanvar, + nanstd, + nanmin, + nanmax, + nanprod, +} from "./nancumops.ts"; +export type { NanInput, NanAggOptions } from "./nancumops.ts"; + +export { + nuniqueSeries, + nuniqueDataFrame, + anySeries, + allSeries, + anyDataFrame, + allDataFrame, +} from "./nunique.ts"; +export type { + NuniqueSeriesOptions, + NuniqueDataFrameOptions, + AnyAllSeriesOptions, + AnyAllDataFrameOptions, +} from "./nunique.ts"; + +export { pctChangeSeries, pctChangeDataFrame } from "./pct_change.ts"; +export type { + PctChangeFillMethod, + PctChangeOptions, + DataFramePctChangeOptions, +} from "./pct_change.ts"; + +export { quantileSeries, quantileDataFrame } from "./quantile.ts"; +export type { + QuantileInterpolation, + QuantileSeriesOptions, + QuantileDataFrameOptions, +} from "./quantile.ts"; + +export { replaceSeries, replaceDataFrame } from "./replace.ts"; +export type { + ReplaceMapping, + ReplaceSpec, + ReplaceOptions, + DataFrameReplaceOptions, +} from "./replace.ts"; + +export { varSeries, semSeries, varDataFrame, semDataFrame } from "./sem_var.ts"; +export type { VarSemSeriesOptions, VarSemDataFrameOptions } from "./sem_var.ts"; + +export { skewSeries, kurtSeries, skewDataFrame, kurtDataFrame } from "./skew_kurt.ts"; +export type { + SkewKurtSeriesOptions, + SkewKurtDataFrameOptions, +} from "./skew_kurt.ts"; + +export { toDatetime } from "./to_datetime.ts"; +export type { DatetimeUnit, DatetimeErrors, ToDatetimeOptions } from "./to_datetime.ts"; + +export { ffillSeries, bfillSeries, dataFrameFfill, dataFrameBfill } from "./na_ops.ts"; +export type { FillDirectionOptions, DataFrameFillOptions } from "./na_ops.ts"; diff --git a/src/stats/na_ops.ts b/src/stats/na_ops.ts new file mode 100644 index 00000000..c776bb1f --- /dev/null +++ b/src/stats/na_ops.ts @@ -0,0 +1,336 @@ +/** + * na_ops β€” missing-value utilities for Series and DataFrame. + * + * Mirrors the following pandas module-level functions and methods: + * - `pd.isna(obj)` / `pd.isnull(obj)` β€” detect missing values + * - `pd.notna(obj)` / `pd.notnull(obj)` β€” detect non-missing values + * - `Series.ffill()` / `DataFrame.ffill()` β€” forward-fill missing values + * - `Series.bfill()` / `DataFrame.bfill()` β€” backward-fill missing values + * + * All functions are **pure** (return new objects; inputs are unchanged). + * + * @module + */ + +import { DataFrame } from "../core/index.ts"; +import { Series } from "../core/index.ts"; +import type { Scalar } from "../types.ts"; + +// ─── public types ───────────────────────────────────────────────────────────── + +/** Options for {@link ffillSeries} and {@link bfillSeries}. */ +export interface FillDirectionOptions { + /** + * Maximum number of consecutive NaN/null values to fill. + * `null` means no limit (default). + */ + readonly limit?: number | null; +} + +/** Options for {@link dataFrameFfill} and {@link dataFrameBfill}. */ +export interface DataFrameFillOptions extends FillDirectionOptions { + /** + * - `0` or `"index"` (default): fill missing values down each **column**. + * - `1` or `"columns"`: fill missing values across each **row**. + */ + readonly axis?: 0 | 1 | "index" | "columns"; +} + +// ─── helpers ────────────────────────────────────────────────────────────────── + +/** True when `v` should be treated as missing. */ +function isMissing(v: Scalar): boolean { + return v === null || v === undefined || (typeof v === "number" && Number.isNaN(v)); +} + +/** Forward-fill an array of scalars in-place (returns a new array). */ +function ffillArray(vals: readonly Scalar[], limit: number | null): Scalar[] { + const out: Scalar[] = Array.from(vals); + let lastValid: Scalar = null; + let streak = 0; + for (let i = 0; i < out.length; i++) { + if (isMissing(out[i])) { + if (!isMissing(lastValid) && (limit === null || streak < limit)) { + out[i] = lastValid; + streak++; + } + } else { + lastValid = out[i] as Scalar; + streak = 0; + } + } + return out; +} + +/** Backward-fill an array of scalars (returns a new array). */ +function bfillArray(vals: readonly Scalar[], limit: number | null): Scalar[] { + const out: Scalar[] = Array.from(vals); + let nextValid: Scalar = null; + let streak = 0; + for (let i = out.length - 1; i >= 0; i--) { + if (isMissing(out[i])) { + if (!isMissing(nextValid) && (limit === null || streak < limit)) { + out[i] = nextValid; + streak++; + } + } else { + nextValid = out[i] as Scalar; + streak = 0; + } + } + return out; +} + +// ─── isna / notna ───────────────────────────────────────────────────────────── + +/** + * Detect missing values in a scalar, Series, or DataFrame. + * + * - For a **scalar**: returns `true` if the value is `null`, `undefined`, or `NaN`. + * - For a **Series**: returns a `Series` of the same index. + * - For a **DataFrame**: returns a `DataFrame` of boolean columns. + * + * Mirrors `pandas.isna()` / `pandas.isnull()`. + * + * @example + * ```ts + * import { isna } from "tsb"; + * isna(null); // true + * isna(42); // false + * isna(NaN); // true + * + * const s = new Series({ data: [1, null, NaN, 4] }); + * isna(s); // Series([false, true, true, false]) + * ``` + */ +export function isna(value: Scalar): boolean; +export function isna(value: Series): Series; +export function isna(value: DataFrame): DataFrame; +export function isna( + value: Scalar | Series | DataFrame, +): boolean | Series | DataFrame { + if (value instanceof DataFrame) { + return value.isna(); + } + if (value instanceof Series) { + return value.isna(); + } + return isMissing(value as Scalar); +} + +/** + * Detect non-missing values in a scalar, Series, or DataFrame. + * + * Mirrors `pandas.notna()` / `pandas.notnull()`. + * + * @example + * ```ts + * import { notna } from "tsb"; + * notna(null); // false + * notna(42); // true + * ``` + */ +export function notna(value: Scalar): boolean; +export function notna(value: Series): Series; +export function notna(value: DataFrame): DataFrame; +export function notna( + value: Scalar | Series | DataFrame, +): boolean | Series | DataFrame { + if (value instanceof DataFrame) { + return value.notna(); + } + if (value instanceof Series) { + return value.notna(); + } + return !isMissing(value as Scalar); +} + +/** Alias for {@link isna}. Mirrors `pandas.isnull()`. */ +export const isnull = isna; + +/** Alias for {@link notna}. Mirrors `pandas.notnull()`. */ +export const notnull = notna; + +// ─── ffill ──────────────────────────────────────────────────────────────────── + +/** + * Forward-fill missing values in a Series. + * + * Each `null`/`NaN` value is replaced with the last non-missing value + * that precedes it (if any). Values before the first non-missing value + * remain missing. + * + * Mirrors `pandas.Series.ffill()`. + * + * @param series - Input Series (unchanged). + * @param options - Optional `{ limit }` β€” max consecutive fills. + * @returns New Series with forward-filled values. + * + * @example + * ```ts + * import { ffillSeries } from "tsb"; + * const s = new Series({ data: [1, null, null, 4] }); + * ffillSeries(s); // Series([1, 1, 1, 4]) + * ``` + */ +export function ffillSeries( + series: Series, + options?: FillDirectionOptions, +): Series { + const limit = options?.limit ?? null; + const filled = ffillArray(series.values as readonly Scalar[], limit) as T[]; + return new Series({ + data: filled, + index: series.index, + dtype: series.dtype, + name: series.name ?? undefined, + }); +} + +/** + * Backward-fill missing values in a Series. + * + * Each `null`/`NaN` value is replaced with the next non-missing value + * that follows it (if any). Values after the last non-missing value + * remain missing. + * + * Mirrors `pandas.Series.bfill()`. + * + * @example + * ```ts + * import { bfillSeries } from "tsb"; + * const s = new Series({ data: [1, null, null, 4] }); + * bfillSeries(s); // Series([1, 4, 4, 4]) + * ``` + */ +export function bfillSeries( + series: Series, + options?: FillDirectionOptions, +): Series { + const limit = options?.limit ?? null; + const filled = bfillArray(series.values as readonly Scalar[], limit) as T[]; + return new Series({ + data: filled, + index: series.index, + dtype: series.dtype, + name: series.name ?? undefined, + }); +} + +// ─── DataFrame ffill / bfill ────────────────────────────────────────────────── + +/** + * Forward-fill missing values in a DataFrame. + * + * By default operates **column-wise** (axis=0): each column is independently + * forward-filled. With `axis=1` each row is forward-filled across columns. + * + * Mirrors `pandas.DataFrame.ffill()`. + * + * @example + * ```ts + * import { dataFrameFfill } from "tsb"; + * const df = new DataFrame({ data: { a: [1, null, 3], b: [null, 2, null] } }); + * dataFrameFfill(df); + * // a: [1, 1, 3] + * // b: [null, 2, 2] + * ``` + */ +export function dataFrameFfill(df: DataFrame, options?: DataFrameFillOptions): DataFrame { + const limit = options?.limit ?? null; + const axis = options?.axis ?? 0; + const byRow = axis === 1 || axis === "columns"; + + if (!byRow) { + // column-wise: fill each column independently + const colMap = new Map>(); + for (const name of df.columns.values) { + const col = df.col(name); + const filled = ffillArray(col.values, limit) as Scalar[]; + colMap.set(name, new Series({ data: filled, index: col.index, dtype: col.dtype })); + } + return new DataFrame(colMap, df.index); + } + + // row-wise: fill across columns for each row + const nRows = df.shape[0]; + const cols = df.columns.values; + const columns = cols.map((name) => df.col(name)); + const rowsFilled: Scalar[][] = columns.map((c) => Array.from(c.values)); + for (let r = 0; r < nRows; r++) { + const rowVals: Scalar[] = columns.map((_, ci) => rowsFilled[ci]?.[r] ?? null); + const filled = ffillArray(rowVals, limit); + for (let ci = 0; ci < cols.length; ci++) { + const rowsFilledCI = rowsFilled[ci]; + if (rowsFilledCI !== undefined) { + rowsFilledCI[r] = filled[ci] ?? null; + } + } + } + const colMap = new Map>(); + for (let ci = 0; ci < cols.length; ci++) { + const name = cols[ci] as string; + const col = columns[ci] as Series; + colMap.set( + name, + new Series({ + data: rowsFilled[ci] ?? [], + index: col.index, + dtype: col.dtype, + }), + ); + } + return new DataFrame(colMap, df.index); +} + +/** + * Backward-fill missing values in a DataFrame. + * + * By default operates **column-wise** (axis=0). With `axis=1` fills across rows. + * + * Mirrors `pandas.DataFrame.bfill()`. + */ +export function dataFrameBfill(df: DataFrame, options?: DataFrameFillOptions): DataFrame { + const limit = options?.limit ?? null; + const axis = options?.axis ?? 0; + const byRow = axis === 1 || axis === "columns"; + + if (!byRow) { + const colMap = new Map>(); + for (const name of df.columns.values) { + const col = df.col(name); + const filled = bfillArray(col.values, limit) as Scalar[]; + colMap.set(name, new Series({ data: filled, index: col.index, dtype: col.dtype })); + } + return new DataFrame(colMap, df.index); + } + + const nRows = df.shape[0]; + const cols = df.columns.values; + const columns = cols.map((name) => df.col(name)); + const rowsFilled: Scalar[][] = columns.map((c) => Array.from(c.values)); + for (let r = 0; r < nRows; r++) { + const rowVals: Scalar[] = columns.map((_, ci) => rowsFilled[ci]?.[r] ?? null); + const filled = bfillArray(rowVals, limit); + for (let ci = 0; ci < cols.length; ci++) { + const rowsFilledCI = rowsFilled[ci]; + if (rowsFilledCI !== undefined) { + rowsFilledCI[r] = filled[ci] ?? null; + } + } + } + const colMap = new Map>(); + for (let ci = 0; ci < cols.length; ci++) { + const name = cols[ci] as string; + const col = columns[ci] as Series; + colMap.set( + name, + new Series({ + data: rowsFilled[ci] ?? [], + index: col.index, + dtype: col.dtype, + }), + ); + } + return new DataFrame(colMap, df.index); +} diff --git a/src/stats/pct_change.ts b/src/stats/pct_change.ts new file mode 100644 index 00000000..10e527ec --- /dev/null +++ b/src/stats/pct_change.ts @@ -0,0 +1,238 @@ +/** + * pct_change β€” percentage change between current and prior element. + * + * Mirrors `pandas.Series.pct_change()` / `pandas.DataFrame.pct_change()`: + * - `pctChangeSeries(series, options)` β€” per-element % change + * - `pctChangeDataFrame(df, options)` β€” column-wise % change + * + * Formula (per element i, with shift=periods): + * `result[i] = (x[i] - x[i-periods]) / x[i-periods]` + * + * When `fillMethod` is set, NaN/null values in the source are filled *before* + * computing the ratio (matching pandas' default behaviour of `fill_method="pad"`). + * + * @module + */ + +import { DataFrame } from "../core/index.ts"; +import { Series } from "../core/index.ts"; +import type { Scalar } from "../types.ts"; + +// ─── public types ───────────────────────────────────────────────────────────── + +/** Fill method applied to NaN/null before computing pct_change. */ +export type PctChangeFillMethod = "pad" | "bfill"; + +/** Options for {@link pctChangeSeries} and {@link pctChangeDataFrame}. */ +export interface PctChangeOptions { + /** + * Number of periods (lags) to shift when computing the ratio. + * Positive values look backward; negative values look forward. + * Default `1`. + */ + readonly periods?: number; + /** + * How to fill NaN/null values *before* computing the ratio. + * - `"pad"` (default): forward-fill (last valid observation carries forward). + * - `"bfill"`: backward-fill (next valid observation fills backward). + * - `null`: no filling β€” NaN/null stays as-is. + */ + readonly fillMethod?: PctChangeFillMethod | null; + /** + * Maximum number of consecutive NaN/null values to fill when `fillMethod` + * is set. `undefined` / `null` means no limit. + */ + readonly limit?: number | null; +} + +/** Options for {@link pctChangeDataFrame} β€” adds an axis selector. */ +export interface DataFramePctChangeOptions extends PctChangeOptions { + /** + * - `0` or `"index"` (default): apply operation **column-wise** (down rows). + * - `1` or `"columns"`: apply operation **row-wise** (across columns). + */ + readonly axis?: 0 | 1 | "index" | "columns"; +} + +// ─── helpers ────────────────────────────────────────────────────────────────── + +/** True when `v` is a valid number (not null, undefined, or NaN). */ +function isNum(v: Scalar): v is number { + return typeof v === "number" && !Number.isNaN(v) && v !== null; +} + +/** + * Forward-fill an array of scalars in place, respecting an optional limit. + * Returns a NEW array. + */ +function padFill(vals: readonly Scalar[], limit: number | null | undefined): Scalar[] { + const out: Scalar[] = [...vals]; + let run = 0; + let lastValid: Scalar = null; + for (let i = 0; i < out.length; i++) { + const v = out[i] as Scalar; + if (v !== null && v !== undefined && !(typeof v === "number" && Number.isNaN(v))) { + lastValid = v; + run = 0; + } else if (lastValid !== null && (limit == null || run < limit)) { + out[i] = lastValid; + run++; + } + } + return out; +} + +/** + * Backward-fill an array of scalars, respecting an optional limit. + * Returns a NEW array. + */ +function bfillFill(vals: readonly Scalar[], limit: number | null | undefined): Scalar[] { + const tmp = padFill([...vals].reverse(), limit); + return tmp.reverse(); +} + +/** Fill NaN/null in `vals` using the requested method. */ +function applyFill( + vals: readonly Scalar[], + method: PctChangeFillMethod | null | undefined, + limit: number | null | undefined, +): Scalar[] { + if (!method) { + return [...vals]; + } + return method === "pad" ? padFill(vals, limit) : bfillFill(vals, limit); +} + +/** Compute pct_change on a flat array of scalars. */ +function computePct(vals: readonly Scalar[], periods: number): Scalar[] { + const n = vals.length; + const out: Scalar[] = new Array(n).fill(null); + const shift = periods; + if (shift >= 0) { + for (let i = shift; i < n; i++) { + const curr = vals[i] as Scalar; + const prev = vals[i - shift] as Scalar; + if (isNum(curr) && isNum(prev) && prev !== 0) { + out[i] = curr / prev - 1; + } else if (isNum(curr) && isNum(prev) && prev === 0) { + // 0 denominator β†’ Infinity (same as pandas) + out[i] = + curr === 0 ? Number.NaN : curr > 0 ? Number.POSITIVE_INFINITY : Number.NEGATIVE_INFINITY; + } else { + out[i] = null; + } + } + } else { + // Negative periods: look forward + const absShift = -shift; + for (let i = 0; i < n - absShift; i++) { + const curr = vals[i] as Scalar; + const fwd = vals[i + absShift] as Scalar; + if (isNum(curr) && isNum(fwd) && curr !== 0) { + out[i] = fwd / curr - 1; + } else if (isNum(curr) && isNum(fwd) && curr === 0) { + out[i] = + fwd === 0 ? Number.NaN : fwd > 0 ? Number.POSITIVE_INFINITY : Number.NEGATIVE_INFINITY; + } else { + out[i] = null; + } + } + } + return out; +} + +// ─── public API ─────────────────────────────────────────────────────────────── + +/** + * Compute the fractional change between a Series element and the element + * `periods` positions earlier (or later, for negative `periods`). + * + * Matches `pandas.Series.pct_change()`. + * + * @example + * ```ts + * const s = new Series({ data: [100, 110, 99, 121] }); + * pctChangeSeries(s); // [null, 0.1, -0.1, 0.2222…] + * ``` + */ +export function pctChangeSeries( + series: Series, + options: PctChangeOptions = {}, +): Series { + const periods = options.periods ?? 1; + const fillMethod = options.fillMethod !== undefined ? options.fillMethod : "pad"; + const limit = options.limit ?? null; + + const filled = applyFill(series.values, fillMethod, limit); + const result = computePct(filled, periods); + + return new Series({ + data: result, + index: series.index, + name: series.name, + }); +} + +/** + * Compute percentage change for every column (or row) of a DataFrame. + * + * Matches `pandas.DataFrame.pct_change()`. + * + * @example + * ```ts + * const df = new DataFrame(new Map([ + * ["a", new Series({ data: [100, 110, 121] })], + * ["b", new Series({ data: [200, 180, 198] })], + * ])); + * pctChangeDataFrame(df); // fractional change per column + * ``` + */ +export function pctChangeDataFrame( + df: DataFrame, + options: DataFramePctChangeOptions = {}, +): DataFrame { + const axis = options.axis ?? 0; + const colWise = axis === 0 || axis === "index"; + + if (colWise) { + const colMap = new Map>(); + for (const name of df.columns.values) { + colMap.set(name, pctChangeSeries(df.col(name), options)); + } + return new DataFrame(colMap, df.index); + } + + // Row-wise: each row across columns + const periods = options.periods ?? 1; + const fillMethod = options.fillMethod !== undefined ? options.fillMethod : "pad"; + const limit = options.limit ?? null; + const nRows = df.index.size; + const cols = df.columns.values; + const nCols = cols.length; + + const resultCols = new Map(); + for (const name of cols) { + resultCols.set(name, new Array(nRows).fill(null)); + } + + for (let r = 0; r < nRows; r++) { + const row: Scalar[] = []; + for (const name of cols) { + row.push(df.col(name).values[r] as Scalar); + } + const filled = applyFill(row, fillMethod, limit); + const pct = computePct(filled, periods); + for (let c = 0; c < nCols; c++) { + (resultCols.get(cols[c] as string) as Scalar[])[r] = pct[c] as Scalar; + } + } + + const colMap = new Map>(); + for (const name of cols) { + colMap.set( + name, + new Series({ data: resultCols.get(name) as Scalar[], index: df.index, name }), + ); + } + return new DataFrame(colMap, df.index); +} diff --git a/tests/stats/na_ops.test.ts b/tests/stats/na_ops.test.ts new file mode 100644 index 00000000..340406ac --- /dev/null +++ b/tests/stats/na_ops.test.ts @@ -0,0 +1,280 @@ +/** + * Tests for na_ops β€” missing-value utilities (isna, notna, ffill, bfill). + */ + +import { describe, expect, it } from "bun:test"; +import fc from "fast-check"; +import { + DataFrame, + Series, + bfillSeries, + dataFrameBfill, + dataFrameFfill, + ffillSeries, + isna, + isnull, + notna, + notnull, +} from "../../src/index.ts"; + +// ─── isna / notna ───────────────────────────────────────────────────────────── + +describe("isna (scalar)", () => { + it("returns true for null", () => expect(isna(null)).toBe(true)); + it("returns true for undefined", () => expect(isna(undefined)).toBe(true)); + it("returns true for NaN", () => expect(isna(Number.NaN)).toBe(true)); + it("returns false for 0", () => expect(isna(0)).toBe(false)); + it("returns false for empty string", () => expect(isna("")).toBe(false)); + it("returns false for false", () => expect(isna(false)).toBe(false)); + it("returns false for a number", () => expect(isna(42)).toBe(false)); +}); + +describe("notna (scalar)", () => { + it("returns false for null", () => expect(notna(null)).toBe(false)); + it("returns false for NaN", () => expect(notna(Number.NaN)).toBe(false)); + it("returns true for 42", () => expect(notna(42)).toBe(true)); + it("returns true for a string", () => expect(notna("hello")).toBe(true)); +}); + +describe("isnull / notnull aliases", () => { + it("isnull equals isna for scalar", () => { + expect(isnull(null)).toBe(isna(null)); + expect(isnull(42)).toBe(isna(42)); + }); + it("notnull equals notna for scalar", () => { + expect(notnull(null)).toBe(notna(null)); + expect(notnull(42)).toBe(notna(42)); + }); +}); + +describe("isna (Series)", () => { + it("returns boolean Series of correct length", () => { + const s = new Series({ data: [1, null, Number.NaN, 4] }); + const result = isna(s); + expect(result).toBeInstanceOf(Series); + expect([...result.values]).toEqual([false, true, true, false]); + }); + + it("all present", () => { + const s = new Series({ data: [1, 2, 3] }); + expect([...isna(s).values]).toEqual([false, false, false]); + }); + + it("all missing", () => { + const s = new Series({ data: [null, null, Number.NaN] }); + expect([...isna(s).values]).toEqual([true, true, true]); + }); +}); + +describe("notna (Series)", () => { + it("is the inverse of isna", () => { + const s = new Series({ data: [1, null, Number.NaN, 4] }); + const na = isna(s).values; + const nna = notna(s).values; + for (let i = 0; i < na.length; i++) { + expect(nna[i]).toBe(!na[i]); + } + }); +}); + +describe("isna (DataFrame)", () => { + it("returns DataFrame of booleans", () => { + const df = DataFrame.fromColumns({ a: [1, null], b: [Number.NaN, 2] }); + const result = isna(df); + expect(result).toBeInstanceOf(DataFrame); + expect([...result.col("a").values]).toEqual([false, true]); + expect([...result.col("b").values]).toEqual([true, false]); + }); +}); + +describe("notna (DataFrame)", () => { + it("returns inverse of isna DataFrame", () => { + const df = DataFrame.fromColumns({ a: [1, null], b: [Number.NaN, 2] }); + expect([...notna(df).col("a").values]).toEqual([true, false]); + expect([...notna(df).col("b").values]).toEqual([false, true]); + }); +}); + +// ─── ffillSeries ────────────────────────────────────────────────────────────── + +describe("ffillSeries", () => { + it("fills nulls with preceding value", () => { + const s = new Series({ data: [1, null, null, 4] }); + expect([...ffillSeries(s).values]).toEqual([1, 1, 1, 4]); + }); + + it("leaves leading nulls untouched", () => { + const s = new Series({ data: [null, null, 3, null] }); + expect([...ffillSeries(s).values]).toEqual([null, null, 3, 3]); + }); + + it("NaN is treated as missing", () => { + const s = new Series({ data: [2, Number.NaN, 5] }); + const result = ffillSeries(s).values; + expect(result[0]).toBe(2); + expect(result[1]).toBe(2); + expect(result[2]).toBe(5); + }); + + it("respects limit option", () => { + const s = new Series({ data: [1, null, null, null, 5] }); + expect([...ffillSeries(s, { limit: 1 }).values]).toEqual([1, 1, null, null, 5]); + }); + + it("preserves original Series", () => { + const s = new Series({ data: [1, null, 3] }); + ffillSeries(s); + expect([...s.values]).toEqual([1, null, 3]); + }); + + it("empty Series returns empty", () => { + const s = new Series({ data: [] }); + expect([...ffillSeries(s).values]).toEqual([]); + }); + + it("preserves name and index", () => { + const s = new Series({ data: [1, null], name: "x" }); + const filled = ffillSeries(s); + expect(filled.name).toBe("x"); + expect(filled.index.size).toBe(2); + }); +}); + +// ─── bfillSeries ────────────────────────────────────────────────────────────── + +describe("bfillSeries", () => { + it("fills nulls with following value", () => { + const s = new Series({ data: [1, null, null, 4] }); + expect([...bfillSeries(s).values]).toEqual([1, 4, 4, 4]); + }); + + it("leaves trailing nulls untouched", () => { + const s = new Series({ data: [null, 3, null, null] }); + expect([...bfillSeries(s).values]).toEqual([3, 3, null, null]); + }); + + it("respects limit option", () => { + const s = new Series({ data: [1, null, null, null, 5] }); + expect([...bfillSeries(s, { limit: 2 }).values]).toEqual([1, null, 5, 5, 5]); + }); + + it("empty Series returns empty", () => { + const s = new Series({ data: [] }); + expect([...bfillSeries(s).values]).toEqual([]); + }); +}); + +// ─── dataFrameFfill ─────────────────────────────────────────────────────────── + +describe("dataFrameFfill (column-wise)", () => { + it("fills each column independently", () => { + const df = DataFrame.fromColumns({ a: [1, null, 3], b: [null, 2, null] }); + const result = dataFrameFfill(df); + expect([...result.col("a").values]).toEqual([1, 1, 3]); + expect([...result.col("b").values]).toEqual([null, 2, 2]); + }); + + it("preserves index", () => { + const df = DataFrame.fromColumns({ x: [1, null] }); + expect(dataFrameFfill(df).index.size).toBe(2); + }); +}); + +describe("dataFrameFfill (row-wise)", () => { + it("fills across columns per row", () => { + const df = DataFrame.fromColumns({ a: [1, null], b: [null, null], c: [3, 4] }); + const result = dataFrameFfill(df, { axis: 1 }); + expect([...result.col("a").values]).toEqual([1, null]); + expect([...result.col("b").values]).toEqual([1, null]); + expect([...result.col("c").values]).toEqual([3, 4]); + }); +}); + +// ─── dataFrameBfill ─────────────────────────────────────────────────────────── + +describe("dataFrameBfill (column-wise)", () => { + it("fills each column backward", () => { + const df = DataFrame.fromColumns({ a: [null, null, 3], b: [1, null, null] }); + const result = dataFrameBfill(df); + expect([...result.col("a").values]).toEqual([3, 3, 3]); + expect([...result.col("b").values]).toEqual([1, null, null]); + }); +}); + +describe("dataFrameBfill (row-wise)", () => { + it("fills backward across columns per row", () => { + const df = DataFrame.fromColumns({ a: [null, 1], b: [null, null], c: [3, null] }); + const result = dataFrameBfill(df, { axis: 1 }); + expect([...result.col("a").values]).toEqual([3, 1]); + expect([...result.col("b").values]).toEqual([3, null]); + expect([...result.col("c").values]).toEqual([3, null]); + }); +}); + +// ─── property-based tests ───────────────────────────────────────────────────── + +describe("property: ffill followed by bfill fills all if any non-null", () => { + it("all values filled when at least one is present", () => { + fc.assert( + fc.property( + fc.array(fc.option(fc.integer({ min: 0, max: 100 }), { nil: null }), { + minLength: 1, + maxLength: 20, + }), + (raw) => { + const hasNonNull = raw.some((v) => v !== null); + if (!hasNonNull) { + return true; + } + const s = new Series({ data: raw }); + const result = bfillSeries(ffillSeries(s)); + return result.values.every((v) => v !== null); + }, + ), + ); + }); +}); + +describe("property: ffill never introduces new non-null values beyond last valid", () => { + it("ffilled series has no nulls after first valid value", () => { + fc.assert( + fc.property( + fc.array(fc.option(fc.integer({ min: -50, max: 50 }), { nil: null }), { + minLength: 0, + maxLength: 30, + }), + (raw) => { + const s = new Series({ data: raw }); + const filled = ffillSeries(s).values; + let sawValid = false; + for (const v of filled) { + if (v !== null) { + sawValid = true; + } + if (sawValid && v === null) { + return false; + } + } + return true; + }, + ), + ); + }); +}); + +describe("property: isna is inverse of notna for scalars", () => { + it("isna(v) === !notna(v)", () => { + fc.assert( + fc.property( + fc.oneof( + fc.integer(), + fc.float({ noNaN: false }), + fc.constant(null), + fc.string(), + fc.boolean(), + ), + (v) => isna(v as Parameters[0]) === !notna(v as Parameters[0]), + ), + ); + }); +}); diff --git a/tests/stats/pct_change.test.ts b/tests/stats/pct_change.test.ts new file mode 100644 index 00000000..f7015e4a --- /dev/null +++ b/tests/stats/pct_change.test.ts @@ -0,0 +1,252 @@ +/** + * Tests for src/stats/pct_change.ts β€” pctChangeSeries, pctChangeDataFrame + */ +import { describe, expect, it } from "bun:test"; +import fc from "fast-check"; +import { DataFrame, Series, pctChangeDataFrame, pctChangeSeries } from "../../src/index.ts"; +import type { Scalar } from "../../src/index.ts"; + +// ─── helpers ───────────────────────────────────────────────────────────────── + +function s(data: readonly Scalar[]): Series { + return new Series({ data: [...data] }); +} + +function nanEq(a: Scalar, b: Scalar): boolean { + if (typeof a === "number" && Number.isNaN(a) && typeof b === "number" && Number.isNaN(b)) { + return true; + } + return a === b; +} + +function arrEq(a: readonly Scalar[], b: readonly Scalar[]): boolean { + if (a.length !== b.length) { + return false; + } + for (let i = 0; i < a.length; i++) { + if (!nanEq(a[i] as Scalar, b[i] as Scalar)) { + return false; + } + } + return true; +} + +function close(a: Scalar, b: Scalar, eps = 1e-9): boolean { + if (a === null && b === null) { + return true; + } + if (typeof a !== "number" || typeof b !== "number") { + return false; + } + if (Number.isNaN(a) && Number.isNaN(b)) { + return true; + } + return Math.abs(a - b) < eps; +} + +function arrClose(a: readonly Scalar[], b: readonly Scalar[], eps = 1e-9): boolean { + if (a.length !== b.length) { + return false; + } + for (let i = 0; i < a.length; i++) { + if (!close(a[i] as Scalar, b[i] as Scalar, eps)) { + return false; + } + } + return true; +} + +// ─── pctChangeSeries ───────────────────────────────────────────────────────── + +describe("pctChangeSeries", () => { + it("basic increasing sequence", () => { + const result = pctChangeSeries(s([100, 110, 121, 133.1])); + expect(result.values[0]).toBeNull(); + expect(close(result.values[1] as Scalar, 0.1)).toBe(true); + expect(close(result.values[2] as Scalar, 0.1)).toBe(true); + expect(close(result.values[3] as Scalar, 0.1)).toBe(true); + }); + + it("decreasing sequence", () => { + const result = pctChangeSeries(s([200, 180, 162])); + expect(result.values[0]).toBeNull(); + expect(close(result.values[1] as Scalar, -0.1)).toBe(true); + expect(close(result.values[2] as Scalar, -0.1)).toBe(true); + }); + + it("periods=2", () => { + const result = pctChangeSeries(s([100, 105, 110, 121]), { periods: 2 }); + expect(result.values[0]).toBeNull(); + expect(result.values[1]).toBeNull(); + expect(close(result.values[2] as Scalar, 0.1)).toBe(true); + expect(close(result.values[3] as Scalar, (121 - 105) / 105)).toBe(true); + }); + + it("negative periods (look forward)", () => { + const result = pctChangeSeries(s([100, 110, 121]), { periods: -1 }); + expect(close(result.values[0] as Scalar, 0.1)).toBe(true); + expect(close(result.values[1] as Scalar, 0.1)).toBe(true); + expect(result.values[2]).toBeNull(); + }); + + it("NaN/null propagates when fillMethod=null", () => { + const result = pctChangeSeries(s([100, null, 110]), { fillMethod: null }); + expect(result.values[0]).toBeNull(); + expect(result.values[1]).toBeNull(); + expect(result.values[2]).toBeNull(); + }); + + it("fillMethod=pad fills NaN before computing", () => { + const result = pctChangeSeries(s([100, null, 110]), { fillMethod: "pad" }); + // after pad-fill: [100, 100, 110] + // pct: [null, 0, 0.1] + expect(result.values[0]).toBeNull(); + expect(close(result.values[1] as Scalar, 0)).toBe(true); + expect(close(result.values[2] as Scalar, 0.1)).toBe(true); + }); + + it("fillMethod=bfill fills NaN backward before computing", () => { + const result = pctChangeSeries(s([100, null, 110, 121]), { fillMethod: "bfill" }); + // after bfill: [100, 110, 110, 121] + // pct: [null, 0.1, 0, 0.1] + expect(result.values[0]).toBeNull(); + expect(close(result.values[1] as Scalar, 0.1)).toBe(true); + expect(close(result.values[2] as Scalar, 0)).toBe(true); + expect(close(result.values[3] as Scalar, 0.1)).toBe(true); + }); + + it("limit=1 caps forward-fill", () => { + const result = pctChangeSeries(s([100, null, null, 130]), { + fillMethod: "pad", + limit: 1, + }); + // after pad with limit=1: [100, 100, null, 130] + // pct: [null, 0, null, null] (null/100 β†’ null) + expect(result.values[0]).toBeNull(); + expect(close(result.values[1] as Scalar, 0)).toBe(true); + expect(result.values[2]).toBeNull(); + expect(result.values[3]).toBeNull(); + }); + + it("zero denominator returns Infinity", () => { + const result = pctChangeSeries(s([0, 10]), { fillMethod: null }); + expect(result.values[1]).toBe(Number.POSITIVE_INFINITY); + }); + + it("zero/zero denominator returns NaN", () => { + const result = pctChangeSeries(s([0, 0]), { fillMethod: null }); + expect(Number.isNaN(result.values[1] as number)).toBe(true); + }); + + it("preserves Series name and index", () => { + const src = new Series({ data: [10, 20, 30], name: "price" }); + const result = pctChangeSeries(src); + expect(result.name).toBe("price"); + expect(result.index.size).toBe(3); + }); + + it("empty series returns empty", () => { + const result = pctChangeSeries(s([])); + expect(result.values.length).toBe(0); + }); + + it("single-element series returns [null]", () => { + const result = pctChangeSeries(s([42])); + expect(result.values[0]).toBeNull(); + }); +}); + +// ─── pctChangeDataFrame ─────────────────────────────────────────────────────── + +describe("pctChangeDataFrame", () => { + it("column-wise (default)", () => { + const df = DataFrame.fromColumns({ + a: [100, 110, 121], + b: [200, 180, 198], + }); + const result = pctChangeDataFrame(df); + const colA = result.col("a").values; + const colB = result.col("b").values; + expect(colA[0]).toBeNull(); + expect(close(colA[1] as Scalar, 0.1)).toBe(true); + expect(close(colA[2] as Scalar, 0.1)).toBe(true); + expect(colB[0]).toBeNull(); + expect(close(colB[1] as Scalar, -0.1)).toBe(true); + expect(close(colB[2] as Scalar, 0.1)).toBe(true); + }); + + it("row-wise (axis=1)", () => { + const df = DataFrame.fromColumns({ + a: [100, 200], + b: [110, 220], + c: [121, 242], + }); + const result = pctChangeDataFrame(df, { axis: 1 }); + // row 0: [100, 110, 121] β†’ [null, 0.1, 0.1] + // row 1: [200, 220, 242] β†’ [null, 0.1, 0.1] + const row0a = result.col("a").values[0]; + const row0b = result.col("b").values[0]; + const row0c = result.col("c").values[0]; + expect(row0a).toBeNull(); + expect(close(row0b as Scalar, 0.1)).toBe(true); + expect(close(row0c as Scalar, 0.1)).toBe(true); + const row1a = result.col("a").values[1]; + const row1b = result.col("b").values[1]; + expect(row1a).toBeNull(); + expect(close(row1b as Scalar, 0.1)).toBe(true); + }); + + it("preserves column order", () => { + const df = DataFrame.fromColumns({ + x: [1, 2], + y: [3, 6], + }); + const result = pctChangeDataFrame(df); + expect(result.columns.values).toEqual(["x", "y"]); + }); +}); + +// ─── property-based tests ───────────────────────────────────────────────────── + +describe("pctChangeSeries β€” property tests", () => { + it("result length equals input length", () => { + fc.assert( + fc.property(fc.array(fc.float({ noNaN: true }), { minLength: 0, maxLength: 50 }), (arr) => { + const result = pctChangeSeries(s(arr)); + return result.values.length === arr.length; + }), + ); + }); + + it("first element is always null for periods=1", () => { + fc.assert( + fc.property(fc.array(fc.float({ noNaN: true }), { minLength: 1, maxLength: 50 }), (arr) => { + const result = pctChangeSeries(s(arr)); + return result.values[0] === null; + }), + ); + }); + + it("pct_change(x, -p) equals pct_change_reversed pattern", () => { + // For a sequence of positive numbers with periods=1 and periods=-1: + // result[-1][i] represents the change looking forward, so result[-1][i] = (x[i+1]-x[i])/x[i] + // and result[+1][i+1] = (x[i+1]-x[i])/x[i], so they should agree on matching indices + fc.assert( + fc.property( + fc.array(fc.float({ noNaN: true, min: 1, max: 1000 }), { minLength: 3, maxLength: 20 }), + (arr) => { + const fwd = pctChangeSeries(s(arr), { periods: -1, fillMethod: null }); + const bwd = pctChangeSeries(s(arr), { periods: 1, fillMethod: null }); + // fwd[i] = (arr[i+1] - arr[i]) / arr[i] + // bwd[i+1] = (arr[i+1] - arr[i]) / arr[i] ← same ratio + for (let i = 0; i < arr.length - 1; i++) { + if (!close(fwd.values[i] as Scalar, bwd.values[i + 1] as Scalar, 1e-6)) { + return false; + } + } + return true; + }, + ), + ); + }); +});