Class: GroupedFrame¶

A grouped view of a BareFrame, produced by BareFrame.groupBy.

Remarks¶

Internally, GroupedFrame holds a reference to the source BareFrame and a map of composite key strings to row index arrays — no data is copied. Each unique combination of key-column values forms one group, in the order of first appearance. All aggregation methods return a new flat BareFrame whose columns start with the group-key columns, followed by the result column(s). Do not construct this class directly — use BareFrame.groupBy instead.

Example¶

TypeScript

const df = BareFrame.fromColumns({
  dept:  ["eng", "eng", "hr"],
  score: [80, 90, 70],
});

const grouped = df.groupBy(["dept"]);

grouped.count();
// dept | count
// eng  | 2
// hr   | 1

grouped.first();
// dept | score
// eng  | 80
// hr   | 70

grouped.agg({
  score: (vals) => (vals as number[]).reduce((a, b) => a + b, 0),
});
// dept | score
// eng  | 170
// hr   | 70

DataFrame¶

count()¶

count(): BareFrame

Returns the number of rows in each group.

Returns¶

BareFrame

New BareFrame with group-key columns + count

Remarks¶

The result always starts with the group-key columns, followed by a count column containing the row count for that group.

Example¶

TypeScript

const df = BareFrame.fromColumns({
  dept:  ["eng", "eng", "hr"],
  score: [80, 90, 70],
});
df.groupBy(["dept"]).count();
// dept | count
// eng  | 2
// hr   | 1

first()¶

first(): BareFrame

Returns the first row of each group.

Returns¶

BareFrame

New BareFrame with one row per group (first occurrence)

Remarks¶

The result preserves all columns from the original BareFrame. Row order follows the order in which each group first appeared.

Example¶

TypeScript

const df = BareFrame.fromColumns({
  dept:  ["eng", "eng", "hr"],
  score: [80, 90, 70],
});
df.groupBy(["dept"]).first();
// dept | score
// eng  | 80
// hr   | 70

last()¶

last(): BareFrame

Returns the last row of each group.

Returns¶

BareFrame

New BareFrame with one row per group (last occurrence)

Remarks¶

The result preserves all columns from the original BareFrame. Row order follows the order in which each group first appeared.

Example¶

TypeScript

const df = BareFrame.fromColumns({
  dept:  ["eng", "eng", "hr"],
  score: [80, 90, 70],
});
df.groupBy(["dept"]).last();
// dept | score
// eng  | 90
// hr   | 70

agg()¶

agg(spec, options?): BareFrame

Aggregates each group using caller-supplied functions.

Parameters¶

spec¶

Record\<string, AggFn>

Plain object mapping column name to aggregation function

options?¶

RollingOptions

Rolling window options. If omitted, computes agg per group.

Returns¶

BareFrame

New BareFrame with group-key columns + aggregated columns

Remarks¶

Each key in spec is a column name; the corresponding AggFn receives all Cell values in that column for a single group and must return one summary Cell. Group-key columns are always prepended to the result before the aggregated columns, in the order they appear in spec.

When options.window is specified, computes rolling aggregation within each group. The result preserves all original rows; each row contains the aggregation result for the rolling window ending at that row.

Throws¶

Error when any column name in spec does not exist

Example¶

Basic usage — aggregate each group:

TypeScript

const df = BareFrame.fromColumns({
  dept:  ["eng", "eng", "hr"],
  score: [80, 90, 70],
});

const sum: AggFn = (vals) =>
  (vals as number[]).reduce((a, b) => a + b, 0);

df.groupBy(["dept"]).agg({ score: sum });
// dept | score
// eng  | 170
// hr   | 70

sum()¶

sum(headers, options?): BareFrame

Returns the sum of each specified column per group.

Parameters¶

headers¶

string[]

One or more column names to sum

options?¶

RollingOptions

Rolling window options. If omitted, computes sum per group.

Returns¶

BareFrame

New BareFrame with group-key columns followed by the summed columns

Remarks¶

Non-numeric cells (strings, nulls, booleans) are silently excluded. If a group contains no numeric values at all, the result is null rather than 0, so a genuine zero-sum can be distinguished from missing data.

When options.window is specified, computes rolling sum within each group. The result preserves all original rows; rows at the start of each group (before the window is full) contain the sum of available values.

Delegates internally to GroupedFrame.agg.

Throws¶

Error when any name in headers does not match an existing column

Examples¶

Basic usage — sum a single column per group:

TypeScript

const df = BareFrame.fromColumns({
  dept:  ["eng", "eng", "hr"],
  score: [80, 90, 70],
});
const result = df.groupBy(["dept"]).sum(["score"]);
// dept | score
// eng  | 170
// hr   | 70

Rolling sum with window 2:

TypeScript

const df = BareFrame.fromColumns({
  dept:  ["eng", "eng", "eng"],
  sales: [10, 20, 30],
});
df.groupBy(["dept"]).sum(["sales"], { window: 2 });
// dept | sales
// eng  | 10
// eng  | 30
// eng  | 50

mean()¶

mean(headers, options?): BareFrame

Returns the arithmetic mean of each specified column per group.

Parameters¶

headers¶

string[]

One or more column names to average

options?¶

RollingOptions

Rolling window options. If omitted, computes mean per group.

Returns¶

BareFrame

New BareFrame with group-key columns followed by the mean columns

Remarks¶

Non-numeric cells (strings, nulls, booleans) are silently excluded before computing the average. If a group contains no numeric values at all, the result is null.

When options.window is specified, computes rolling mean within each group.

Delegates internally to GroupedFrame.agg.

Throws¶

Error when any name in headers does not match an existing column

Example¶

Basic usage — average a single column per group:

TypeScript

const df = BareFrame.fromColumns({
  dept:  ["eng", "eng", "hr"],
  score: [80, 90, 70],
});
const result = df.groupBy(["dept"]).mean(["score"]);
// dept | score
// eng  | 85
// hr   | 70

min()¶

min(headers, options?): BareFrame

Returns the minimum numeric value of each specified column per group.

Parameters¶

headers¶

string[]

One or more column names to find the minimum of

options?¶

RollingOptions

Returns¶

BareFrame

New BareFrame with group-key columns followed by the min columns

Remarks¶

Non-numeric cells (strings, nulls, booleans) are silently excluded from the comparison. If a group contains no numeric values at all, the result is null.

Delegates internally to GroupedFrame.agg.

Throws¶

Error when any name in headers does not match an existing column

Examples¶

Basic usage — find the minimum of a single column:

TypeScript

const df = BareFrame.fromColumns({
  dept:  ["eng", "eng", "hr"],
  score: [80, 90, 70],
});
const result = df.groupBy(["dept"]).min(["score"]);
// dept | score
// eng  | 80
// hr   | 70

Mixed data — non-numeric cells are excluded:

TypeScript

const df = BareFrame.fromColumns({
  dept:  ["eng", "eng"],
  score: [90, "n/a"],  // "n/a" is excluded
});
df.groupBy(["dept"]).min(["score"]);
// dept | score
// eng  | 90

Error — column does not exist:

TypeScript

df.groupBy(["dept"]).min(["missing"]); // throws Error: column "missing" does not exist

max()¶

max(headers, options?): BareFrame

Returns the maximum numeric value of each specified column per group.

Parameters¶

headers¶

string[]

One or more column names to find the maximum of

options?¶

RollingOptions

Returns¶

BareFrame

New BareFrame with group-key columns followed by the max columns

Remarks¶

Non-numeric cells (strings, nulls, booleans) are silently excluded from the comparison. If a group contains no numeric values at all, the result is null.

Delegates internally to GroupedFrame.agg.

Throws¶

Error when any name in headers does not match an existing column

Examples¶

Basic usage — find the maximum of a single column:

TypeScript

const df = BareFrame.fromColumns({
  dept:  ["eng", "eng", "hr"],
  score: [80, 90, 70],
});
const result = df.groupBy(["dept"]).max(["score"]);
// dept | score
// eng  | 90
// hr   | 70

Mixed data — non-numeric cells are excluded:

TypeScript

const df = BareFrame.fromColumns({
  dept:  ["eng", "eng"],
  score: [80, "n/a"],  // "n/a" is excluded
});
df.groupBy(["dept"]).max(["score"]);
// dept | score
// eng  | 80

Error — column does not exist:

TypeScript

df.groupBy(["dept"]).max(["missing"]); // throws Error: column "missing" does not exist

cumsum()¶

cumsum(header): BareFrame

Returns a new BareFrame with cumulative sum applied to each group.

Parameters¶

string

Column name to compute cumulative sum for

Returns¶

BareFrame

New BareFrame with cumsum applied, preserving row order

Remarks¶

Computes the running sum within each group. Non-numeric values (strings, nulls, booleans) are skipped (treated as 0 in the cumulative total). The result preserves all original columns; the specified column contains cumulative values instead of original values.

Throws¶

Error when the column does not exist

Example¶

TypeScript

const df = BareFrame.fromColumns({
  dept:   ["eng", "eng", "eng", "hr", "hr"],
  sales:  [10, 20, 30, 5, 15],
});
df.groupBy(["dept"]).cumsum("sales");
// dept | sales
// eng  | 10
// eng  | 30
// eng  | 60
// hr   | 5
// hr   | 20

cumprod()¶

cumprod(header): BareFrame

Returns a new BareFrame with cumulative product applied to each group.

Parameters¶

header¶

string

Column name to compute cumulative product for

Returns¶

BareFrame

New BareFrame with cumprod applied, preserving row order

Remarks¶

Computes the running product within each group. Non-numeric values (strings, nulls, booleans) are skipped (treated as 1 in the cumulative product). The result preserves all original columns; the specified column contains cumulative values instead of original values.

Throws¶

Error when the column does not exist

Example¶

TypeScript

const df = BareFrame.fromColumns({
  dept:   ["eng", "eng", "eng", "hr", "hr"],
  factor: [2, 3, 4, 5, 2],
});
df.groupBy(["dept"]).cumprod("factor");
// dept | factor
// eng  | 2
// eng  | 6
// eng  | 24
// hr   | 5
// hr   | 10

cummax()¶

cummax(header): BareFrame

Returns a new BareFrame with cumulative maximum applied to each group.

Parameters¶

header¶

string

Column name to compute cumulative maximum for

Returns¶

BareFrame

New BareFrame with cummax applied, preserving row order

Remarks¶

Computes the running maximum within each group. Non-numeric values (strings, nulls, booleans) are skipped; the running max is compared only against numeric values. The result preserves all original columns; the specified column contains cumulative max values instead of original values.

Throws¶

Error when the column does not exist

Example¶

TypeScript

const df = BareFrame.fromColumns({
  dept:    ["eng", "eng", "eng", "hr", "hr"],
  revenue: [100, 50, 150, 80, 120],
});
df.groupBy(["dept"]).cummax("revenue");
// dept | revenue
// eng  | 100
// eng  | 100
// eng  | 150
// hr   | 80
// hr   | 120

cummin()¶

cummin(header): BareFrame

Returns a new BareFrame with cumulative minimum applied to each group.

Parameters¶

header¶

string

Column name to compute cumulative minimum for

Returns¶

BareFrame

New BareFrame with cummin applied, preserving row order

Remarks¶

Computes the running minimum within each group. Non-numeric values (strings, nulls, booleans) are skipped; the running min is compared only against numeric values. The result preserves all original columns; the specified column contains cumulative min values instead of original values.

Throws¶

Error when the column does not exist

Example¶

TypeScript

const df = BareFrame.fromColumns({
  dept:    ["eng", "eng", "eng", "hr", "hr"],
  latency: [50, 100, 30, 120, 80],
});
df.groupBy(["dept"]).cummin("latency");
// dept | latency
// eng  | 50
// eng  | 50
// eng  | 30
// hr   | 120
// hr   | 80

shift()¶

shift(header, offset?): BareFrame

Returns a new BareFrame with shifted values applied to each group.

Parameters¶

header¶

string

Column name to shift

offset?¶

number = 1

Number of positions to shift. Positive = forward (default: 1), negative = backward. Default: 1.

Returns¶

BareFrame

New BareFrame with shifted column, preserving row order

Remarks¶

Shifts column values within each group by the specified offset. Positive offset shifts forward (previous rows move down); negative offset shifts backward (next rows move up). Rows at the boundary of each group that fall outside the valid range are filled with null.

Throws¶

Error when the column does not exist

Examples¶

Basic usage — shift forward by 1 (default, get previous row's value):

TypeScript

const df = BareFrame.fromColumns({
  dept:  ["eng", "eng", "eng", "hr", "hr"],
  value: [10, 20, 30, 5, 15],
});
df.groupBy(["dept"]).shift("value");
// dept | value
// eng  | null
// eng  | 10
// eng  | 20
// hr   | null
// hr   | 5

Shift backward by 1 (get next row's value):

TypeScript

df.groupBy(["dept"]).shift("value", -1);
// dept | value
// eng  | 20
// eng  | 30
// eng  | null
// hr   | 15
// hr   | null

Shift forward by 2:

TypeScript

df.groupBy(["dept"]).shift("value", 2);
// dept | value
// eng  | null
// eng  | null
// eng  | 10
// hr   | null
// hr   | null