Skip to content

Commit

Permalink
docs(python): Improve docstrings rolling functions (#9215)
Browse files Browse the repository at this point in the history
  • Loading branch information
@zundertj
zundertj authored Jun 19, 2023
1 parent 62ac540 commit b1452a7
Showing 1 changed file with 78 additions and 46 deletions.
124 changes: 78 additions & 46 deletions py-polars/polars/expr/expr.py
View file
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
endpoint is included.
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
endpoint 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
endpoint 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
endpoint 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
endpoint is included.
Parameters
----------
Expand Down Expand Up @@ -5178,7 +5197,8 @@ 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
Expand Down Expand Up @@ -5243,16 +5263,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
endpoint is included.
Parameters
----------
Expand Down Expand Up @@ -5292,7 +5315,8 @@ 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
Expand Down Expand Up @@ -5358,16 +5382,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
endpoint is included.
Parameters
----------
Expand Down Expand Up @@ -5407,7 +5434,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 +5495,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
endpoint is included.
Parameters
----------
Expand All @@ -5485,8 +5516,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 +5539,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 +5551,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

0 comments on commit b1452a7

Please sign in to comment.