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

Examples

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

Copied!1
2
3
4
5
6
7
8
>>> 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

Copied!1
2
3
4
5
6
7
8
9
>>> 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

Copied!1
2
3
4
5
6
7
8
9
>>> 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