df-script 1.6.0 → 1.7.0

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

@@ -1,25 +1,359 @@
 import type { AggFn, UniqueArrayStatsOptions } from "../../types";
 import { ExprBase } from "../ExprBase";
+/**
+ * @namespace $df.col
+ * @category ColumnExpression
+ * @syntax $df.col(<column_name>).{symbol}(...)
+ */
 export declare class AggregationExpr extends ExprBase {
     _deriveAgg(fn: AggFn<any>): this;
+    _deriveAggBinary(other: any, fn: AggFn<[any, any]>): this;
+    /**
+     * Aggregation: Returns true if all values in the group are truthy.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ group: ["A", "A", "B"], val: [true, true, false] })
+     * >>> df.group_by("group").agg($df.col("val").all().alias("all_true"))
+     * shape: (2, 2)
+     * ┌───────┬──────────┐
+     * │ group │ all_true │
+     * ├───────┼──────────┤
+     * │ "A"   │ true     │
+     * │ "B"   │ false    │
+     * └───────┴──────────┘
+     */
     all(): this;
+    /**
+     * Aggregation: Checks if all values in the group are null.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ group: ["A", "A"], val: [null, null] })
+     * >>> df.group_by("group").agg($df.col("val").all_null().alias("is_null"))
+     * shape: (1, 2)
+     * ┌───────┬─────────┐
+     * │ group │ is_null │
+     * ├───────┼─────────┤
+     * │ "A"   │ true    │
+     * └───────┴─────────┘
+     */
     all_null(): this;
+    /**
+     * Aggregation: Checks if any value in the group is truthy.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ group: ["A", "A", "B"], val: [true, false, false] })
+     * >>> df.group_by("group").agg($df.col("val").any().alias("any_true"))
+     * shape: (2, 2)
+     * ┌───────┬──────────┐
+     * │ group │ any_true │
+     * ├───────┼──────────┤
+     * │ "A"   │ true     │
+     * │ "B"   │ false    │
+     * └───────┴──────────┘
+     */
     any(): this;
+    /**
+     * Aggregation: Checks if any value in the group is null.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ group: ["A", "A"], val: [10, null] })
+     * >>> df.group_by("group").agg($df.col("val").any_null().alias("has_null"))
+     * shape: (1, 2)
+     * ┌───────┬──────────┐
+     * │ group │ has_null │
+     * ├───────┼──────────┤
+     * │ "A"   │ true     │
+     * └───────┴──────────┘
+     */
     any_null(): this;
+    /**
+     * Aggregation: Computes the arithmetic mean of the group.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ group: ["A", "A"], val: [10, 20] })
+     * >>> df.group_by("group").agg($df.col("val").avg().alias("mean"))
+     * shape: (1, 2)
+     * ┌───────┬──────┐
+     * │ group │ mean │
+     * ├───────┼──────┤
+     * │ "A"   │ 15   │
+     * └───────┴──────┘
+     */
     avg(): this;
+    /**
+     * Aggregation: Computes the Pearson correlation coefficient between two columns.
+     * @param other The target column expression to correlate with.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ x: [1, 2, 3], y: [2, 4, 6] })
+     * >>> df.select($df.col("x").corr($df.col("y")).alias("correlation"))
+     * shape: (1, 1)
+     * ┌─────────────┐
+     * │ correlation │
+     * ├─────────────┤
+     * │ 1           │
+     * └─────────────┘
+     */
+    corr(other: any): this;
+    /**
+     * Aggregation: Returns the count of records inside the group.
+     * @param options Config flags including whether to count null values.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ group: ["A", "A"], val: [10, null] })
+     * >>> df.group_by("group").agg($df.col("val").count().alias("cnt"))
+     * shape: (1, 2)
+     * ┌───────┬─────┐
+     * │ group │ cnt │
+     * ├───────┼─────┤
+     * │ "A"   │ 1   │
+     * └───────┴─────┘
+     */
     count(options?: {
         includeNulls?: boolean;
     }): this;
+    /**
+     * Aggregation: Computes the covariance between two columns.
+     * @param other The target column expression to compute covariance with.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ x: [1, 2, 3], y: [2, 4, 6] })
+     * >>> df.select($df.col("x").cov($df.col("y")).alias("covariance"))
+     * shape: (1, 1)
+     * ┌────────────┐
+     * │ covariance │
+     * ├────────────┤
+     * │ 2          │
+     * └────────────┘
+     */
+    cov(other: any): this;
+    /**
+     * Aggregation: Computes the dot product with another column.
+     * @param other The other column expression to compute the dot product with.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ x: [1, 2, 3], y: [2, 3, 4] })
+     * >>> df.select($df.col("x").dot($df.col("y")).alias("dot_product"))
+     * shape: (1, 1)
+     * ┌─────────────┐
+     * │ dot_product │
+     * ├─────────────┤
+     * │ 20          │
+     * └─────────────┘
+     */
+    dot(other: any): this;
+    /**
+     * Aggregation: Finds the first value in the group.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ group: ["A", "A"], val: [10, 20] })
+     * >>> df.group_by("group").agg($df.col("val").first().alias("first_val"))
+     * shape: (1, 2)
+     * ┌───────┬───────────┐
+     * │ group │ first_val │
+     * ├───────┼───────────┤
+     * │ "A"   │ 10        │
+     * └───────┴───────────┘
+     */
     first(): this;
+    /**
+     * Aggregation: Combines all values in the group into a single array/list cell.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ group: ["A", "A"], val: [10, 20] })
+     * >>> df.group_by("group").agg($df.col("val").implode().alias("list_val"))
+     * shape: (1, 2)
+     * ┌───────┬──────────┐
+     * │ group │ list_val │
+     * ├───────┼──────────┤
+     * │ "A"   │ [10, 20] │
+     * └───────┴──────────┘
+     */
     implode(): this;
+    /**
+     * Aggregation: Finds the last value in the group.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ group: ["A", "A"], val: [10, 20] })
+     * >>> df.group_by("group").agg($df.col("val").last().alias("last_val"))
+     * shape: (1, 2)
+     * ┌───────┬──────────┐
+     * │ group │ last_val │
+     * ├───────┼──────────┤
+     * │ "A"   │ 20       │
+     * └───────┴──────────┘
+     */
     last(): this;
+    /**
+     * Aggregation: Finds the maximum value in the group.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ group: ["A", "A"], val: [10, 50] })
+     * >>> df.group_by("group").agg($df.col("val").max().alias("max_val"))
+     * shape: (1, 2)
+     * ┌───────┬─────────┐
+     * │ group │ max_val │
+     * ├───────┼─────────┤
+     * │ "A"   │ 50      │
+     * └───────┴─────────┘
+     */
     max(): this;
+    /**
+     * Aggregation: Computes the arithmetic mean of elements in the group.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ group: ["A", "A"], val: [10, 30] })
+     * >>> df.group_by("group").agg($df.col("val").mean().alias("mean_val"))
+     * shape: (1, 2)
+     * ┌───────┬──────────┐
+     * │ group │ mean_val │
+     * ├───────┼──────────┤
+     * │ "A"   │ 20       │
+     * └───────┴──────────┘
+     */
     mean(): this;
+    /**
+     * Aggregation: Computes the 50th percentile median.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ group: ["A", "A", "A"], val: [10, 50, 20] })
+     * >>> df.group_by("group").agg($df.col("val").median().alias("med"))
+     * shape: (1, 2)
+     * ┌───────┬─────┐
+     * │ group │ med │
+     * ├───────┼─────┤
+     * │ "A"   │ 20  │
+     * └───────┴─────┘
+     */
     median(): this;
+    /**
+     * Aggregation: Finds the minimum value in the group.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ group: ["A", "A"], val: [10, 50] })
+     * >>> df.group_by("group").agg($df.col("val").min().alias("min_val"))
+     * shape: (1, 2)
+     * ┌───────┬─────────┐
+     * │ group │ min_val │
+     * ├───────┼─────────┤
+     * │ "A"   │ 10      │
+     * └───────┴─────────┘
+     */
     min(): this;
+    /**
+     * Aggregation: Finds the statistical mode (most frequent value).
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ group: ["A", "A", "A"], val: [5, 5, 10] })
+     * >>> df.group_by("group").agg($df.col("val").mode().alias("mode_val"))
+     * shape: (1, 2)
+     * ┌───────┬──────────┐
+     * │ group │ mode_val │
+     * ├───────┼──────────┤
+     * │ "A"   │ 5        │
+     * └───────┴──────────┘
+     */
     mode(): this;
+    /**
+     * Aggregation: Computes number of unique elements.
+     * @param options Uniqueness options.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ group: ["A", "A", "A"], val: [5, 5, 10] })
+     * >>> df.group_by("group").agg($df.col("val").n_unique().alias("unique_cnt"))
+     * shape: (1, 2)
+     * ┌───────┬────────────┐
+     * │ group │ unique_cnt │
+     * ├───────┼────────────┤
+     * │ "A"   │ 2          │
+     * └───────┴────────────┘
+     */
     n_unique(options?: UniqueArrayStatsOptions): this;
+    /**
+     * Aggregation: Counts the number of null or missing records.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ group: ["A", "A"], val: [10, null] })
+     * >>> df.group_by("group").agg($df.col("val").null_count().alias("nulls"))
+     * shape: (1, 2)
+     * ┌───────┬───────┐
+     * │ group │ nulls │
+     * ├───────┼───────┤
+     * │ "A"   │ 1     │
+     * └───────┴───────┘
+     */
+    null_count(): this;
+    /**
+     * Aggregation: Computes the specific quantile values (0.0 to 1.0).
+     * @param q The quantile parameter value between 0.0 and 1.0.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ val: [10, 20, 30, 40] })
+     * >>> df.select($df.col("val").quantile(0.75).alias("q75"))
+     * shape: (1, 1)
+     * ┌─────┐
+     * │ q75 │
+     * ├─────┤
+     * │ 32.5│
+     * └─────┘
+     */
     quantile(q: number): this;
+    /**
+     * Aggregation: Computes the Spearman rank correlation coefficient.
+     * @param other The other column expression to correlate with.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ x: [1, 2, 3], y: [5, 6, 7] })
+     * >>> df.select($df.col("x").spearman_corr($df.col("y")).alias("spearman"))
+     * shape: (1, 1)
+     * ┌──────────┐
+     * │ spearman │
+     * ├──────────┤
+     * │ 1        │
+     * └──────────┘
+     */
+    spearman_corr(other: any): this;
+    /**
+     * Aggregation: Computes sample standard deviation.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ group: ["A", "A", "A"], val: [10, 20, 30] })
+     * >>> df.group_by("group").agg($df.col("val").std().alias("std_dev"))
+     * shape: (1, 2)
+     * ┌───────┬─────────┐
+     * │ group │ std_dev │
+     * ├───────┼─────────┤
+     * │ "A"   │ 10      │
+     * └───────┴─────────┘
+     */
     std(): this;
+    /**
+     * Aggregation: Computes the sum of elements in the group.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ group: ["A", "A"], val: [10, 20] })
+     * >>> df.group_by("group").agg($df.col("val").sum().alias("total"))
+     * shape: (1, 2)
+     * ┌───────┬───────┐
+     * │ group │ total │
+     * ├───────┼───────┤
+     * │ "A"   │ 30    │
+     * └───────┴───────┘
+     */
     sum(): this;
+    /**
+     * Aggregation: Computes weighted average.
+     * @param weights The weight values or column expression.
+     * @returns ColumnExpression
+     * @example
+     * >>> const df = $df.data({ val: [10, 20], weight: [1, 3] })
+     * >>> df.select($df.col("val").w_avg($df.col("weight")).alias("w_mean"))
+     * shape: (1, 1)
+     * ┌────────┐
+     * │ w_mean │
+     * ├────────┤
+     * │ 17.5   │
+     * └────────┘
+     */
+    w_avg(weights: any): this;
 }