diff --git a/py-polars/polars/expr/expr.py b/py-polars/polars/expr/expr.py index f4012256ed13..dd02a58656fc 100644 --- a/py-polars/polars/expr/expr.py +++ b/py-polars/polars/expr/expr.py @@ -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 ````, 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 ````, 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) @@ -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 -------- @@ -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 ````, 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 ````, 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 ---------- @@ -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 -------- @@ -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 ````, 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 ````, 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 ---------- @@ -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 -------- @@ -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 ````, 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 ````, 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 ---------- @@ -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 -------- @@ -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 ````, 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 ````, 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 ---------- @@ -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 @@ -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 ````, 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 ````, 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 ---------- @@ -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 @@ -5358,16 +5382,19 @@ def rolling_median( """ Compute a rolling median. - If you pass a ``by`` column ````, 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 ````, 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 ---------- @@ -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 -------- @@ -5467,16 +5495,19 @@ def rolling_quantile( """ Compute a rolling quantile. - If you pass a ``by`` column ````, 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 ````, 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 ---------- @@ -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) @@ -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. @@ -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 --------