deepbox 0.1.0

package/dist/index-DbultU6X.d.cts

@@ -0,0 +1,1427 @@
+import { A as Axis } from './tensor-B96jjJLQ.cjs';
+import { T as Tensor } from './Tensor-BQLk1ltW.cjs';
+
+/**
+ * Data structure for DataFrame initialization.
+ *
+ * Maps column names to arrays of values. All arrays must have the same length.
+ *
+ * @example
+ * ```ts
+ * const data: DataFrameData = {
+ *   name: ['Alice', 'Bob', 'Charlie'],
+ *   age: [25, 30, 35],
+ *   score: [85.5, 92.0, 78.5]
+ * };
+ * ```
+ */
+type DataFrameData = Record<string, unknown[]>;
+/**
+ * Configuration options for DataFrame construction.
+ *
+ * @property index - Custom row labels (defaults to 0, 1, 2, ...). Can be strings or numbers.
+ * @property columns - Custom column order (defaults to Object.keys order)
+ * @property copy - Whether to copy data on construction (default: true). Set to false for performance if data ownership can be transferred.
+ */
+type DataFrameOptions = {
+    index?: (string | number)[];
+    columns?: string[];
+    copy?: boolean;
+};
+/**
+ * Configuration options for Series construction.
+ *
+ * @property name - Optional name for the Series
+ * @property index - Custom index labels (defaults to 0, 1, 2, ...). Can be strings or numbers.
+ * @property copy - Whether to copy data on construction (default: true). Set to false for performance if data ownership can be transferred.
+ */
+type SeriesOptions = {
+    name?: string;
+    index?: (string | number)[];
+    copy?: boolean;
+};
+/**
+ * Supported aggregation functions for DataFrame groupby operations.
+ *
+ * - `sum`: Sum of values
+ * - `mean`: Arithmetic mean
+ * - `median`: Median value
+ * - `min`: Minimum value
+ * - `max`: Maximum value
+ * - `std`: Standard deviation
+ * - `var`: Variance
+ * - `count`: Count of non-null values
+ * - `first`: First value in group
+ * - `last`: Last value in group
+ */
+type AggregateFunction = "sum" | "mean" | "median" | "min" | "max" | "std" | "var" | "count" | "first" | "last";
+
+/**
+ * One-dimensional labeled array capable of holding any data type.
+ *
+ * A Series is like a column in a spreadsheet or database table. It combines:
+ * - An array of data values
+ * - An array of index labels (can be strings or numbers)
+ * - An optional name
+ *
+ * Similar to pandas Series in Python.
+ *
+ * @template T - The type of data stored in the Series
+ *
+ * @example
+ * ```ts
+ * // Create a numeric series
+ * const s = new Series([1, 2, 3, 4], { name: 'numbers' });
+ *
+ * // Create a series with custom index
+ * const s2 = new Series(['a', 'b', 'c'], {
+ *   index: ['row1', 'row2', 'row3'],
+ *   name: 'letters'
+ * });
+ * ```
+ *
+ * @see {@link https://pandas.pydata.org/docs/reference/api/pandas.Series.html | Pandas Series}
+ */
+declare class Series<T = unknown> {
+    private _data;
+    private _index;
+    private _indexPos;
+    private _name;
+    /**
+     * Creates a new Series instance.
+     *
+     * @param data - Array of values to store in the Series
+     * @param options - Configuration options
+     * @param options.index - Custom index labels (defaults to 0, 1, 2, ...)
+     * @param options.name - Optional name for the Series
+     *
+     * @example
+     * ```ts
+     * const s = new Series([10, 20, 30], {
+     *   index: ['a', 'b', 'c'],
+     *   name: 'values'
+     * });
+     * ```
+     */
+    constructor(data: T[], options?: SeriesOptions);
+    /**
+     * Get the underlying data array.
+     *
+     * @returns Read-only view of the data array
+     */
+    get data(): readonly T[];
+    /**
+     * Get the index labels.
+     *
+     * @returns Read-only view of the index array
+     */
+    get index(): readonly (string | number)[];
+    /**
+     * Get the Series name.
+     *
+     * @returns The name of this Series, or undefined if not set
+     */
+    get name(): string | undefined;
+    /**
+     * Get the number of elements in the Series.
+     *
+     * @returns Length of the Series
+     */
+    get length(): number;
+    /**
+     * Get a value by label.
+     *
+     * This method is an alias for `loc()`. It performs strict label-based lookup.
+     * For positional access, use `iloc()`.
+     *
+     * @param label - The index label to look up
+     * @returns The value at that label, or undefined if not found
+     *
+     * @example
+     * ```ts
+     * const s = new Series([10, 20, 30], { index: ['a', 'b', 'c'] });
+     * s.get('a');  // 10
+     * s.get('z');  // undefined
+     * ```
+     */
+    get(label: number | string): T | undefined;
+    /**
+     * Access a value by label (label-based indexing).
+     *
+     * @param label - The index label to look up
+     * @returns The value at that label, or undefined if not found
+     *
+     * @example
+     * ```ts
+     * const s = new Series([10, 20], { index: ['a', 'b'] });
+     * s.loc('a');  // 10
+     * ```
+     */
+    loc(label: string | number): T | undefined;
+    /**
+     * Access a value by integer position (position-based indexing).
+     *
+     * @param position - The integer position (0-based)
+     * @returns The value at that position, or undefined if out of bounds
+     * @throws {IndexError} If position is out of bounds
+     *
+     * @example
+     * ```ts
+     * const s = new Series([10, 20, 30]);
+     * s.iloc(0);  // 10
+     * s.iloc(2);  // 30
+     * ```
+     */
+    iloc(position: number): T | undefined;
+    /**
+     * Return the first n elements.
+     *
+     * @param n - Number of elements to return (default: 5)
+     * @returns New Series with the first n elements
+     *
+     * @example
+     * ```ts
+     * const s = new Series([1, 2, 3, 4, 5, 6]);
+     * s.head(3);  // Series([1, 2, 3])
+     * ```
+     */
+    head(n?: number): Series<T>;
+    /**
+     * Return the last n elements.
+     *
+     * @param n - Number of elements to return (default: 5)
+     * @returns New Series with the last n elements
+     *
+     * @example
+     * ```ts
+     * const s = new Series([1, 2, 3, 4, 5, 6]);
+     * s.tail(3);  // Series([4, 5, 6])
+     * ```
+     */
+    tail(n?: number): Series<T>;
+    /**
+     * Filter Series by a boolean predicate function.
+     *
+     * Filters both data AND index to maintain alignment.
+     *
+     * @param predicate - Function that returns true for elements to keep
+     * @returns New Series with only elements that passed the predicate
+     *
+     * @example
+     * ```ts
+     * const s = new Series([1, 2, 3, 4, 5]);
+     * s.filter(x => x > 2);  // Series([3, 4, 5])
+     * ```
+     */
+    filter(predicate: (value: T, index: number) => boolean): Series<T>;
+    /**
+     * Transform each element using a mapping function.
+     *
+     * @template U - The type of the transformed values
+     * @param fn - Function to apply to each element
+     * @returns New Series with transformed values
+     *
+     * @example
+     * ```ts
+     * const s = new Series([1, 2, 3]);
+     * s.map(x => x * 2);  // Series([2, 4, 6])
+     * ```
+     */
+    map<U>(fn: (value: T, index: number) => U): Series<U>;
+    /**
+     * Sort the Series values.
+     *
+     * Preserves index-value mapping by sorting `[value, index]` pairs.
+     *
+     * @param ascending - Sort in ascending order (default: true)
+     * @returns New sorted Series with index reordered to match
+     *
+     * @example
+     * ```ts
+     * const s = new Series([3, 1, 2], { index: ['a', 'b', 'c'] });
+     * s.sort();  // Series([1, 2, 3]) with index ['b', 'c', 'a']
+     * ```
+     */
+    sort(ascending?: boolean): Series<T>;
+    /**
+     * Get unique values in the Series.
+     *
+     * @returns Array of unique values (order preserved)
+     *
+     * @example
+     * ```ts
+     * const s = new Series([1, 2, 2, 3, 1]);
+     * s.unique();  // [1, 2, 3]
+     * ```
+     */
+    unique(): T[];
+    /**
+     * Count occurrences of unique values.
+     *
+     * Returns a Series where index is the unique values and data is their counts.
+     *
+     * @returns Series where index is unique values and data is their counts
+     *
+     * @example
+     * ```ts
+     * const s = new Series(['a', 'b', 'a', 'c', 'a']);
+     * s.valueCounts();  // Series([3, 1, 1]) with index ['a', 'b', 'c']
+     * ```
+     */
+    valueCounts(): Series<number>;
+    /**
+     * Calculate the sum of all values.
+     *
+     * Skips null, undefined, and NaN values.
+     *
+     * @returns Sum of all numeric values.
+     * @throws {DataValidationError} If Series is empty or contains non-numeric data
+     *
+     * @example
+     * ```ts
+     * const s = new Series([1, 2, null, 3, 4]);
+     * s.sum();  // 10
+     * ```
+     */
+    sum(): number;
+    /**
+     * Calculate the arithmetic mean (average) of all values.
+     *
+     * Skips null, undefined, and NaN values.
+     *
+     * @returns Mean of all numeric values.
+     * @throws {DataValidationError} If Series is empty or contains non-numeric data
+     *
+     * @example
+     * ```ts
+     * const s = new Series([1, 2, null, 3, 4]);
+     * s.mean();  // 2.5
+     * ```
+     */
+    mean(): number;
+    /**
+     * Calculate the median (middle value) of all values.
+     *
+     * Skips null, undefined, and NaN values.
+     * For even-length Series, returns the average of the two middle values.
+     *
+     * @returns Median value.
+     * @throws {DataValidationError} If Series is empty or contains non-numeric data
+     *
+     * @example
+     * ```ts
+     * const s = new Series([1, 2, 3, 4, 5]);
+     * s.median();  // 3
+     * ```
+     */
+    median(): number;
+    /**
+     * Calculate the standard deviation of all values.
+     *
+     * Skips null, undefined, and NaN values.
+     * Uses sample standard deviation (divides by n-1).
+     *
+     * @returns Standard deviation.
+     * @throws {DataValidationError} If Series is empty or contains non-numeric data
+     *
+     * @example
+     * ```ts
+     * const s = new Series([2, 4, 6, 8]);
+     * s.std();  // ~2.58
+     * ```
+     */
+    std(): number;
+    /**
+     * Calculate the variance of all values.
+     *
+     * Skips null, undefined, and NaN values.
+     * Uses sample variance (divides by n-1).
+     *
+     * @returns Variance.
+     * @throws {DataValidationError} If Series is empty or contains non-numeric data
+     *
+     * @example
+     * ```ts
+     * const s = new Series([2, 4, 6, 8]);
+     * s.var();  // ~6.67
+     * ```
+     */
+    var(): number;
+    /**
+     * Find the minimum value in the Series.
+     *
+     * Skips null, undefined, and NaN values.
+     *
+     * @returns Minimum value.
+     * @throws {DataValidationError} If Series is empty or contains non-numeric data
+     *
+     * @example
+     * ```ts
+     * const s = new Series([5, 2, 8, 1, 9]);
+     * s.min();  // 1
+     * ```
+     */
+    min(): number;
+    /**
+     * Find the maximum value in the Series.
+     *
+     * Skips null, undefined, and NaN values.
+     *
+     * @returns Maximum value.
+     * @throws {DataValidationError} If Series is empty or contains non-numeric data
+     *
+     * @example
+     * ```ts
+     * const s = new Series([5, 2, 8, 1, 9]);
+     * s.max();  // 9
+     * ```
+     */
+    max(): number;
+    /**
+     * Convert the Series to a plain JavaScript array.
+     *
+     * Returns a shallow copy of the data.
+     *
+     * @returns Array copy of the data
+     *
+     * @example
+     * ```ts
+     * const s = new Series([1, 2, 3]);
+     * const arr = s.toArray();  // [1, 2, 3]
+     * ```
+     */
+    toArray(): T[];
+    /**
+     * Convert the Series to an ndarray Tensor.
+     *
+     * Uses the `tensor()` factory function.
+     *
+     * @returns Tensor containing the Series data
+     * @throws {DataValidationError} If data cannot be converted to Tensor
+     *
+     * @example
+     * ```ts
+     * import { Series } from 'deepbox/dataframe';
+     *
+     * const s = new Series([1, 2, 3, 4]);
+     * const t = s.toTensor();  // Tensor([1, 2, 3, 4])
+     * ```
+     */
+    toTensor(): Tensor;
+    /**
+     * Return a human-readable string representation of this Series.
+     *
+     * Each row is printed as `index  value`, with an optional name/dtype
+     * footer.  Large Series are truncated with an ellipsis.
+     *
+     * @param maxRows - Maximum rows to display before summarizing (default: 20).
+     * @returns Formatted string representation
+     *
+     * @example
+     * ```ts
+     * const s = new Series([10, 20, 30], { name: 'values' });
+     * s.toString();
+     * // "0  10\n1  20\n2  30\nName: values, Length: 3"
+     * ```
+     */
+    toString(maxRows?: number): string;
+}
+
+/**
+ * Two-dimensional, size-mutable, potentially heterogeneous tabular data.
+ *
+ * A DataFrame is like a spreadsheet or SQL table. It consists of:
+ * - Rows (observations) identified by an index
+ * - Columns (variables) identified by column names
+ * - Data stored in a columnar format for efficient access
+ *
+ * Similar to pandas DataFrame in Python.
+ *
+ * @example
+ * ```ts
+ * import { DataFrame } from 'deepbox/dataframe';
+ *
+ * const df = new DataFrame({
+ *   name: ['Alice', 'Bob', 'Charlie'],
+ *   age: [25, 30, 35],
+ *   score: [85.5, 92.0, 78.5]
+ * });
+ *
+ * console.log(df.shape);  // [3, 3]
+ * console.log(df.columns);  // ['name', 'age', 'score']
+ * ```
+ *
+ * @see {@link https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html | Pandas DataFrame}
+ */
+declare class DataFrame {
+    private _data;
+    private _index;
+    private _indexPos;
+    private _columns;
+    /**
+     * Creates a new DataFrame instance.
+     *
+     * @param data - Object mapping column names to arrays of values.
+     *               All arrays must have the same length.
+     * @param options - Configuration options
+     * @param options.columns - Custom column order (defaults to Object.keys(data))
+     * @param options.index - Custom row labels (defaults to 0, 1, 2, ...)
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({
+     *   col1: [1, 2, 3],
+     *   col2: ['a', 'b', 'c']
+     * }, {
+     *   index: ['row1', 'row2', 'row3']
+     * });
+     * ```
+     */
+    constructor(data: DataFrameData, options?: DataFrameOptions);
+    /**
+     * Get the dimensions of the DataFrame.
+     *
+     * @returns Tuple of [rows, columns]
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [1, 2, 3], b: [4, 5, 6] });
+     * df.shape;  // [3, 2]
+     * ```
+     */
+    get shape(): [number, number];
+    /**
+     * Get the column names.
+     *
+     * @returns Array of column names (copy)
+     */
+    get columns(): string[];
+    /**
+     * Get the row index labels.
+     *
+     * @returns Array of index labels (copy)
+     */
+    get index(): (string | number)[];
+    /**
+     * Get a column as a Series.
+     *
+     * @param column - Column name to retrieve
+     * @returns Series containing the column data
+     * @throws {InvalidParameterError} If column doesn't exist
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ age: [25, 30, 35], name: ['Alice', 'Bob', 'Carol'] });
+     * const ageSeries = df.get('age');  // Series([25, 30, 35])
+     * ```
+     */
+    get(column: string): Series<unknown>;
+    get<T>(column: string, guard: (value: unknown) => value is T): Series<T>;
+    /**
+     * Access a row by label (label-based indexing).
+     *
+     * @param row - The index label of the row
+     * @returns Object mapping column names to values for that row
+     * @throws {IndexError} If row label not found
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame(
+     *   { age: [25, 30], name: ['Alice', 'Bob'] },
+     *   { index: ['row1', 'row2'] }
+     * );
+     * df.loc('row1');  // { age: 25, name: 'Alice' }
+     * ```
+     */
+    loc(row: string | number): Record<string, unknown>;
+    /**
+     * Access a row by integer position (position-based indexing).
+     *
+     * @param position - The integer position (0-based)
+     * @returns Object mapping column names to values for that row
+     * @throws {IndexError} If position is out of bounds
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ age: [25, 30], name: ['Alice', 'Bob'] });
+     * df.iloc(0);  // { age: 25, name: 'Alice' }
+     * df.iloc(1);  // { age: 30, name: 'Bob' }
+     * ```
+     */
+    iloc(position: number): Record<string, unknown>;
+    /**
+     * Return the first n rows.
+     *
+     * @param n - Number of rows to return (default: 5)
+     * @returns New DataFrame with first n rows
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [1, 2, 3, 4, 5], b: [6, 7, 8, 9, 10] });
+     * df.head(3);  // DataFrame with rows 0-2
+     * ```
+     */
+    head(n?: number): DataFrame;
+    /**
+     * Return the last n rows.
+     *
+     * @param n - Number of rows to return (default: 5)
+     * @returns New DataFrame with last n rows
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [1, 2, 3, 4, 5], b: [6, 7, 8, 9, 10] });
+     * df.tail(3);  // DataFrame with rows 2-4
+     * ```
+     */
+    tail(n?: number): DataFrame;
+    /**
+     * Filter rows based on a boolean predicate function.
+     *
+     * @param predicate - Function that returns true for rows to keep
+     * @returns New DataFrame with filtered rows
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ age: [25, 30, 35], name: ['Alice', 'Bob', 'Carol'] });
+     * const filtered = df.filter(row => row.age > 28);
+     * // DataFrame with Bob and Carol
+     * ```
+     */
+    filter(predicate: (row: Record<string, unknown>) => boolean): DataFrame;
+    /**
+     * Select a subset of columns.
+     *
+     * @param columns - Array of column names to select
+     * @returns New DataFrame with only specified columns
+     * @throws {InvalidParameterError} If any column doesn't exist
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [1, 2], b: [3, 4], c: [5, 6] });
+     * df.select(['a', 'c']);  // DataFrame with only columns a and c
+     * ```
+     */
+    select(columns: string[]): DataFrame;
+    /**
+     * Drop (remove) specified columns.
+     *
+     * @param columns - Array of column names to drop
+     * @returns New DataFrame without the dropped columns
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [1, 2], b: [3, 4], c: [5, 6] });
+     * df.drop(['b']);  // DataFrame with only columns a and c
+     * ```
+     */
+    drop(columns: string[]): DataFrame;
+    /**
+     * Sort DataFrame by one or more columns.
+     *
+     * @param by - Column name or array of column names to sort by
+     * @param ascending - Sort in ascending order (default: true)
+     * @returns New sorted DataFrame
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ age: [30, 25, 35], name: ['Bob', 'Alice', 'Carol'] });
+     * df.sort('age');  // Sorted by age ascending
+     * df.sort(['age'], false);  // Sorted by age descending
+     * ```
+     */
+    sort(by: string | string[], ascending?: boolean): DataFrame;
+    /**
+     * Group DataFrame by one or more columns.
+     *
+     * Returns a DataFrameGroupBy object for performing aggregations.
+     *
+     * @param by - Column name or array of column names to group by
+     * @returns DataFrameGroupBy object for aggregation operations
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({
+     *   category: ['A', 'B', 'A', 'B'],
+     *   value: [10, 20, 30, 40]
+     * });
+     * const grouped = df.groupBy('category');
+     * grouped.sum();  // Sum values by category
+     * ```
+     */
+    groupBy(by: string | string[]): DataFrameGroupBy;
+    /**
+     * Join with another DataFrame using SQL-style join.
+     *
+     * Uses hash join algorithm for O(n + m) time complexity.
+     * Optimized for large datasets with minimal memory overhead.
+     *
+     * @param other - DataFrame to join with
+     * @param on - Column name to join on (must exist in both DataFrames)
+     * @param how - Type of join operation
+     *   - 'inner': Only rows with matching keys in both DataFrames
+     *   - 'left': All rows from left, matched rows from right (nulls for non-matches)
+     *   - 'right': All rows from right, matched rows from left (nulls for non-matches)
+     *   - 'outer': All rows from both DataFrames (nulls for non-matches)
+     * @returns New DataFrame with joined data
+     *
+     * @throws {InvalidParameterError} If join column doesn't exist in either DataFrame
+     *
+     * @example
+     * ```ts
+     * const customers = new DataFrame({
+     *   id: [1, 2, 3],
+     *   name: ['Alice', 'Bob', 'Charlie']
+     * });
+     * const orders = new DataFrame({
+     *   id: [1, 1, 2, 4],
+     *   product: ['Laptop', 'Mouse', 'Keyboard', 'Monitor']
+     * });
+     *
+     * // Inner join - only customers with orders
+     * const inner = customers.join(orders, 'id', 'inner');
+     * // Result: Alice with 2 orders, Bob with 1 order
+     *
+     * // Left join - all customers, with/without orders
+     * const left = customers.join(orders, 'id', 'left');
+     * // Result: Alice, Bob, Charlie (Charlie has null for product)
+     * ```
+     *
+     * @see {@link https://en.wikipedia.org/wiki/Hash_join | Hash Join Algorithm}
+     */
+    join(other: DataFrame, on: string, how?: "inner" | "left" | "right" | "outer"): DataFrame;
+    /**
+     * Merge with another DataFrame using pandas-style merge.
+     *
+     * More flexible than join() - supports different column names for join keys.
+     * Uses hash join algorithm for O(n + m) complexity.
+     *
+     * @param other - DataFrame to merge with
+     * @param options - Merge configuration
+     *   - on: Column name to join on (must exist in both DataFrames)
+     *   - left_on: Column name in left DataFrame
+     *   - right_on: Column name in right DataFrame
+     *   - how: Join type ('inner', 'left', 'right', 'outer')
+     *   - suffixes: Suffix for duplicate column names ['_x', '_y']
+     * @returns New DataFrame with merged data
+     *
+     * @throws {InvalidParameterError} If merge columns don't exist or conflicting options provided
+     *
+     * @example
+     * ```ts
+     * const employees = new DataFrame({
+     *   emp_id: [1, 2, 3],
+     *   name: ['Alice', 'Bob', 'Charlie']
+     * });
+     * const salaries = new DataFrame({
+     *   employee_id: [1, 2, 4],
+     *   salary: [50000, 60000, 55000]
+     * });
+     *
+     * // Merge on different column names
+     * const result = employees.merge(salaries, {
+     *   left_on: 'emp_id',
+     *   right_on: 'employee_id',
+     *   how: 'left'
+     * });
+     * ```
+     *
+     * @see {@link https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.merge.html | Pandas merge}
+     */
+    merge(other: DataFrame, options?: {
+        readonly on?: string;
+        readonly left_on?: string;
+        readonly right_on?: string;
+        readonly how?: "inner" | "left" | "right" | "outer";
+        readonly suffixes?: readonly [string, string];
+    }): DataFrame;
+    /**
+     * Concatenate with another DataFrame.
+     *
+     * @param other - DataFrame to concatenate
+     * @param axis - Axis to concatenate along.
+     *               - 0 or "rows" or "index": Stack vertically (append rows)
+     *               - 1 or "columns": Stack horizontally (append columns)
+     * @returns Concatenated DataFrame
+     *
+     * @example
+     * ```ts
+     * const df1 = new DataFrame({ a: [1, 2], b: [3, 4] });
+     * const df2 = new DataFrame({ a: [5, 6], b: [7, 8] });
+     * df1.concat(df2, "rows");  // Stack vertically: 4 rows
+     * df1.concat(df2, "columns");  // Stack horizontally: 4 columns
+     * ```
+     */
+    concat(other: DataFrame, axis?: Axis): DataFrame;
+    /**
+     * Fill missing values (null or undefined) with a specified value.
+     *
+     * @param value - Value to use for filling missing values
+     * @returns New DataFrame with missing values filled
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [1, null, 3], b: [4, 5, undefined] });
+     * df.fillna(0);  // Replace null/undefined with 0
+     * ```
+     */
+    fillna(value: unknown): DataFrame;
+    /**
+     * Drop rows that contain any missing values (null or undefined).
+     *
+     * @returns New DataFrame with rows containing missing values removed
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [1, null, 3], b: [4, 5, 6] });
+     * df.dropna();  // Only keeps rows 0 and 2
+     * ```
+     */
+    dropna(): DataFrame;
+    /**
+     * Generate descriptive statistics.
+     *
+     * Computes count, mean, std, min, 25%, 50%, 75%, max for numeric columns.
+     *
+     * @returns DataFrame with statistics
+     */
+    describe(): DataFrame;
+    /**
+     * Compute correlation matrix.
+     *
+     * Uses pairwise complete observations (ignores missing values for each pair).
+     *
+     * @returns DataFrame containing pairwise correlations
+     */
+    corr(): DataFrame;
+    /**
+     * Compute covariance matrix.
+     *
+     * Uses pairwise complete observations.
+     *
+     * @returns DataFrame containing pairwise covariances
+     */
+    cov(): DataFrame;
+    /**
+     * Apply a function along an axis of the DataFrame.
+     *
+     * When `axis=1`, the provided Series is indexed by column names.
+     *
+     * @param fn - Function to apply to each Series
+     * @param axis - Axis to apply along (0=columns, 1=rows)
+     * @returns New DataFrame with function applied
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [1, 2, 3], b: [4, 5, 6] });
+     * // Apply function to each column
+     * df.apply(series => series.map(x => Number(x) * 2), 0);
+     * ```
+     */
+    apply<U = unknown>(fn: (series: Series<unknown>) => Series<U>, axis?: Axis): DataFrame;
+    /**
+     * Convert DataFrame to a 2D Tensor.
+     *
+     * All columns must contain numeric data.
+     *
+     * @returns 2D Tensor with shape [rows, columns]
+     * @throws {DataValidationError} If data is non-numeric
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [1, 2, 3], b: [4, 5, 6] });
+     * const t = df.toTensor();  // 2D tensor [[1,4], [2,5], [3,6]]
+     * ```
+     */
+    toTensor(): Tensor;
+    /**
+     * Convert DataFrame to a 2D JavaScript array.
+     *
+     * Each inner array represents a row.
+     *
+     * @returns 2D array of values
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [1, 2], b: [3, 4] });
+     * df.toArray();  // [[1, 3], [2, 4]]
+     * ```
+     */
+    toArray(): unknown[][];
+    /**
+     * Parse CSV string into DataFrame with full type inference and quote handling.
+     * Time complexity: O(n) where n is number of characters.
+     */
+    static fromCsvString(csvString: string, options?: {
+        readonly delimiter?: string;
+        readonly quoteChar?: string;
+        readonly hasHeader?: boolean;
+        readonly skipRows?: number;
+    }): DataFrame;
+    /**
+     * Read CSV file - environment-aware (Node.js fs or browser fetch).
+     * Time complexity: O(n) for file read + O(m) for parsing.
+     */
+    static readCsv(path: string, options?: {
+        readonly delimiter?: string;
+        readonly quoteChar?: string;
+        readonly hasHeader?: boolean;
+        readonly skipRows?: number;
+    }): Promise<DataFrame>;
+    /**
+     * Convert DataFrame to CSV string with proper quoting and escaping.
+     * Time complexity: O(n × m) where n is rows, m is columns.
+     */
+    toCsvString(options?: {
+        readonly delimiter?: string;
+        readonly quoteChar?: string;
+        readonly includeIndex?: boolean;
+        readonly header?: boolean;
+    }): string;
+    /**
+     * Write DataFrame to CSV file - environment-aware.
+     * Time complexity: O(n × m) for generation + O(k) for write.
+     */
+    toCsv(path: string, options?: {
+        readonly delimiter?: string;
+        readonly quoteChar?: string;
+        readonly includeIndex?: boolean;
+        readonly header?: boolean;
+    }): Promise<void>;
+    /**
+     * Serialize DataFrame to JSON string.
+     * Time complexity: O(n × m).
+     */
+    toJsonString(): string;
+    /**
+     * Create DataFrame from JSON string.
+     * Time complexity: O(n × m).
+     */
+    static fromJsonString(jsonStr: string): DataFrame;
+    /**
+     * Read JSON file - environment-aware.
+     * Time complexity: O(n) for file read + O(m) for parsing.
+     */
+    static readJson(path: string): Promise<DataFrame>;
+    /**
+     * Write DataFrame to JSON file - environment-aware.
+     * Time complexity: O(n × m) for generation + O(k) for write.
+     */
+    toJson(path: string): Promise<void>;
+    /**
+     * Create DataFrame from a Tensor.
+     *
+     * @param tensor - Tensor to convert (must be 1D or 2D)
+     * @param columns - Column names (optional). If provided, length must match tensor columns.
+     * @returns DataFrame
+     *
+     * @example
+     * ```ts
+     * import { tensor } from 'deepbox/ndarray';
+     *
+     * const t = tensor([[1, 2], [3, 4], [5, 6]]);
+     * const df = DataFrame.fromTensor(t, ['col1', 'col2']);
+     * ```
+     */
+    static fromTensor(tensor: Tensor, columns?: string[]): DataFrame;
+    /**
+     * Remove duplicate rows from DataFrame.
+     * Time complexity: O(n × m) where n is rows, m is columns.
+     *
+     * @param subset - Columns to consider for identifying duplicates (default: all columns)
+     * @param keep - Which duplicates to keep: 'first', 'last', or false (remove all)
+     * @returns New DataFrame with duplicates removed
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [1, 1, 2], b: [3, 3, 4] });
+     * df.drop_duplicates();  // Keeps first occurrence: [[1, 3], [2, 4]]
+     * df.drop_duplicates(undefined, 'last');  // Keeps last occurrence
+     * ```
+     */
+    drop_duplicates(subset?: string[], keep?: "first" | "last" | false): DataFrame;
+    /**
+     * Return boolean Series indicating duplicate rows.
+     * Time complexity: O(n × m).
+     *
+     * @param subset - Columns to consider for identifying duplicates
+     * @param keep - Which duplicates to mark as False: 'first', 'last', or false (mark all)
+     * @returns Series of booleans (true = duplicate, false = unique)
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [1, 1, 2], b: [3, 3, 4] });
+     * df.duplicated();  // Series([false, true, false])
+     * ```
+     */
+    duplicated(subset?: string[], keep?: "first" | "last" | false): Series<boolean>;
+    /**
+     * Rename columns or index labels.
+     * Time complexity: O(m) for columns, O(n) for index.
+     *
+     * @param mapper - Object mapping old names to new names, or function to transform names
+     * @param axis - 0 for index, 1 for columns
+     * @returns New DataFrame with renamed labels
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [1, 2], b: [3, 4] });
+     * df.rename({ a: 'x', b: 'y' }, 1);  // Rename columns a->x, b->y
+     * df.rename((name) => name.toUpperCase(), 1);  // Uppercase all column names
+     * ```
+     */
+    rename(mapper: Record<string, string> | ((name: string) => string), axis?: 0 | 1): DataFrame;
+    /**
+     * Reset index to default integer index.
+     * Time complexity: O(n).
+     *
+     * @param drop - If true, don't add old index as column.
+     *              If a column named "index" already exists, the new column will be
+     *              named "index_1", "index_2", etc.
+     * @returns New DataFrame with reset index
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [1, 2] }, { index: ['x', 'y'] });
+     * df.reset_index();  // Index becomes [0, 1], adds 'index' column with ['x', 'y']
+     * df.reset_index(true);  // Index becomes [0, 1], no new column
+     * ```
+     */
+    reset_index(drop?: boolean): DataFrame;
+    /**
+     * Set a column as the index.
+     * Time complexity: O(n).
+     *
+     * @param column - Column name to use as index
+     * @param drop - If true, remove the column after setting it as index
+     * @returns New DataFrame with new index
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ id: ['a', 'b', 'c'], value: [1, 2, 3] });
+     * df.set_index('id');  // Index becomes ['a', 'b', 'c']
+     * ```
+     */
+    set_index(column: string, drop?: boolean): DataFrame;
+    /**
+     * Return boolean DataFrame showing null values.
+     * Time complexity: O(n × m).
+     *
+     * @returns DataFrame of booleans (true = null/undefined, false = not null)
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [1, null, 3], b: [4, 5, undefined] });
+     * df.isnull();  // [[false, false], [true, false], [false, true]]
+     * ```
+     */
+    isnull(): DataFrame;
+    /**
+     * Return boolean DataFrame showing non-null values.
+     * Time complexity: O(n × m).
+     *
+     * @returns DataFrame of booleans (true = not null, false = null/undefined)
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [1, null, 3], b: [4, 5, undefined] });
+     * df.notnull();  // [[true, true], [false, true], [true, false]]
+     * ```
+     */
+    notnull(): DataFrame;
+    /**
+     * Replace values in DataFrame.
+     * Time complexity: O(n × m).
+     *
+     * @param toReplace - Value or array of values to replace
+     * @param value - Replacement value
+     * @returns New DataFrame with replaced values
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [1, 2, 3], b: [4, 5, 6] });
+     * df.replace(2, 99);  // Replace all 2s with 99
+     * df.replace([1, 2], 0);  // Replace 1s and 2s with 0
+     * ```
+     */
+    replace(toReplace: unknown | unknown[], value: unknown): DataFrame;
+    /**
+     * Clip (limit) values in a range.
+     * Time complexity: O(n × m).
+     *
+     * @param lower - Minimum value (values below are set to this)
+     * @param upper - Maximum value (values above are set to this)
+     * @returns New DataFrame with clipped values
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [1, 5, 10], b: [2, 8, 15] });
+     * df.clip(3, 9);  // [[3, 3], [5, 8], [9, 9]]
+     * ```
+     */
+    clip(lower?: number, upper?: number): DataFrame;
+    /**
+     * Return a random sample of rows.
+     * Time complexity: O(n) for sampling.
+     *
+     * @param n - Number of rows to sample
+     * @param random_state - Random seed for reproducibility
+     * @returns New DataFrame with sampled rows
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [1, 2, 3, 4, 5], b: [6, 7, 8, 9, 10] });
+     * df.sample(3);  // Random 3 rows
+     * ```
+     */
+    sample(n: number, random_state?: number): DataFrame;
+    /**
+     * Seeded random number generator for reproducibility.
+     * @private
+     */
+    private seededRandom;
+    /**
+     * Return values at the given quantile.
+     * Time complexity: O(n log n) per column due to sorting.
+     *
+     * @param q - Quantile to compute (0 to 1)
+     * @returns Series with quantile values for each numeric column
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [1, 2, 3, 4, 5], b: [10, 20, 30, 40, 50] });
+     * df.quantile(0.5);  // Median: Series({ a: 3, b: 30 })
+     * df.quantile(0.25);  // 25th percentile
+     * ```
+     */
+    quantile(q: number): Series<number>;
+    /**
+     * Compute numerical rank of values (1 through n) along axis.
+     * Time complexity: O(n log n) per column.
+     *
+     * @param method - How to rank ties: 'average', 'min', 'max', 'first', 'dense'
+     * @param ascending - Rank in ascending order
+     * @returns New DataFrame with ranks
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [3, 1, 2, 1] });
+     * df.rank();  // [[4], [1.5], [3], [1.5]] (average method)
+     * df.rank('min');  // [[4], [1], [3], [1]]
+     * ```
+     */
+    rank(method?: "average" | "min" | "max" | "first" | "dense", ascending?: boolean): DataFrame;
+    /**
+     * Calculate the difference between consecutive rows.
+     * Time complexity: O(n × m).
+     *
+     * @param periods - Number of periods to shift (default: 1)
+     * @returns New DataFrame with differences
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [1, 3, 6, 10] });
+     * df.diff();  // [[null], [2], [3], [4]]
+     * df.diff(2);  // [[null], [null], [5], [7]]
+     * ```
+     */
+    diff(periods?: number): DataFrame;
+    /**
+     * Calculate percentage change between consecutive rows.
+     * Time complexity: O(n × m).
+     *
+     * @param periods - Number of periods to shift (default: 1)
+     * @returns New DataFrame with percentage changes
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [100, 110, 121] });
+     * df.pct_change();  // [[null], [0.1], [0.1]] (10% increase each time)
+     * ```
+     */
+    pct_change(periods?: number): DataFrame;
+    /**
+     * Return cumulative sum over DataFrame axis.
+     * Time complexity: O(n × m).
+     *
+     * @returns New DataFrame with cumulative sums
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [1, 2, 3], b: [4, 5, 6] });
+     * df.cumsum();  // [[1, 4], [3, 9], [6, 15]]
+     * ```
+     */
+    cumsum(): DataFrame;
+    /**
+     * Return cumulative product over DataFrame axis.
+     * Time complexity: O(n × m).
+     *
+     * @returns New DataFrame with cumulative products
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [2, 3, 4] });
+     * df.cumprod();  // [[2], [6], [24]]
+     * ```
+     */
+    cumprod(): DataFrame;
+    /**
+     * Return cumulative maximum over DataFrame axis.
+     * Time complexity: O(n × m).
+     *
+     * @returns New DataFrame with cumulative maximums
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [3, 1, 5, 2] });
+     * df.cummax();  // [[3], [3], [5], [5]]
+     * ```
+     */
+    cummax(): DataFrame;
+    /**
+     * Return cumulative minimum over DataFrame axis.
+     * Time complexity: O(n × m).
+     *
+     * @returns New DataFrame with cumulative minimums
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [3, 1, 5, 2] });
+     * df.cummin();  // [[3], [1], [1], [1]]
+     * ```
+     */
+    cummin(): DataFrame;
+    /**
+     * Shift index by desired number of periods.
+     * Time complexity: O(n × m).
+     *
+     * @param periods - Number of periods to shift (positive = down, negative = up)
+     * @param fill_value - Value to use for newly introduced missing values
+     * @returns New DataFrame with shifted data
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [1, 2, 3, 4] });
+     * df.shift(1);  // [[null], [1], [2], [3]]
+     * df.shift(-1);  // [[2], [3], [4], [null]]
+     * df.shift(1, 0);  // [[0], [1], [2], [3]]
+     * ```
+     */
+    shift(periods?: number, fill_value?: unknown): DataFrame;
+    /**
+     * Pivot DataFrame.
+     * Time complexity: O(n × m).
+     *
+     * @param index - Column to use as index
+     * @param columns - Column to use as column headers
+     * @param values - Column to use as values
+     * @returns New DataFrame with pivoted data
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({
+     *   country: ['USA', 'USA', 'Canada', 'Canada'],
+     *   year: [2010, 2011, 2010, 2011],
+     *   value: [100, 200, 300, 400]
+     * });
+     * df.pivot('country', 'year', 'value');
+     * // country | 2010 | 2011
+     * //   USA   | 100  | 200
+     * //  Canada | 300  | 400
+     * ```
+     */
+    pivot(index: string, columns: string, values: string): DataFrame;
+    /**
+     * Melt DataFrame.
+     * Time complexity: O(n × m).
+     *
+     * @param id_vars - Columns to keep as is
+     * @param value_vars - Columns to melt
+     * @param var_name - Name for new column with melted variable names
+     * @param value_name - Name for new column with melted values.
+     *                    Must not conflict with existing columns or var_name.
+     * @returns New DataFrame with melted data
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({
+     *   id: ['a', 'b'],
+     *   x: [1, 2],
+     *   y: [3, 4]
+     * });
+     * df.melt(['id'], ['x', 'y'], 'variable', 'value');
+     * // id | variable | value
+     * //  a |       x |     1
+     * //  a |       y |     3
+     * //  b |       x |     2
+     * //  b |       y |     4
+     * ```
+     */
+    melt(id_vars: string[], value_vars: string[], var_name?: string, value_name?: string): DataFrame;
+    /**
+     * Rolling window mean calculation.
+     *
+     * @param window - Size of the rolling window
+     * @param on - Column to apply rolling calculation to (if omitted, applies to all columns)
+     * @returns New DataFrame with rolling mean values
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [1, 2, 3, 4, 5] });
+     * df.rolling(3);  // [[null], [null], [2], [3], [4]]
+     * ```
+     */
+    rolling(window: number, on?: string): DataFrame;
+    /**
+     * Return a human-readable tabular string representation.
+     *
+     * Columns are right-aligned and padded so that rows line up.
+     * Large DataFrames are truncated with an ellipsis row.
+     *
+     * @param maxRows - Maximum rows to display before summarizing (default: 20).
+     * @returns Formatted table string
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({ a: [1, 2], b: [3, 4] });
+     * df.toString();
+     * // "  a  b\n0 1  3\n1 2  4"
+     * ```
+     */
+    toString(maxRows?: number): string;
+}
+/**
+ * GroupBy object for aggregation operations.
+ *
+ * Created by DataFrame.groupBy(). Used to perform aggregations on grouped data.
+ *
+ * @example
+ * ```ts
+ * const df = new DataFrame({
+ *   category: ['A', 'B', 'A', 'B'],
+ *   value: [10, 20, 30, 40]
+ * });
+ * const grouped = df.groupBy('category');
+ * grouped.sum();   // Sum by category
+ * grouped.mean();  // Mean by category
+ * ```
+ */
+declare class DataFrameGroupBy {
+    private groupMap;
+    private keyValuesMap;
+    private df;
+    private by;
+    constructor(df: DataFrame, by: string | string[]);
+    /**
+     * Build the grouping map: group key -> array of row indices.
+     *
+     * @private
+     */
+    private buildGroupMap;
+    /**
+     * Aggregate grouped data.
+     *
+     * @param operations - Dictionary of column name to aggregation function
+     * @returns New DataFrame with aggregated data
+     *
+     * @example
+     * ```ts
+     * const grouped = df.groupBy('category');
+     * const result = grouped.agg({ value: 'sum', count: 'count' });
+     * ```
+     */
+    agg(operations: Record<string, AggregateFunction | AggregateFunction[]>): DataFrame;
+    /**
+     * Helper to identify numeric columns (excluding grouping columns).
+     * @private
+     */
+    private getNumericColumns;
+    /**
+     * Helper method to perform same aggregation on all numeric non-grouping columns.
+     * @private
+     */
+    private aggNumeric;
+    /**
+     * Helper method to perform same aggregation on all non-grouping columns.
+     *
+     * @private
+     */
+    private aggAll;
+    /**
+     * Compute sum for each group.
+     *
+     * @returns DataFrame with summed values by group
+     *
+     * @example
+     * ```ts
+     * const df = new DataFrame({
+     *   category: ['A', 'A', 'B', 'B'],
+     *   value: [1, 2, 3, 4]
+     * });
+     * df.groupBy('category').sum();
+     * // category | value
+     * //    A     |   3
+     * //    B     |   7
+     * ```
+     */
+    sum(): DataFrame;
+    /**
+     * Compute mean (average) for each group.
+     *
+     * @returns DataFrame with mean values by group
+     */
+    mean(): DataFrame;
+    /**
+     * Count non-null values in each non-grouping column for every group.
+     *
+     * @returns DataFrame with per-column non-null counts by group
+     */
+    count(): DataFrame;
+    /**
+     * Compute minimum value for each group.
+     *
+     * @returns DataFrame with minimum values by group
+     */
+    min(): DataFrame;
+    /**
+     * Compute maximum value for each group.
+     *
+     * @returns DataFrame with maximum values by group
+     */
+    max(): DataFrame;
+    /**
+     * Compute standard deviation for each group.
+     *
+     * @returns DataFrame with standard deviation values by group
+     */
+    std(): DataFrame;
+    /**
+     * Compute variance for each group.
+     *
+     * @returns DataFrame with variance values by group
+     */
+    var(): DataFrame;
+    /**
+     * Compute median for each group.
+     *
+     * @returns DataFrame with median values by group
+     */
+    median(): DataFrame;
+}
+
+type index_AggregateFunction = AggregateFunction;
+type index_DataFrame = DataFrame;
+declare const index_DataFrame: typeof DataFrame;
+type index_DataFrameData = DataFrameData;
+type index_DataFrameGroupBy = DataFrameGroupBy;
+declare const index_DataFrameGroupBy: typeof DataFrameGroupBy;
+type index_DataFrameOptions = DataFrameOptions;
+type index_Series<T = unknown> = Series<T>;
+declare const index_Series: typeof Series;
+type index_SeriesOptions = SeriesOptions;
+declare namespace index {
+  export { type index_AggregateFunction as AggregateFunction, index_DataFrame as DataFrame, type index_DataFrameData as DataFrameData, index_DataFrameGroupBy as DataFrameGroupBy, type index_DataFrameOptions as DataFrameOptions, index_Series as Series, type index_SeriesOptions as SeriesOptions };
+}
+
+export { type AggregateFunction as A, DataFrame as D, Series as S, DataFrameGroupBy as a, type DataFrameData as b, type DataFrameOptions as c, type SeriesOptions as d, index as i };