foundryts.functions.rolling_aggregate¶

foundryts.functions.rolling_aggregate(aggregate, window)¶

Returns a function that aggregates values over a rolling window for a single time series.

A rolling window is a moving subset of data points that ends at the current timestamp (inclusive) and spans a specified duration (window size). As new data points are added, old points fall out of the window if they are outside the specified duration.

Rolling windows are commonly used for smoothing data, detecting trends, and reducing noise in time series analysis.

Aggregation functions supported:

Aggregation function	Description
min	Smallest value within the window.
max	Largest value within the window.
count	Count of points within the window.
sum	Sum of values within the window.
product	Product of values within the window.
mean	Average of values within the window.
standard_deviation	Standard deviation of values within the window.
difference	Difference between first point’s value and last point’s value in the window, providing the relative change within the window.
percent_change	Percent change from first point’s value to the last point’s value in the window, providing the relative rate of change within the window.
first	First value within the window.
last	Last value within the window.

Parameters:
aggregate (str) – Aggregation function to apply. See Aggregation Function above.
window (str | int | datetime.timedelta | pandas.Timedelta) – Duration of the rolling window, which determines how many points are evaluated at any time, e.g., 5ms, or 5e6.
Returns: A function that takes a single time series as input and computes the specified aggregate for each point within the rolling window.
Return type: (FunctionNode) -> FunctionNode

Dataframe schema¶

Column name	Type	Description
timestamp	pandas.Timestamp	Timestamp of the point
value	Union[float, str]	Value of the point

:::callout{theme="success" title="See Also"} cumulative_aggregate(), periodic_aggregate() :::

:::callout{theme="warning" title="Note"} This function is only applicable to numeric series. :::

Examples¶

>>> series = F.points(
...     (2, 10.0), (5, 20.0), (6, 30.0), (7, 40.0), (8, 50.0), (12, 60.0), name="series"
... )

>>> series.to_pandas()
                      timestamp  value
0 1970-01-01 00:00:00.000000002   10.0
1 1970-01-01 00:00:00.000000005   20.0
2 1970-01-01 00:00:00.000000006   30.0
3 1970-01-01 00:00:00.000000007   40.0
4 1970-01-01 00:00:00.000000008   50.0
5 1970-01-01 00:00:00.000000012   60.0

>>> rolling_difference = F.rolling_aggregate("difference", "3ns")(series)
>>> rolling_difference.to_pandas()
                      timestamp  value
0 1970-01-01 00:00:00.000000002    0.0
1 1970-01-01 00:00:00.000000005    0.0
2 1970-01-01 00:00:00.000000006   10.0
3 1970-01-01 00:00:00.000000007   20.0
4 1970-01-01 00:00:00.000000008   20.0
5 1970-01-01 00:00:00.000000012    0.0

>>> rolling_percentage_change = F.rolling_aggregate("percent_change", "3ns")(series)
>>> rolling_percentage_change.to_pandas()
                      timestamp     value
0 1970-01-01 00:00:00.000000002  0.000000
1 1970-01-01 00:00:00.000000005  0.000000
2 1970-01-01 00:00:00.000000006  0.500000
3 1970-01-01 00:00:00.000000007  1.000000
4 1970-01-01 00:00:00.000000008  0.666667
5 1970-01-01 00:00:00.000000012  0.000000

中文翻译¶

foundryts.functions.rolling_aggregate¶

foundryts.functions.rolling_aggregate(aggregate, window)¶

返回一个函数，用于对单个时间序列在滚动窗口(Rolling Window)内聚合值。

滚动窗口是一个移动的数据点子集，其结束于当前时间戳（包含当前时间戳），并跨越指定的持续时间（窗口大小）。随着新数据点的加入，超出指定持续时间的旧数据点将从窗口中移除。

滚动窗口常用于时间序列分析中的数据平滑、趋势检测和噪声降低。

支持的聚合函数：

聚合函数(Aggregation function)	描述
min	窗口内的最小值。
max	窗口内的最大值。
count	窗口内的数据点计数。
sum	窗口内值的总和。
product	窗口内值的乘积。
mean	窗口内值的平均值。
standard_deviation	窗口内值的标准差。
difference	窗口内第一个数据点值与最后一个数据点值之间的差值，提供窗口内的相对变化。
percent_change	窗口内第一个数据点值到最后一个数据点值的百分比变化，提供窗口内的相对变化率。
first	窗口内的第一个值。
last	窗口内的最后一个值。

参数：
aggregate (str) – 要应用的聚合函数。请参见上方的聚合函数(Aggregation Function)。
window (str | int | datetime.timedelta | pandas.Timedelta) – 滚动窗口的持续时间，决定在任何时间点评估多少个数据点，例如 5ms 或 5e6。
返回： 一个函数，该函数接受单个时间序列作为输入，并计算滚动窗口内每个数据点的指定聚合值。
返回类型： (FunctionNode) -> FunctionNode

数据框模式(Dataframe Schema)¶

列名(Column name)	类型(Type)	描述(Description)
timestamp	pandas.Timestamp	数据点的时间戳
value	Union[float, str]	数据点的值

:::callout{theme="success" title="另请参阅(See Also)"} cumulative_aggregate(), periodic_aggregate() :::

:::callout{theme="warning" title="注意(Note)"} 此函数仅适用于数值型序列。 :::

示例(Examples)¶

>>> series = F.points(
...     (2, 10.0), (5, 20.0), (6, 30.0), (7, 40.0), (8, 50.0), (12, 60.0), name="series"
... )

>>> series.to_pandas()
                      timestamp  value
0 1970-01-01 00:00:00.000000002   10.0
1 1970-01-01 00:00:00.000000005   20.0
2 1970-01-01 00:00:00.000000006   30.0
3 1970-01-01 00:00:00.000000007   40.0
4 1970-01-01 00:00:00.000000008   50.0
5 1970-01-01 00:00:00.000000012   60.0

>>> rolling_difference = F.rolling_aggregate("difference", "3ns")(series)
>>> rolling_difference.to_pandas()
                      timestamp  value
0 1970-01-01 00:00:00.000000002    0.0
1 1970-01-01 00:00:00.000000005    0.0
2 1970-01-01 00:00:00.000000006   10.0
3 1970-01-01 00:00:00.000000007   20.0
4 1970-01-01 00:00:00.000000008   20.0
5 1970-01-01 00:00:00.000000012    0.0

>>> rolling_percentage_change = F.rolling_aggregate("percent_change", "3ns")(series)
>>> rolling_percentage_change.to_pandas()
                      timestamp     value
0 1970-01-01 00:00:00.000000002  0.000000
1 1970-01-01 00:00:00.000000005  0.000000
2 1970-01-01 00:00:00.000000006  0.500000
3 1970-01-01 00:00:00.000000007  1.000000
4 1970-01-01 00:00:00.000000008  0.666667
5 1970-01-01 00:00:00.000000012  0.000000