Polars Windowing Functions

last modified March 1, 2025

Polars is a fast, efficient DataFrame library in Python. Windowing functions are used for analyzing data within a sliding or expanding window. This tutorial covers how to use windowing functions in Polars, with practical examples.

Windowing functions are useful for time series analysis, moving averages, and cumulative calculations. Polars provides methods like rolling and over for these tasks.

Rolling Window: Moving Average

This example shows how to calculate a moving average using a rolling window.

rolling_window.py

import polars as pl

data = {
    'Date': pl.date_range(start='2023-01-01', end='2023-01-10', interval='1d'),
    'Values': [10, 20, 30, 40, 50, 60, 70, 80, 90, 100]
}

df = pl.DataFrame(data)
df = df.with_column(
    pl.col('Values').rolling_mean(window_size=3).alias('MovingAvg')
)

print(df)

The rolling_mean(window_size=3) calculates a 3-day moving average for the 'Values' column. This is useful for smoothing time series data.

Rolling Window: Minimum and Maximum

This example demonstrates calculating rolling minimum and maximum values.

rolling_min_max.py

import polars as pl

data = {
    'Date': pl.date_range(start='2023-01-01', end='2023-01-10', interval='1d'),
    'Values': [10, 20, 30, 40, 50, 60, 70, 80, 90, 100]
}

df = pl.DataFrame(data)
df = df.with_columns([
    pl.col('Values').rolling_min(window_size=3).alias('RollingMin'),
    pl.col('Values').rolling_max(window_size=3).alias('RollingMax')
])

print(df)

The rolling_min(window_size=3) and rolling_max(window_size=3) calculate the rolling minimum and maximum values, respectively. This is useful for identifying trends.

Expanding Window: Cumulative Sum

This example shows how to calculate a cumulative sum using an expanding window.

expanding_sum.py

import polars as pl

data = {
    'Date': pl.date_range(start='2023-01-01', end='2023-01-10', interval='1d'),
    'Values': [10, 20, 30, 40, 50, 60, 70, 80, 90, 100]
}

df = pl.DataFrame(data)
df = df.with_column(
    pl.col('Values').cumsum().alias('CumulativeSum')
)

print(df)

The cumsum calculates the cumulative sum of the 'Values' column. This is useful for tracking cumulative totals.

Expanding Window: Cumulative Average

This example demonstrates calculating a cumulative average using an expanding window.

expanding_avg.py

import polars as pl

data = {
    'Date': pl.date_range(start='2023-01-01', end='2023-01-10', interval='1d'),
    'Values': [10, 20, 30, 40, 50, 60, 70, 80, 90, 100]
}

df = pl.DataFrame(data)
df = df.with_column(
    pl.col('Values').cummean().alias('CumulativeAvg')
)

print(df)

The cummean calculates the cumulative average of the 'Values' column. This is useful for analyzing trends over time.

Rolling Window with Custom Function

This example shows how to apply a custom function to a rolling window.

rolling_custom.py

import polars as pl

data = {
    'Date': pl.date_range(start='2023-01-01', end='2023-01-10', interval='1d'),
    'Values': [10, 20, 30, 40, 50, 60, 70, 80, 90, 100]
}

df = pl.DataFrame(data)

def custom_agg(x):
    return x.max() - x.min()

df = df.with_column(
    pl.col('Values').rolling_apply(window_size=3, function=custom_agg).alias('RollingRange')
)

print(df)

The rolling_apply(window_size=3, function=custom_agg) applies a custom function to calculate the range (max - min) within each rolling window. This is useful for custom calculations.

Rolling Window with Center Alignment

This example demonstrates using a rolling window with center alignment.

rolling_center.py

import polars as pl

data = {
    'Date': pl.date_range(start='2023-01-01', end='2023-01-10', interval='1d'),
    'Values': [10, 20, 30, 40, 50, 60, 70, 80, 90, 100]
}

df = pl.DataFrame(data)
df = df.with_column(
    pl.col('Values').rolling_mean(window_size=3, center=True).alias('RollingAvgCenter')
)

print(df)

The rolling_mean(window_size=3, center=True) calculates a rolling average with the window centered on each point. This is useful for symmetric analysis.

Rolling Window with Minimum Periods

This example shows how to use a rolling window with a minimum number of periods.

rolling_min_periods.py

import polars as pl

data = {
    'Date': pl.date_range(start='2023-01-01', end='2023-01-10', interval='1d'),
    'Values': [10, 20, 30, 40, 50, 60, 70, 80, 90, 100]
}

df = pl.DataFrame(data)
df = df.with_column(
    pl.col('Values').rolling_mean(window_size=3, min_periods=1).alias('RollingAvgMinPeriods')
)

print(df)

The rolling_mean(window_size=3, min_periods=1) calculates a rolling average even if fewer than 3 values are available. This is useful for handling edge cases.

Best Practices for Windowing Functions

Understand Data: Analyze data structure before applying windowing functions.
Choose Appropriate Window Size: Select a window size that aligns with your analysis goals.
Handle Edge Cases: Use min_periods to handle incomplete windows.
Validate Results: Check windowed data for accuracy and consistency.

Source

Polars rolling Documentation

In this article, we have explored how to use windowing functions in Polars.

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.

List all Polars tutorials.

Ebooks