df-script 1.5.0 → 1.7.0

package/dist/columnExpressions/mixins/ArrayExpr.d.ts

@@ -0,0 +1,567 @@
+import { ExprBase } from "../ExprBase";
+import { SortArrayOptions, StepSliceArrayOptions } from "../../utils";
+import type { UniqueArrayStatsOptions, JoinArrayOptions, ExplodeOptions, IExpr, AnyTypedArray, ToStructOptions } from "../../types";
+/**
+ * @namespace $df.col.arr
+ * @category ColumnExpression
+ * @syntax $df.col(<column_name>).arr.{symbol}(...)
+ */
+export declare class ArrayExprNamespace {
+    expr: any;
+    constructor(expr: any);
+    _deriveArray(fn: (arr: any[] | AnyTypedArray) => any): any;
+    /**
+     * Returns true if all items in nested list cells are truthy.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[true, true], [true, false]] })
+     * >>> df.with_columns($df.col("a").arr.all().alias("all_true"))
+     * shape: (2, 2)
+     * ┌───────────────┬──────────┐
+     * │ a             │ all_true │
+     * ├───────────────┼──────────┤
+     * │ [true, true]  │ true     │
+     * │ [true, false] │ false    │
+     * └───────────────┴──────────┘
+     */
+    all(): any;
+    /**
+     * Returns true if any item in nested list cells is truthy.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[true, false], [false, false]] })
+     * >>> df.with_columns($df.col("a").arr.any().alias("any_true"))
+     * shape: (2, 2)
+     * ┌────────────────┬──────────┐
+     * │ a              │ any_true │
+     * ├────────────────┼──────────┤
+     * │ [true, false]  │ true     │
+     * │ [false, false] │ false    │
+     * └────────────────┴──────────┘
+     */
+    any(): any;
+    /**
+     * Checks if nested lists contain item.
+     * @param item The element to search for.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] })
+     * >>> df.with_columns($df.col("a").arr.contains(3).alias("has_three"))
+     * shape: (2, 2)
+     * ┌───────────┬───────────┐
+     * │ a         │ has_three │
+     * ├───────────┼───────────┤
+     * │ [1, 2, 3] │ true      │
+     * │ [4, 5]    │ false     │
+     * └───────────┴───────────┘
+     */
+    contains(item: any): any;
+    /**
+     * Checks if nested lists contain all elements in items.
+     * @param items Array of elements that must all be present.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[1, 2, 3], [1, 5]] })
+     * >>> df.with_columns($df.col("a").arr.contains_all([1, 2]).alias("has_all"))
+     * shape: (2, 2)
+     * ┌───────────┬─────────┐
+     * │ a         │ has_all │
+     * ├───────────┼─────────┤
+     * │ [1, 2, 3] │ true    │
+     * │ [1, 5]    │ false   │
+     * └───────────┴─────────┘
+     */
+    contains_all(items: ArrayLike<any>): any;
+    /**
+     * Checks if nested lists contain any element in items.
+     * @param items Array of elements where at least one must be present.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[1, 2], [3, 4]] })
+     * >>> df.with_columns($df.col("a").arr.contains_any([2, 3]).alias("has_any"))
+     * shape: (2, 2)
+     * ┌────────┬─────────┐
+     * │ a      │ has_any │
+     * ├────────┼─────────┤
+     * │ [1, 2] │ true    │
+     * │ [3, 4] │ true    │
+     * └────────┴─────────┘
+     */
+    contains_any(items: ArrayLike<any>): any;
+    /**
+     * Counts occurrence frequency of item inside nested lists.
+     * @param item The value to count occurrences of.
+     * @param options Statistics and matching options.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[1, 2, 2, 3], [4, 5]] })
+     * >>> df.with_columns($df.col("a").arr.count_matches(2).alias("twos"))
+     * shape: (2, 2)
+     * ┌──────────────┬──────┐
+     * │ a            │ twos │
+     * ├──────────────┼──────┤
+     * │ [1, 2, 2, 3] │ 2    │
+     * │ [4, 5]       │ 0    │
+     * └──────────────┴──────┘
+     */
+    count_matches(item: any, options?: UniqueArrayStatsOptions): any;
+    /**
+     * Filters elements of list columns matching a boolean sub-expression.
+     * @param expr The boolean column expression to filter by.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[1, 5, 10], [2, 8]] })
+     * >>> df.with_columns($df.col("a").arr.filter($df.element().gt(4)).alias("filtered"))
+     * shape: (2, 2)
+     * ┌────────────┬──────────┐
+     * │ a          │ filtered │
+     * ├────────────┼──────────┤
+     * │ [1, 5, 10] │ [5, 10]  │
+     * │ [2, 8]     │ [8]      │
+     * └────────────┴──────────┘
+     */
+    filter(expr: IExpr): any;
+    /**
+     * Expands lists into row-wise records.
+     * @param options Config options including handling of empty arrays and nulls.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[1, 2], [3]] })
+     * >>> df.explode($df.col("a").arr.explode())
+     * shape: (3, 1)
+     * ┌───┐
+     * │ a │
+     * ├───┤
+     * │ 1 │
+     * │ 2 │
+     * │ 3 │
+     * └───┘
+     */
+    explode({ empty_as_null, keep_nulls }?: ExplodeOptions): any;
+    /**
+     * Returns the first element of each list.
+     * @param null_on_oob If true, returns null if the list is empty (default: true).
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[10, 20], [30]] })
+     * >>> df.with_columns($df.col("a").arr.first().alias("first_a"))
+     * shape: (2, 2)
+     * ┌──────────┬─────────┐
+     * │ a        │ first_a │
+     * ├──────────┼─────────┤
+     * │ [10, 20] │ 10      │
+     * │ [30]     │ 30      │
+     * └──────────┴─────────┘
+     */
+    first(null_on_oob?: boolean): any;
+    /**
+     * Gathers specific indices from each nested list.
+     * @param indices Index or array of indices to extract.
+     * @param null_on_oob If true, returns null for indices out of bounds (default: true).
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[10, 20, 30], [40, 50]] })
+     * >>> df.with_columns($df.col("a").arr.gather([0, 2]).alias("g"))
+     * shape: (2, 2)
+     * ┌──────────────┬──────────┐
+     * │ a            │ g        │
+     * ├──────────────┼──────────┤
+     * │ [10, 20, 30] │ [10, 30] │
+     * │ [40, 50]     │ [40, null]│
+     * └──────────────┴──────────┘
+     */
+    gather(indices: number | ArrayLike<number>, null_on_oob?: boolean): any;
+    /**
+     * Gather element slices with custom steps.
+     * @param options Config options including offset, limit, and step size.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[1, 2, 3, 4], [5, 6, 7]] })
+     * >>> df.with_columns($df.col("a").arr.gather_every({ step: 2 }).alias("ge"))
+     * shape: (2, 2)
+     * ┌──────────────┬────────┐
+     * │ a            │ ge     │
+     * ├──────────────┼────────┤
+     * │ [1, 2, 3, 4] │ [1, 3] │
+     * │ [5, 6, 7]    │ [5, 7] │
+     * └──────────────┴────────┘
+     */
+    gather_every(options?: StepSliceArrayOptions): any;
+    /**
+     * Extracts a single list element by its index position.
+     * @param index The 0-based or negative index position to extract.
+     * @param null_on_oob If true, returns null if index is out of bounds (default: true).
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[10, 20], [30]] })
+     * >>> df.with_columns($df.col("a").arr.get(1).alias("second"))
+     * shape: (2, 2)
+     * ┌──────────┬────────┐
+     * │ a        │ second │
+     * ├──────────┼────────┤
+     * │ [10, 20] │ 20     │
+     * │ [30]     │ null   │
+     * └──────────┴────────┘
+     */
+    get(index: number, null_on_oob?: boolean): any;
+    /**
+     * Joins elements of list columns into a single string column.
+     * @param separator The character sequence separating list elements.
+     * @param options String conversion options.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [["a", "b"], ["c"]] })
+     * >>> df.with_columns($df.col("a").arr.join("-").alias("joined"))
+     * shape: (2, 2)
+     * ┌──────────┬────────┐
+     * │ a        │ joined │
+     * ├──────────┼────────┤
+     * │ ["a","b"]│ "a-b"  │
+     * │ ["c"]    │ "c"    │
+     * └──────────┴────────┘
+     */
+    join(separator?: string, options?: JoinArrayOptions): any;
+    /**
+     * Returns the last element of each list.
+     * @param null_on_oob If true, returns null if the list is empty (default: true).
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[10, 20], [30]] })
+     * >>> df.with_columns($df.col("a").arr.last().alias("last_a"))
+     * shape: (2, 2)
+     * ┌──────────┬────────┐
+     * │ a        │ last_a │
+     * ├──────────┼────────┤
+     * │ [10, 20] │ 20     │
+     * │ [30]     │ 30     │
+     * └──────────┴────────┐
+     */
+    last(null_on_oob?: boolean): any;
+    /**
+     * Returns the length of each list inside the column cell.
+     */
+    len(): any;
+    /**
+     * Returns the length of each list inside the column cell.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[10, 20], [30, 40, 50]] })
+     * >>> df.with_columns($df.col("a").arr.lengths().alias("len_a"))
+     * shape: (2, 2)
+     * ┌──────────────┬───────┐
+     * │ a            │ len_a │
+     * ├──────────────┼───────┤
+     * │ [10, 20]     │ 2     │
+     * │ [30, 40, 50] │ 3     │
+     * └──────────────┴───────┘
+     */
+    lengths(): any;
+    /**
+     * Returns the maximum value of elements inside each list.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[1, 5, 2], [10, 4]] })
+     * >>> df.with_columns($df.col("a").arr.max().alias("max_a"))
+     * shape: (2, 2)
+     * ┌───────────┬───────┐
+     * │ a         │ max_a │
+     * ├───────────┼───────┤
+     * │ [1, 5, 2] │ 5     │
+     * │ [10, 4]   │ 10    │
+     * └───────────┴───────┘
+     */
+    max(): any;
+    /**
+     * Returns the index of maximum value.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[1, 5, 2], [10, 4]] })
+     * >>> df.with_columns($df.col("a").arr.max_index().alias("max_idx"))
+     * shape: (2, 2)
+     * ┌───────────┬─────────┐
+     * │ a         │ max_idx │
+     * ├───────────┼─────────┤
+     * │ [1, 5, 2] │ 1       │
+     * │ [10, 4]   │ 0       │
+     * └───────────┴─────────┘
+     */
+    max_index(): any;
+    /**
+     * Returns average of elements inside each list.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[1, 5, 9], [10, 40]] })
+     * >>> df.with_columns($df.col("a").arr.mean().alias("mean_a"))
+     * shape: (2, 2)
+     * ┌───────────┬────────┐
+     * │ a         │ mean_a │
+     * ├───────────┼────────┤
+     * │ [1, 5, 9] │ 5      │
+     * │ [10, 40]  │ 25     │
+     * └───────────┴────────┘
+     */
+    mean(): any;
+    /**
+     * Returns statistical median inside each list.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[1, 3, 5, 7], [10, 20, 30]] })
+     * >>> df.with_columns($df.col("a").arr.median().alias("med"))
+     * shape: (2, 2)
+     * ┌────────────────┬──────┐
+     * │ a              │ med  │
+     * ├────────────────┼──────┤
+     * │ [1, 3, 5, 7]   │ 4    │
+     * │ [10, 20, 30]   │ 20   │
+     * └────────────────┴──────┘
+     */
+    median(): any;
+    /**
+     * Returns minimum of elements inside each list.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[1, 5, 2], [10, 4]] })
+     * >>> df.with_columns($df.col("a").arr.min().alias("min_a"))
+     * shape: (2, 2)
+     * ┌───────────┬───────┐
+     * │ a         │ min_a │
+     * ├───────────┼───────┤
+     * │ [1, 5, 2] │ 1     │
+     * │ [10, 4]   │ 4     │
+     * └───────────┴───────┘
+     */
+    min(): any;
+    /**
+     * Returns the index of minimum value.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[5, 1, 2], [10, 4]] })
+     * >>> df.with_columns($df.col("a").arr.min_index().alias("min_idx"))
+     * shape: (2, 2)
+     * ┌───────────┬─────────┐
+     * │ a         │ min_idx │
+     * ├───────────┼─────────┤
+     * │ [5, 1, 2] │ 1       │
+     * │ [10, 4]   │ 1       │
+     * └───────────┴─────────┘
+     */
+    min_index(): any;
+    /**
+     * Returns the mode value inside each list.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[1, 2, 2, 3], [5, 5, 6]] })
+     * >>> df.with_columns($df.col("a").arr.mode().alias("mode_a"))
+     * shape: (2, 2)
+     * ┌──────────────┬────────┐
+     * │ a            │ mode_a │
+     * ├──────────────┼────────┤
+     * │ [1, 2, 2, 3] │ 2      │
+     * │ [5, 5, 6]    │ 5      │
+     * └──────────────┴────────┘
+     */
+    mode(): any;
+    /**
+     * Returns the unique count of elements inside each list.
+     * @param options Formatting/statistics parameters.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[1, 2, 2, 3], [4, 5]] })
+     * >>> df.with_columns($df.col("a").arr.n_unique().alias("unique_len"))
+     * shape: (2, 2)
+     * ┌──────────────┬────────────┐
+     * │ a            │ unique_len │
+     * ├──────────────┼────────────┤
+     * │ [1, 2, 2, 3] │ 3          │
+     * │ [4, 5]       │ 2          │
+     * └──────────────┴────────────┘
+     */
+    n_unique(options?: UniqueArrayStatsOptions): any;
+    /**
+     * Reverses elements of list columns.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] })
+     * >>> df.with_columns($df.col("a").arr.reverse().alias("reversed"))
+     * shape: (2, 2)
+     * ┌───────────┬───────────┐
+     * │ a         │ reversed  │
+     * ├───────────┼───────────┤
+     * │ [1, 2, 3] │ [3, 2, 1] │
+     * │ [4, 5]    │ [5, 4]    │
+     * └───────────┴───────────┘
+     */
+    reverse(): any;
+    /**
+     * Shifts elements of list columns by N offsets.
+     * @param n Positive or negative offsets shift amount (default: 1).
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] })
+     * >>> df.with_columns($df.col("a").arr.shift(1).alias("shifted"))
+     * shape: (2, 2)
+     * ┌───────────┬──────────────────┐
+     * │ a         │ shifted          │
+     * ├───────────┼──────────────────┤
+     * │ [1, 2, 3] │ [null, 1, 2]     │
+     * │ [4, 5]    │ [null, 4]        │
+     * └───────────┴──────────────────┘
+     */
+    shift(n?: number): any;
+    /**
+     * Slices nested list arrays.
+     * @param start The slice starting index.
+     * @param end The slice ending index.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[1, 2, 3, 4], [5, 6]] })
+     * >>> df.with_columns($df.col("a").arr.slice(1, 3).alias("sliced"))
+     * shape: (2, 2)
+     * ┌──────────────┬────────┐
+     * │ a            │ sliced │
+     * ├──────────────┼────────┤
+     * │ [1, 2, 3, 4] │ [2, 3] │
+     * │ [5, 6]       │ [6]    │
+     * └──────────────┴────────┘
+     */
+    slice(start?: number, end?: number): any;
+    /**
+     * Splices elements in list cells.
+     * @param start The index where array modifications begin.
+     * @param deleteCount The number of elements to remove.
+     * @param items The elements to insert.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] })
+     * >>> df.with_columns($df.col("a").arr.splice(1, 1, 10, 20).alias("spliced"))
+     * shape: (2, 2)
+     * ┌───────────┬─────────────────┐
+     * │ a         │ spliced         │
+     * ├───────────┼─────────────────┤
+     * │ [1, 2, 3] │ [1, 10, 20, 3]  │
+     * │ [4, 5]    │ [4, 10, 20]     │
+     * └───────────┴─────────────────┘
+     */
+    splice(start: number, deleteCount?: number, ...items: any[]): any;
+    /**
+     * Sorts elements inside each list.
+     * @param options Sort customization parameters (e.g. descending flag).
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[3, 1, 2], [5, 4]] })
+     * >>> df.with_columns($df.col("a").arr.sort().alias("sorted"))
+     * shape: (2, 2)
+     * ┌───────────┬───────────┐
+     * │ a         │ sorted    │
+     * ├───────────┼───────────┤
+     * │ [3, 1, 2] │ [1, 2, 3] │
+     * │ [5, 4]    │ [4, 5]    │
+     * └───────────┴───────────┘
+     */
+    sort(options?: SortArrayOptions): any;
+    /**
+     * Returns sample standard deviation of elements inside each list.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[1, 2, 3], [10, 20]] })
+     * >>> df.with_columns($df.col("a").arr.std().alias("std_dev"))
+     * shape: (2, 2)
+     * ┌───────────┬─────────┐
+     * │ a         │ std_dev │
+     * ├───────────┼─────────┤
+     * │ [1, 2, 3] │ 1       │
+     * │ [10, 20]  │ 7.071   │
+     * └───────────┴─────────┘
+     */
+    std(): any;
+    /**
+     * Returns sum of elements inside each list.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[1, 2, 3], [10, 20]] })
+     * >>> df.with_columns($df.col("a").arr.sum().alias("sum_a"))
+     * shape: (2, 2)
+     * ┌───────────┬───────┐
+     * │ a         │ sum_a │
+     * ├───────────┼───────┤
+     * │ [1, 2, 3] │ 6     │
+     * │ [10, 20]  │ 30    │
+     * └───────────┴───────┘
+     */
+    sum(): any;
+    /**
+     * Converts list column elements to struct columns.
+     * @param options Config flags including custom field names or upper bound size.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[1, 2], [3, 4]] })
+     * >>> df.with_columns($df.col("a").arr.to_struct({ fields: ["x", "y"] }).alias("struct_a"))
+     * shape: (2, 2)
+     * ┌────────┬────────────────┐
+     * │ a      │ struct_a       │
+     * ├────────┼────────────────┤
+     * │ [1, 2] │ { x: 1, y: 2 } │
+     * │ [3, 4] │ { x: 3, y: 4 } │
+     * └────────┴────────────────┘
+     */
+    to_struct({ upper_bound, fields }?: ToStructOptions): any;
+    /**
+     * Fills each list with unique elements only.
+     * @param options Custom uniqueness matching configuration.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[1, 2, 2, 3], [4, 4, 5]] })
+     * >>> df.with_columns($df.col("a").arr.unique().alias("unique_a"))
+     * shape: (2, 2)
+     * ┌──────────────┬───────────┐
+     * │ a            │ unique_a  │
+     * ├──────────────┼───────────┤
+     * │ [1, 2, 2, 3] │ [1, 2, 3] │
+     * │ [4, 4, 5]    │ [4, 5]    │
+     * └──────────────┴───────────┘
+     */
+    unique(options?: UniqueArrayStatsOptions): any;
+    /**
+     * Returns sample variance of elements inside each list.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[1, 2, 3], [10, 20]] })
+     * >>> df.with_columns($df.col("a").arr.variance().alias("var_a"))
+     * shape: (2, 2)
+     * ┌───────────┬───────┐
+     * │ a         │ var_a │
+     * ├───────────┼───────┤
+     * │ [1, 2, 3] │ 1     │
+     * │ [10, 20]  │ 50    │
+     * └───────────┴───────┘
+     */
+    variance(): any;
+    /**
+     * Evaluates subExpr element-wise across array lists.
+     * @param expr The sub-expression to evaluate inside each nested list.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ a: [[1, 2], [3, 4]] })
+     * >>> df.with_columns($df.col("a").arr.eval($df.element().mul(10)).alias("multiplied"))
+     * shape: (2, 2)
+     * ┌────────┬────────────┐
+     * │ a      │ multiplied │
+     * ├────────┼────────────┤
+     * │ [1, 2] │ [10, 20]   │
+     * │ [3, 4] │ [30, 40]   │
+     * └────────┴────────────┘
+     */
+    eval(expr: IExpr): any;
+}
+export declare class ArrayExpr extends ExprBase {
+    /**
+     * Array namespace accessor for list-based column operations.
+     * @namespace $df.col
+     * @category ColumnExpression
+     * @syntax $df.col(<column_name>).arr
+     * @returns ArrayExprNamespace
+     * @example
+     * >>> df.select($df.col("a").arr.len())
+     */
+    get arr(): ArrayExprNamespace;
+}