Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(python): correct default in rolling_* function examples #16000

Merged
merged 1 commit into from
May 2, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
117 changes: 55 additions & 62 deletions py-polars/polars/expr/expr.py
Original file line number Diff line number Diff line change
Expand Up @@ -6238,28 +6238,29 @@ def rolling_min(
│ 23 ┆ 2001-01-01 23:00:00 │
│ 24 ┆ 2001-01-02 00:00:00 │
└───────┴─────────────────────┘

Compute the rolling min with the temporal windows closed on the right (default)

>>> df_temporal.with_columns(
... rolling_row_min=pl.col("index").rolling_min(
... window_size="2h", by="date", closed="left"
... )
... rolling_row_min=pl.col("index").rolling_min(window_size="2h", by="date")
... )
shape: (25, 3)
┌───────┬─────────────────────┬─────────────────┐
│ index ┆ date ┆ rolling_row_min │
│ --- ┆ --- ┆ --- │
│ u32 ┆ datetime[μs] ┆ u32 │
╞═══════╪═════════════════════╪═════════════════╡
│ 0 ┆ 2001-01-01 00:00:00 ┆ null
│ 0 ┆ 2001-01-01 00:00:00 ┆ 0
│ 1 ┆ 2001-01-01 01:00:00 ┆ 0 │
│ 2 ┆ 2001-01-01 02:00:00 ┆ 0
│ 3 ┆ 2001-01-01 03:00:00 ┆ 1
│ 4 ┆ 2001-01-01 04:00:00 ┆ 2
│ 2 ┆ 2001-01-01 02:00:00 ┆ 1
│ 3 ┆ 2001-01-01 03:00:00 ┆ 2
│ 4 ┆ 2001-01-01 04:00:00 ┆ 3
│ … ┆ … ┆ … │
│ 20 ┆ 2001-01-01 20:00:00 ┆ 18
│ 21 ┆ 2001-01-01 21:00:00 ┆ 19
│ 22 ┆ 2001-01-01 22:00:00 ┆ 20
│ 23 ┆ 2001-01-01 23:00:00 ┆ 21
│ 24 ┆ 2001-01-02 00:00:00 ┆ 22
│ 20 ┆ 2001-01-01 20:00:00 ┆ 19
│ 21 ┆ 2001-01-01 21:00:00 ┆ 20
│ 22 ┆ 2001-01-01 22:00:00 ┆ 21
│ 23 ┆ 2001-01-01 23:00:00 ┆ 22
│ 24 ┆ 2001-01-02 00:00:00 ┆ 23
└───────┴─────────────────────┴─────────────────┘
"""
window_size = deprecate_saturating(window_size)
Expand Down Expand Up @@ -6447,30 +6448,28 @@ def rolling_max(
│ 24 ┆ 2001-01-02 00:00:00 │
└───────┴─────────────────────┘

Compute the rolling max with the default left closure of temporal windows
Compute the rolling max with the temporal windows closed on the right (default)

>>> df_temporal.with_columns(
... rolling_row_max=pl.col("index").rolling_max(
... window_size="2h", by="date", closed="left"
... )
... rolling_row_max=pl.col("index").rolling_max(window_size="2h", by="date")
... )
shape: (25, 3)
┌───────┬─────────────────────┬─────────────────┐
│ index ┆ date ┆ rolling_row_max │
│ --- ┆ --- ┆ --- │
│ u32 ┆ datetime[μs] ┆ u32 │
╞═══════╪═════════════════════╪═════════════════╡
│ 0 ┆ 2001-01-01 00:00:00 ┆ null
│ 1 ┆ 2001-01-01 01:00:00 ┆ 0
│ 2 ┆ 2001-01-01 02:00:00 ┆ 1
│ 3 ┆ 2001-01-01 03:00:00 ┆ 2
│ 4 ┆ 2001-01-01 04:00:00 ┆ 3
│ 0 ┆ 2001-01-01 00:00:00 ┆ 0
│ 1 ┆ 2001-01-01 01:00:00 ┆ 1
│ 2 ┆ 2001-01-01 02:00:00 ┆ 2
│ 3 ┆ 2001-01-01 03:00:00 ┆ 3
│ 4 ┆ 2001-01-01 04:00:00 ┆ 4
│ … ┆ … ┆ … │
│ 20 ┆ 2001-01-01 20:00:00 ┆ 19
│ 21 ┆ 2001-01-01 21:00:00 ┆ 20
│ 22 ┆ 2001-01-01 22:00:00 ┆ 21
│ 23 ┆ 2001-01-01 23:00:00 ┆ 22
│ 24 ┆ 2001-01-02 00:00:00 ┆ 23
│ 20 ┆ 2001-01-01 20:00:00 ┆ 20
│ 21 ┆ 2001-01-01 21:00:00 ┆ 21
│ 22 ┆ 2001-01-01 22:00:00 ┆ 22
│ 23 ┆ 2001-01-01 23:00:00 ┆ 23
│ 24 ┆ 2001-01-02 00:00:00 ┆ 24
└───────┴─────────────────────┴─────────────────┘

Compute the rolling max with the closure of windows on both sides
Expand Down Expand Up @@ -6688,11 +6687,11 @@ def rolling_mean(
│ 24 ┆ 2001-01-02 00:00:00 │
└───────┴─────────────────────┘

Compute the rolling mean with the default left closure of temporal windows
Compute the rolling mean with the temporal windows closed on the right (default)

>>> df_temporal.with_columns(
... rolling_row_mean=pl.col("index").rolling_mean(
... window_size="2h", by="date", closed="left"
... window_size="2h", by="date"
... )
... )
shape: (25, 3)
Expand All @@ -6701,17 +6700,17 @@ def rolling_mean(
│ --- ┆ --- ┆ --- │
│ u32 ┆ datetime[μs] ┆ f64 │
╞═══════╪═════════════════════╪══════════════════╡
│ 0 ┆ 2001-01-01 00:00:00 ┆ null
│ 1 ┆ 2001-01-01 01:00:00 ┆ 0.0
│ 2 ┆ 2001-01-01 02:00:00 ┆ 0.5 │
│ 3 ┆ 2001-01-01 03:00:00 ┆ 1.5 │
│ 4 ┆ 2001-01-01 04:00:00 ┆ 2.5 │
│ 0 ┆ 2001-01-01 00:00:00 ┆ 0.0
│ 1 ┆ 2001-01-01 01:00:00 ┆ 0.5
│ 2 ┆ 2001-01-01 02:00:00 ┆ 1.5 │
│ 3 ┆ 2001-01-01 03:00:00 ┆ 2.5 │
│ 4 ┆ 2001-01-01 04:00:00 ┆ 3.5 │
│ … ┆ … ┆ … │
│ 20 ┆ 2001-01-01 20:00:00 ┆ 18.5 │
│ 21 ┆ 2001-01-01 21:00:00 ┆ 19.5 │
│ 22 ┆ 2001-01-01 22:00:00 ┆ 20.5 │
│ 23 ┆ 2001-01-01 23:00:00 ┆ 21.5 │
│ 24 ┆ 2001-01-02 00:00:00 ┆ 22.5 │
│ 20 ┆ 2001-01-01 20:00:00 ┆ 19.5 │
│ 21 ┆ 2001-01-01 21:00:00 ┆ 20.5 │
│ 22 ┆ 2001-01-01 22:00:00 ┆ 21.5 │
│ 23 ┆ 2001-01-01 23:00:00 ┆ 22.5 │
│ 24 ┆ 2001-01-02 00:00:00 ┆ 23.5 │
└───────┴─────────────────────┴──────────────────┘

Compute the rolling mean with the closure of windows on both sides
Expand Down Expand Up @@ -6931,30 +6930,28 @@ def rolling_sum(
│ 24 ┆ 2001-01-02 00:00:00 │
└───────┴─────────────────────┘

Compute the rolling sum with the default left closure of temporal windows
Compute the rolling sum with the temporal windows closed on the right (default)

>>> df_temporal.with_columns(
... rolling_row_sum=pl.col("index").rolling_sum(
... window_size="2h", by="date", closed="left"
... )
... rolling_row_sum=pl.col("index").rolling_sum(window_size="2h", by="date")
... )
shape: (25, 3)
┌───────┬─────────────────────┬─────────────────┐
│ index ┆ date ┆ rolling_row_sum │
│ --- ┆ --- ┆ --- │
│ u32 ┆ datetime[μs] ┆ u32 │
╞═══════╪═════════════════════╪═════════════════╡
│ 0 ┆ 2001-01-01 00:00:00 ┆ null
│ 1 ┆ 2001-01-01 01:00:00 ┆ 0
│ 2 ┆ 2001-01-01 02:00:00 ┆ 1
│ 3 ┆ 2001-01-01 03:00:00 ┆ 3
│ 4 ┆ 2001-01-01 04:00:00 ┆ 5
│ 0 ┆ 2001-01-01 00:00:00 ┆ 0
│ 1 ┆ 2001-01-01 01:00:00 ┆ 1
│ 2 ┆ 2001-01-01 02:00:00 ┆ 3
│ 3 ┆ 2001-01-01 03:00:00 ┆ 5
│ 4 ┆ 2001-01-01 04:00:00 ┆ 7
│ … ┆ … ┆ … │
│ 20 ┆ 2001-01-01 20:00:00 ┆ 37
│ 21 ┆ 2001-01-01 21:00:00 ┆ 39
│ 22 ┆ 2001-01-01 22:00:00 ┆ 41
│ 23 ┆ 2001-01-01 23:00:00 ┆ 43
│ 24 ┆ 2001-01-02 00:00:00 ┆ 45
│ 20 ┆ 2001-01-01 20:00:00 ┆ 39
│ 21 ┆ 2001-01-01 21:00:00 ┆ 41
│ 22 ┆ 2001-01-01 22:00:00 ┆ 43
│ 23 ┆ 2001-01-01 23:00:00 ┆ 45
│ 24 ┆ 2001-01-02 00:00:00 ┆ 47
└───────┴─────────────────────┴─────────────────┘

Compute the rolling sum with the closure of windows on both sides
Expand Down Expand Up @@ -7172,12 +7169,10 @@ def rolling_std(
│ 24 ┆ 2001-01-02 00:00:00 │
└───────┴─────────────────────┘

Compute the rolling std with the default left closure of temporal windows
Compute the rolling std with the temporal windows closed on the right (default)

>>> df_temporal.with_columns(
... rolling_row_std=pl.col("index").rolling_std(
... window_size="2h", by="date", closed="left"
... )
... rolling_row_std=pl.col("index").rolling_std(window_size="2h", by="date")
... )
shape: (25, 3)
┌───────┬─────────────────────┬─────────────────┐
Expand All @@ -7186,7 +7181,7 @@ def rolling_std(
│ u32 ┆ datetime[μs] ┆ f64 │
╞═══════╪═════════════════════╪═════════════════╡
│ 0 ┆ 2001-01-01 00:00:00 ┆ null │
│ 1 ┆ 2001-01-01 01:00:00 ┆ null
│ 1 ┆ 2001-01-01 01:00:00 ┆ 0.707107
│ 2 ┆ 2001-01-01 02:00:00 ┆ 0.707107 │
│ 3 ┆ 2001-01-01 03:00:00 ┆ 0.707107 │
│ 4 ┆ 2001-01-01 04:00:00 ┆ 0.707107 │
Expand Down Expand Up @@ -7419,12 +7414,10 @@ def rolling_var(
│ 24 ┆ 2001-01-02 00:00:00 │
└───────┴─────────────────────┘

Compute the rolling var with the default left closure of temporal windows
Compute the rolling var with the temporal windows closed on the right (default)

>>> df_temporal.with_columns(
... rolling_row_var=pl.col("index").rolling_var(
... window_size="2h", by="date", closed="left"
... )
... rolling_row_var=pl.col("index").rolling_var(window_size="2h", by="date")
... )
shape: (25, 3)
┌───────┬─────────────────────┬─────────────────┐
Expand All @@ -7433,7 +7426,7 @@ def rolling_var(
│ u32 ┆ datetime[μs] ┆ f64 │
╞═══════╪═════════════════════╪═════════════════╡
│ 0 ┆ 2001-01-01 00:00:00 ┆ null │
│ 1 ┆ 2001-01-01 01:00:00 ┆ null
│ 1 ┆ 2001-01-01 01:00:00 ┆ 0.5
│ 2 ┆ 2001-01-01 02:00:00 ┆ 0.5 │
│ 3 ┆ 2001-01-01 03:00:00 ┆ 0.5 │
│ 4 ┆ 2001-01-01 04:00:00 ┆ 0.5 │
Expand Down