foundryts.functions.periodic_aggregate

foundryts.functions.periodic_aggregate(aggregate, window, window_type='end', alignment_timestamp=0)

Returns a function that aggregates values over discrete, periodic windows for a single time series.

A periodic window divides the time series into windows of fixed durations. For each window, an aggregate function is applied to the points within that window. The result is a time series with values representing the aggregate for each window. Windows with no data points are not included in the output.

This method is useful for summarizing data over regular periods, such as generating hourly, daily, or weekly summaries from a continuous stream of data.

Aggregation functions supported:

• Parameters:

  • aggregate (str) – Aggregation function to apply, use a valid option from the Aggregation Function table above.

  • window (int , datetime.timedelta , str) – Duration of each periodic window, e.g., 5ms, or 5e6.

  • window_type (str , optional) –

    Type of window to apply (default is “end”):

    start: Window is inclusive at the start and exclusive at the end. The timestamp of the aggregation is the start of the window. end: Window is exclusive at the start and inclusive at the end. The timestamp of the aggregation is the end of the window.

  • alignment_timestamp (str | float | datetime.datetime , optional) – The timestamp used to align the result, such that ticks in the result time series will lie at integer multiples of the window duration from the alignment timestamp (default is 0).

• Returns: A function that takes a single time series as input and computes the specified aggregate for each periodic window.
• Return type: (FunctionNode) -> FunctionNode

Dataframe schema

Examples

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
>>> series = F.points(
...     (1, 1.0),
...     (101, 2.0),
...     (200, 4.0),
...     (201, 8.0),
...     (299, 16.0),
...     (300, 32.0),
...     (1000, 64.0),
...     (12345, 128.0),
...     name="series",
... )
>>> series.to_pandas()
                      timestamp  value
0 1970-01-01 00:00:00.000000001    1.0
1 1970-01-01 00:00:00.000000101    2.0
2 1970-01-01 00:00:00.000000200    4.0
3 1970-01-01 00:00:00.000000201    8.0
4 1970-01-01 00:00:00.000000299   16.0
5 1970-01-01 00:00:00.000000300   32.0
6 1970-01-01 00:00:00.000001000   64.0
7 1970-01-01 00:00:00.000012345  128.0

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
>>> periodic_difference = F.periodic_aggregate("difference", "100ns")(series) # window_type defaults to end
# 5 windows with (1,2,3,1,1) points:
# window 1: [(1, 1.0)]
# window 2: [
# (101, 2.0),
# (200, 4.0)
# ]
# window 3: [
# (201, 8.0),
# (200, 16.0),
# (300. 32.0)
# ]
# window 4: [(1000, 64.0)]
# window 5: [(12345, 128.0)]
>>> periodic_difference.to_pandas()
                      timestamp  value
0 1970-01-01 00:00:00.000000100    0.0
1 1970-01-01 00:00:00.000000200    2.0
2 1970-01-01 00:00:00.000000300   24.0
3 1970-01-01 00:00:00.000001000    0.0
4 1970-01-01 00:00:00.000012400    0.0

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
>>> periodic_percentage_change = F.periodic_aggregate("percent_change", "100ns")(series) # window_type defaults to end
# 5 windows with (1,2,3,1,1) points:
# window 1: [(1, 1.0)]
# window 2: [
# (101, 2.0),
# (200, 4.0)
# ]
# window 3: [
# (201, 8.0),
# (200, 16.0),
# (300. 32.0)
# ]
# window 4: [(1000, 64.0)]
# window 5: [(12345, 128.0)]
>>> periodic_percentage_change.to_pandas()
                      timestamp  value
0 1970-01-01 00:00:00.000000100    0.0
1 1970-01-01 00:00:00.000000200    1.0
2 1970-01-01 00:00:00.000000300    3.0
3 1970-01-01 00:00:00.000001000    0.0
4 1970-01-01 00:00:00.000012400    0.0

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
>>> periodic_percentage_change_window_start = F.periodic_aggregate(
...     "percent_change", "100ns", "start"
... )(series)
# 6 windows with (1,1,3,1,1,1) points:
# window 0: [(1, 1.0)]
# window 1: [(101, 2.0)]
# window 2: [
# (200, 4.0),
# (201, 8.0),
# (299, 16.0)
# ]
# window 3: [(300, 32.0)]
# window 4: [(1000, 64.0)]
# window 5: [(12345, 128.0)]
>>> periodic_percentage_change_window_start.to_pandas()
                      timestamp  value
0 1970-01-01 00:00:00.000000000    0.0
1 1970-01-01 00:00:00.000000100    0.0
2 1970-01-01 00:00:00.000000200    3.0
3 1970-01-01 00:00:00.000000300    0.0
4 1970-01-01 00:00:00.000001000    0.0
5 1970-01-01 00:00:00.000012300    0.0

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
>>> periodic_percentage_change_with_alignment = F.periodic_aggregate(
...     "percent_change", "100ns", alignment_timestamp=50
... )(series)
# 6 windows with (1,1,2,2,1,1) points:
# window 0: [(1, 1.0)]
# window 1: [(101, 2.0)]
# window 2: [
# (200, 4.0),
# (201, 8.0)
# ]
# window 3: [
# (299, 16.0),
# (300, 32.0),
# ]
# window 5: [(1000, 64.0)]
# window 4: [(12345, 128.0)]
>>> periodic_percentage_change_with_alignment.to_pandas()
                      timestamp  value
0 1970-01-01 00:00:00.000000050    0.0
1 1970-01-01 00:00:00.000000150    0.0
2 1970-01-01 00:00:00.000000250    1.0
3 1970-01-01 00:00:00.000000350    1.0
4 1970-01-01 00:00:00.000001050    0.0
5 1970-01-01 00:00:00.000012350    0.0