Pandas Window TDS Frame

Represents a window specification over a base frame.

Created by expanding(), rolling(), or window_frame_legend_ext() on a PandasApiTdsFrame or a PandasApiGroupbyTdsFrame. Calling an aggregate (e.g. .aggregate('sum')) on this object produces a new TDS frame whose columns contain the windowed values. The first(), last(), and window_extend_legend_ext() methods are also available for positional and custom window operations. Alternatively, use bracket notation to select a single column first and obtain a WindowSeries.

Obtaining a PandasApiWindowTdsFrame

# Expanding (cumulative) window — all rows up to current row
window = frame.expanding(order_by="col")

# Fixed-size sliding window — 5 preceding rows to current row
window = frame.rolling(5, order_by="col")

# Custom window bounds (pylegend extension)
window = frame.window_frame_legend_ext(
    frame_spec=frame.rows_between(-3, 3),
    order_by="col",
)

# No frame clause — only PARTITION BY / ORDER BY
window = frame.window_frame_legend_ext(
    frame_spec=None,
    order_by="col",
)

When created from a groupby, the grouping columns are automatically used as PARTITION BY in the generated SQL:

window = frame.groupby("grp").expanding(order_by="val")
# SQL: ... PARTITION BY "grp", ... ORDER BY "val" ...

Selecting a single column

Use bracket notation to narrow to one column before aggregating. This returns a WindowSeries whose aggregate result can be assigned back to the parent frame:

frame["cumsum"] = frame.expanding(order_by="col")["col"].sum()

Order-by resolution

If no order_by is supplied when creating the window, the first column of the base frame is used as a fallback. Providing an explicit order_by is recommended for deterministic results.

param base_frame:: The underlying frame or groupby frame.
param order_by:: Column name(s) to use for ORDER BY within the window. None means no explicit ordering (the first column of the base frame is used as a fallback).
type order_by:: str, list of str, or None
param frame_spec:: A FrameSpec describing the window frame bounds. Defaults to RowsBetween(None, None) (i.e. ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING). Pass None to omit the frame clause entirely, producing a window with only PARTITION BY / ORDER BY. This is required for functions like shift() (lag/lead) which do not accept a frame clause.
type frame_spec:: RowsBetween, RangeBetween, or None
param ascending:: Sort direction(s) for the ORDER BY columns. True means ascending. Can be a single bool (applied to all columns) or a list[bool] whose length must match the number of order_by columns.
type ascending:: bool or list of bool, default True

See also

PandasApiTdsFrame.expanding: Create an expanding window.
PandasApiTdsFrame.rolling: Create a rolling window.
PandasApiTdsFrame.window_frame_legend_ext: Create a custom window.
WindowSeries: Single-column proxy on a window frame.
first: First value in the window for every column.
last: Last value in the window for every column.
window_extend_legend_ext: Custom single-column window function.

Notes

Differences from pandas:

In pandas, Expanding and Rolling objects have built-in convenience methods (sum(), mean(), etc.) that return a DataFrame. Here, the window frame object exposes only aggregate() / agg() for multi-column use. For single-column convenience methods (sum(), mean(), etc.), use bracket notation to get a WindowSeries first.
When created from a groupby, the grouping columns are excluded from the result columns (only the aggregated value columns appear).
The order_by parameter is a pylegend extension. In pandas, window ordering relies on the implicit order of the DataFrame index.
Extra *args / **kwargs on aggregate() are not supported.

Examples

Download Interactive Notebook

agg

PandasApiWindowTdsFrame.agg(func, axis=0, *args, **kwargs)[source]

Apply a window aggregate function across all non-grouping columns.

Alias for aggregate(). See aggregate for full documentation.

See also

aggregate: Equivalent method (canonical name).

Return type:: PandasApiBaseTdsFrame

aggregate

PandasApiWindowTdsFrame.aggregate(func, axis=0, *args, **kwargs)[source]

Apply a window aggregate function across all non-grouping columns.

Compute the window aggregate specified by func over the window defined by this PandasApiWindowTdsFrame. The result is a new TDS frame whose columns contain the windowed values.

Parameters:

func (Union[Callable[..., Union[int, float, str, bool, date, datetime, Decimal, PyLegendPrimitive]], str, ufunc, List[Union[Callable[..., Union[int, float, str, bool, date, datetime, Decimal, PyLegendPrimitive]], str, ufunc]], Mapping[Hashable, Union[Callable[..., Union[int, float, str, bool, date, datetime, Decimal, PyLegendPrimitive]], str, ufunc, List[Union[Callable[..., Union[int, float, str, bool, date, datetime, Decimal, PyLegendPrimitive]], str, ufunc]]]]]) –
Aggregation specification. Accepted forms:
- str — a named aggregation (e.g. 'sum', 'mean', 'min', 'max', 'count', 'std', 'var').
- callable — a function receiving a column proxy and returning an aggregated value.
- list — a list of the above.
- dict — a mapping of column name → aggregation(s).
axis (Union[int, str]) – Only 0 / 'index' is supported.
*args (Union[int, float, str, bool, date, datetime, Decimal, PyLegendPrimitive]) – Not supported.
**kwargs (Union[int, float, str, bool, date, datetime, Decimal, PyLegendPrimitive]) – Not supported.

Returns:

A new TDS frame with the windowed aggregate values.

Return type:

PandasApiBaseTdsFrame

See also

agg: Alias for aggregate.
PandasApiTdsFrame.aggregate: Frame-level aggregation (no window).
PandasApiGroupbyTdsFrame.aggregate: Grouped aggregation.

Notes

Differences from pandas:

In pandas, Expanding.aggregate() and Rolling.aggregate() accept *args and **kwargs forwarded to the aggregation function. Here, extra positional and keyword arguments are not supported.
The result is a full TDS frame (all non-grouping columns are aggregated), not a single column. Use bracket notation on the window frame to select a single column before aggregating (returns a WindowSeries).

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

# Expanding sum over all numeric columns
frame.filter(
    items=["Order Id"]
).expanding(order_by="Order Id").aggregate("sum").head(5).to_pandas()

	Order Id
0	10248
1	20497
2	30747
3	40998
4	51250

# Rolling mean with a window of 3
frame.filter(
    items=["Order Id"]
).rolling(3, order_by="Order Id").aggregate("mean").head(5).to_pandas()

	Order Id
0	10248.0
1	10248.5
2	10249.0
3	10250.0
4	10251.0

first

PandasApiWindowTdsFrame.first(numeric_only=False)[source]

Return the first value in the window for every column.

Generates first_value(col) OVER (...) for each column.

Parameters:: numeric_only (bool) – If True, apply first_value only to numeric columns and retain grouping columns. Non-numeric, non-grouping columns are dropped from the result.
Returns:: A new frame whose columns contain the first value within the window.
Return type:: PandasApiTdsFrame

See also

last: Last value in the window.
WindowSeries.first: Single-column version.

Notes

Differences from pandas:

first() is a pylegend extension. In pandas, there is no Expanding.first() or Rolling.first().
When numeric_only=True, the implementation applies first() per numeric column individually, then filters.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

# First Order Id across the entire sorted window
frame.filter(items=["Order Id"]).window_frame_legend_ext(
    frame_spec=frame.rows_between(),
    order_by="Order Id",
).first().head(5).to_pandas()

	Order Id
0	10248
1	10248
2	10248
3	10248
4	10248

last

PandasApiWindowTdsFrame.last(numeric_only=False)[source]

Return the last value in the window for every column.

Generates last_value(col) OVER (...) for each column.

Parameters:: numeric_only (bool) – If True, apply last_value only to numeric columns and retain grouping columns. Non-numeric, non-grouping columns are dropped from the result.
Returns:: A new frame whose columns contain the last value within the window.
Return type:: PandasApiTdsFrame

See also

first: First value in the window.
WindowSeries.last: Single-column version.

Notes

Differences from pandas:

last() is a pylegend extension. In pandas, there is no Expanding.last() or Rolling.last().
When numeric_only=True, the implementation applies last() per numeric column individually, then filters.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

# Last Order Id across the entire sorted window
frame.filter(items=["Order Id"]).window_frame_legend_ext(
    frame_spec=frame.rows_between(),
    order_by="Order Id",
).last().head(5).to_pandas()

	Order Id
0	11077
1	11077
2	11077
3	11077
4	11077

window_extend_legend_ext

PandasApiWindowTdsFrame.window_extend_legend_ext(value_func, agg_func=None)[source]

Apply a custom window function to all columns in the frame.

PyLegend extension — not present in pandas.

Compute a user-defined window expression over every non-grouping column. The value_func receives three arguments — a PandasApiPartialFrame (p), a PandasApiWindowReference (w), and a PandasApiTdsRow (r) — and must return either a single primitive (processed per-column) or a PandasApiTdsRow (expanded to all columns).

Parameters:

value_func (Callable[[PandasApiPartialFrame, PyLegendWindowReference, PandasApiTdsRow], Union[int, float, str, bool, date, datetime, Decimal, PyLegendPrimitive]]) –
(p, w, r) -> primitive | PandasApiTdsRow.

Common patterns:
- lambda p, w, r: p.first(w, r) — first value (returns PandasApiTdsRow → applies to all columns).
- lambda p, w, r: p.last(w, r) — last value.
- lambda p, w, r: p.nth(w, r, 3) — nth value.
- lambda p, w, r: p.lag(r, 1) — lag (previous row).
- lambda p, w, r: p.lead(r, 2) — lead (future row).
- lambda p, w, r: r["col"] — raw column ref (combined with agg_func).
agg_func (Optional[Callable[[PyLegendPrimitiveCollection], PyLegendPrimitive]]) – (collection) -> primitive. If provided, an additional aggregation step (e.g. lambda c: c.sum()) is applied on top of the value_func result.

Returns:

A new TDS frame with the window function applied to every column.

Return type:

PandasApiBaseTdsFrame

See also

WindowSeries.window_extend_legend_ext: Same operation scoped to a single column.
first: Convenience wrapper using p.first(w, r).
last: Convenience wrapper using p.last(w, r).

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

# nth-value across all columns
frame.filter(items=["Order Id"]).window_frame_legend_ext(
    frame_spec=frame.rows_between(),
    order_by="Order Id",
).window_extend_legend_ext(
    value_func=lambda p, w, r: p.nth(w, r, 3),
).head(5).to_pandas()

	Order Id
0	10250
1	10250
2	10250
3	10250
4	10250

PyLegend

Table of Contents

Quick Search

Pandas Window TDS Frame

Obtaining a PandasApiWindowTdsFrame

Selecting a single column

Order-by resolution

agg

aggregate

first

last

window_extend_legend_ext