diff --git a/docs/src/reference/temporian/operators/window/moving_quantile.md b/docs/src/reference/temporian/operators/window/moving_quantile.md new file mode 100644 index 000000000..d4723cdf8 --- /dev/null +++ b/docs/src/reference/temporian/operators/window/moving_quantile.md @@ -0,0 +1 @@ +::: temporian.EventSet.moving_quantile diff --git a/temporian/core/event_set_ops.py b/temporian/core/event_set_ops.py index 247780177..4ca71eb9e 100644 --- a/temporian/core/event_set_ops.py +++ b/temporian/core/event_set_ops.py @@ -3224,7 +3224,58 @@ def moving_quantile( quantile: float, sampling: Optional[EventSetOrNode] = None, ) -> EventSetOrNode: - """ """ + """Computes the quantile in a sliding window over an + [`EventSet`][temporian.EventSet]. + + For each t in sampling, and for each feature independently, returns at + time t the appropiated quantile for the feature in the window + (t - window_length, t]. + + `sampling` can't be specified if a variable `window_length` is + specified (i.e. if `window_length` is an EventSet). + + If `sampling` is specified or `window_length` is an EventSet, the moving + window is sampled at each timestamp in them, else it is sampled on the + input's. + + Missing values (such as NaNs) are ignored. + + If the window does not contain any values (e.g., all the values are + missing, or the window does not contain any sampling), outputs missing + values. + + The quantile calculated in each window is equivalent to numpy's + `"averaged_inverted_cdf"` method. + + Example: + ```python + >>> a = tp.event_set( + ... timestamps=[0, 1, 2, 5, 6, 7], + ... features={"value": [np.nan, 1, 5, 10, 15, 20]}, + ... ) + + >>> a.moving_quantile(tp.duration.seconds(4), quantile=0.5) + indexes: ... + (6 events): + timestamps: [0. 1. 2. 5. 6. 7.] + 'value': [ nan 1. 3. 7.5 12.5 15. ] + ... + + ``` + + See [`EventSet.moving_count()`][temporian.EventSet.moving_count] for + examples of moving window operations with external sampling and indices. + + Args: + window_length: Sliding window's length. + quantile: the desired quantile defined in the range (0, 1). + sampling: Timestamps to sample the sliding window's value at. If not + provided, timestamps in the input are used. + + Returns: + EventSet containing the moving standard deviation of each feature in + the input. + """ from temporian.core.operators.window.moving_quantile import ( moving_quantile, ) diff --git a/temporian/core/test/registered_operators_test.py b/temporian/core/test/registered_operators_test.py index 155790bee..3b087bbf9 100644 --- a/temporian/core/test/registered_operators_test.py +++ b/temporian/core/test/registered_operators_test.py @@ -81,6 +81,7 @@ def test_base(self): "MOVING_MAX", "MOVING_MIN", "MOVING_PRODUCT", + "MOVING_QUANTILE", "MOVING_STANDARD_DEVIATION", "MOVING_SUM", "MULTIPLICATION",