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.

Sign up for GitHub

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): Improve docstrings rolling functions #9215

Merged
merged 6 commits into from
Jun 19, 2023
Merged

docs(python): Improve docstrings rolling functions #9215

Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
879cd82
Clarify rolling docstrings
zundertj Jun 4, 2023
2ac8cd5
Update docstrings
zundertj Jun 17, 2023
93bbb42
Update
zundertj Jun 17, 2023
e3227ea
Fix docstring indentation
zundertj Jun 17, 2023
945d4f7
Change entrypoint to endpoint
zundertj Jun 18, 2023
0ac5fa2
Fix ddof parameter description x2
zundertj Jun 19, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
128 changes: 82 additions & 46 deletions py-polars/polars/expr/expr.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4684,22 +4684,25 @@ def rolling_min(
this window will (optionally) be multiplied with the weights given by the
`weight` vector. The resulting values will be aggregated to their sum.

If you pass a ``by`` column ``<t_0, t_1, ..., t_2>``, then by default the
windows will be:
If ``by`` has not been specified (the default), the window at a given row will
include the row itself, and the `window_size - 1` elements before it.

If you pass a ``by`` column ``<t_0, t_1, ..., t_2>``, then `closed="left"`
means the windows will be:

- [t_0 - window_size, t_0)
- [t_1 - window_size, t_1)
- ...
- [t_n - window_size, t_n)

Otherwise, the window at a given row will include the row itself, and the
`window_size - 1` elements before it.
With `closed="right"`, the left endpoint is not included and the right
entrypoint is included.
zundertj marked this conversation as resolved.
Show resolved Hide resolved

Parameters
----------
window_size
The length of the window. Can be a fixed integer size, or a dynamic temporal
size indicated by a timedelta or the following string language:
The length of the window. Can be a fixed integer size, or a dynamic
temporal size indicated by a timedelta or the following string language:

- 1ns (1 nanosecond)
- 1us (1 microsecond)
Expand Down Expand Up @@ -4733,7 +4736,8 @@ def rolling_min(
set the column that will be used to determine the windows. This column must
be of dtype Datetime.
closed : {'left', 'right', 'both', 'none'}
Define which sides of the temporal interval are closed (inclusive).
Define which sides of the temporal interval are closed (inclusive); only
applicable if `by` has been set.

Warnings
--------
Expand Down Expand Up @@ -4795,16 +4799,19 @@ def rolling_max(
this window will (optionally) be multiplied with the weights given by the
`weight` vector. The resulting values will be aggregated to their sum.

If you pass a ``by`` column ``<t_0, t_1, ..., t_2>``, then by default the
windows will be:
If ``by`` has not been specified (the default), the window at a given row will
include the row itself, and the `window_size - 1` elements before it.

If you pass a ``by`` column ``<t_0, t_1, ..., t_2>``, then `closed="left"`
means the windows will be:

- [t_0 - window_size, t_0)
- [t_1 - window_size, t_1)
- ...
- [t_n - window_size, t_n)

Otherwise, the window at a given row will include the row itself, and the
`window_size - 1` elements before it.
With `closed="right"`, the left endpoint is not included and the right
entrypoint is included.

Parameters
----------
Expand Down Expand Up @@ -4844,7 +4851,8 @@ def rolling_max(
set the column that will be used to determine the windows. This column must
be of dtype Datetime.
closed : {'left', 'right', 'both', 'none'}
Define which sides of the temporal interval are closed (inclusive).
Define which sides of the temporal interval are closed (inclusive); only
applicable if `by` has been set.

Warnings
--------
Expand Down Expand Up @@ -4906,16 +4914,19 @@ def rolling_mean(
this window will (optionally) be multiplied with the weights given by the
`weight` vector. The resulting values will be aggregated to their sum.

If you pass a ``by`` column ``<t_0, t_1, ..., t_2>``, then by default the
windows will be:
If ``by`` has not been specified (the default), the window at a given row will
include the row itself, and the `window_size - 1` elements before it.

If you pass a ``by`` column ``<t_0, t_1, ..., t_2>``, then `closed="left"`
means the windows will be:

- [t_0 - window_size, t_0)
- [t_1 - window_size, t_1)
- ...
- [t_n - window_size, t_n)

Otherwise, the window at a given row will include the row itself, and the
`window_size - 1` elements before it.
With `closed="right"`, the left endpoint is not included and the right
entrypoint is included.

Parameters
----------
Expand Down Expand Up @@ -4955,7 +4966,8 @@ def rolling_mean(
set the column that will be used to determine the windows. This column must
be of dtype Datetime.
closed : {'left', 'right', 'both', 'none'}
Define which sides of the temporal interval are closed (inclusive).
Define which sides of the temporal interval are closed (inclusive); only
applicable if `by` has been set.

Warnings
--------
Expand Down Expand Up @@ -5017,16 +5029,19 @@ def rolling_sum(
this window will (optionally) be multiplied with the weights given by the
`weight` vector. The resulting values will be aggregated to their sum.

If you pass a ``by`` column ``<t_0, t_1, ..., t_2>``, then by default the
windows will be:
If ``by`` has not been specified (the default), the window at a given row will
include the row itself, and the `window_size - 1` elements before it.

If you pass a ``by`` column ``<t_0, t_1, ..., t_2>``, then `closed="left"`
means the windows will be:

- [t_0 - window_size, t_0)
- [t_1 - window_size, t_1)
- ...
- [t_n - window_size, t_n)

Otherwise, the window at a given row will include the row itself, and the
`window_size - 1` elements before it.
With `closed="right"`, the left endpoint is not included and the right
entrypoint is included.

Parameters
----------
Expand Down Expand Up @@ -5066,7 +5081,8 @@ def rolling_sum(
set the column that will be used to determine the windows. This column must
of dtype `{Date, Datetime}`
closed : {'left', 'right', 'both', 'none'}
Define which sides of the temporal interval are closed (inclusive).
Define which sides of the temporal interval are closed (inclusive); only
applicable if `by` has been set.

Warnings
--------
Expand Down Expand Up @@ -5129,16 +5145,19 @@ def rolling_std(
this window will (optionally) be multiplied with the weights given by the
`weight` vector. The resulting values will be aggregated to their sum.

If you pass a ``by`` column ``<t_0, t_1, ..., t_2>``, then by default the
windows will be:
If ``by`` has not been specified (the default), the window at a given row will
include the row itself, and the `window_size - 1` elements before it.

If you pass a ``by`` column ``<t_0, t_1, ..., t_2>``, then `closed="left"` means
the windows will be:

- [t_0 - window_size, t_0)
- [t_1 - window_size, t_1)
- ...
- [t_n - window_size, t_n)

Otherwise, the window at a given row will include the row itself, and the
`window_size - 1` elements before it.
With `closed="right"`, the left endpoint is not included and the right
entrypoint is included.

Parameters
----------
Expand Down Expand Up @@ -5178,9 +5197,12 @@ def rolling_std(
set the column that will be used to determine the windows. This column must
be of dtype Datetime.
closed : {'left', 'right', 'both', 'none'}
Define which sides of the temporal interval are closed (inclusive).
Define which sides of the temporal interval are closed (inclusive); only
applicable if `by` has been set.
ddof
"Delta Degrees of Freedom": The divisor for a length N window is N - ddof
Define which sides of the temporal interval are closed (inclusive); only
applicable if `by` has been set.
zundertj marked this conversation as resolved.
Show resolved Hide resolved

Warnings
--------
Expand Down Expand Up @@ -5243,16 +5265,19 @@ def rolling_var(
this window will (optionally) be multiplied with the weights given by the
`weight` vector. The resulting values will be aggregated to their sum.

If you pass a ``by`` column ``<t_0, t_1, ..., t_2>``, then by default the
windows will be:
If ``by`` has not been specified (the default), the window at a given row will
include the row itself, and the `window_size - 1` elements before it.

If you pass a ``by`` column ``<t_0, t_1, ..., t_2>``, then `closed="left"`
means the windows will be:

- [t_0 - window_size, t_0)
- [t_1 - window_size, t_1)
- ...
- [t_n - window_size, t_n)

Otherwise, the window at a given row will include the row itself, and the
`window_size - 1` elements before it.
With `closed="right"`, the left endpoint is not included and the right
entrypoint is included.

Parameters
----------
Expand Down Expand Up @@ -5292,9 +5317,12 @@ def rolling_var(
set the column that will be used to determine the windows. This column must
be of dtype Datetime.
closed : {'left', 'right', 'both', 'none'}
Define which sides of the temporal interval are closed (inclusive).
Define which sides of the temporal interval are closed (inclusive); only
applicable if `by` has been set.
ddof
"Delta Degrees of Freedom": The divisor for a length N window is N - ddof
Define which sides of the temporal interval are closed (inclusive); only
applicable if `by` has been set.

Warnings
--------
Expand Down Expand Up @@ -5358,16 +5386,19 @@ def rolling_median(
"""
Compute a rolling median.

If you pass a ``by`` column ``<t_0, t_1, ..., t_2>``, then by default the
windows will be:
If ``by`` has not been specified (the default), the window at a given row will
include the row itself, and the `window_size - 1` elements before it.

If you pass a ``by`` column ``<t_0, t_1, ..., t_2>``, then `closed="left"` means
the windows will be:

- [t_0 - window_size, t_0)
- [t_1 - window_size, t_1)
- ...
- [t_n - window_size, t_n)

Otherwise, the window at a given row will include the row itself, and the
`window_size - 1` elements before it.
With `closed="right"`, the left endpoint is not included and the right
entrypoint is included.

Parameters
----------
Expand Down Expand Up @@ -5407,7 +5438,8 @@ def rolling_median(
set the column that will be used to determine the windows. This column must
be of dtype Datetime.
closed : {'left', 'right', 'both', 'none'}
Define which sides of the temporal interval are closed (inclusive).
Define which sides of the temporal interval are closed (inclusive); only
applicable if `by` has been set.

Warnings
--------
Expand Down Expand Up @@ -5467,16 +5499,19 @@ def rolling_quantile(
"""
Compute a rolling quantile.

If you pass a ``by`` column ``<t_0, t_1, ..., t_2>``, then by default the
windows will be:
If ``by`` has not been specified (the default), the window at a given row will
include the row itself, and the `window_size - 1` elements before it.

If you pass a ``by`` column ``<t_0, t_1, ..., t_2>``, then `closed="left"`
means the windows will be:

- [t_0 - window_size, t_0)
- [t_1 - window_size, t_1)
- ...
- [t_n - window_size, t_n)

Otherwise, the window at a given row will include the row itself, and the
`window_size - 1` elements before it.
With `closed="right"`, the left endpoint is not included and the right
entrypoint is included.

Parameters
----------
Expand All @@ -5485,8 +5520,8 @@ def rolling_quantile(
interpolation : {'nearest', 'higher', 'lower', 'midpoint', 'linear'}
Interpolation method.
window_size
The length of the window. Can be a fixed integer size, or a dynamic temporal
size indicated by a timedelta or the following string language:
The length of the window. Can be a fixed integer size, or a dynamic
temporal size indicated by a timedelta or the following string language:

- 1ns (1 nanosecond)
- 1us (1 microsecond)
Expand All @@ -5508,8 +5543,8 @@ def rolling_quantile(
If a timedelta or the dynamic string language is used, the `by`
and `closed` arguments must also be set.
weights
An optional slice with the same length as the window that will be multiplied
elementwise with the values in the window.
An optional slice with the same length as the window that will be
multiplied elementwise with the values in the window.
min_periods
The number of values in the window that should be non-null before computing
a result. If None, it will be set equal to window size.
Expand All @@ -5520,7 +5555,8 @@ def rolling_quantile(
set the column that will be used to determine the windows. This column must
be of dtype Datetime.
closed : {'left', 'right', 'both', 'none'}
Define which sides of the temporal interval are closed (inclusive).
Define which sides of the temporal interval are closed (inclusive); only
applicable if `by` has been set.

Warnings
--------
Expand Down