foundryts.functions.periodic_aggregate

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

返回一个函数，该函数在单个时间序列中以离散、周期性窗口进行值的聚合。

周期性窗口将时间序列划分为固定持续时间的窗口。对于每个窗口，应用一个聚合函数到该窗口内的点。结果是一个时间序列，其值代表每个窗口的聚合。没有数据点的窗口不会包含在输出中。

此方法对于总结定期数据非常有用，例如从连续的数据流生成每小时、每天或每周的汇总。

支持的聚合函数：

聚合函数	描述
min	每个周期性窗口内的最小值。
max	每个周期性窗口内的最大值。
count	每个周期性窗口内的点计数。
sum	每个周期性窗口内的值之和。
product	每个周期性窗口内的值的乘积。
mean	每个周期性窗口内的平均值。
standard_deviation	每个周期性窗口内的标准差。
difference	当前周期性窗口的第一个点的值与最后一个点的值之间的差异，提供固定窗口的相对更改。
percent_change	从每个周期性窗口内的第一个点的值到最后一个点的值的百分比变化，提供固定窗口内的相对变化率。
first	每个周期性窗口内的第一个值。
last	每个周期性窗口内的最后一个值。

参数:
- aggregate (str) – 要应用的聚合函数，请使用上面 聚合函数 表中的有效选项。
- window (int , datetime.timedelta , str) – 每个周期性窗口的持续时间，例如 5ms 或 5e6。
- window_type (str , 非必填) –
  
  要应用的窗口类型（默认为“end”）：
  
  start: 窗口在开始时是包含的，结束时是排除的。聚合的时间戳是窗口的开始。 end: 窗口在开始时是排除的，结束时是包含的。聚合的时间戳是窗口的结束。
- alignment_timestamp (str | float | datetime.datetime , 非必填) – 用于对齐结果的时间戳，使得结果时间序列中的刻度位于从对齐时间戳起的窗口持续时间的整数倍位置（默认为 0）。
返回: 一个函数，该函数将单个时间序列作为输入并计算指定的聚合以用于每个周期性窗口。
返回类型: (FunctionNode) -> FunctionNode

数据框架模式

列名	类型	描述
timestamp	pandas.Timestamp	点的时间戳
value	Union[float, str]	点的值

另请参见

cumulative_aggregate(), rolling_aggregate()

注意

此函数仅适用于数值序列。

示例

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
25
26
27
28
>>> 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",
... )
# 使用 F.points 创建一个时间序列数据，其中包含时间戳和对应的数值。
# 参数列表中，每个元组的第一个元素是时间戳（整型），第二个元素是数值（浮点型）。
# 该时间序列的名称为 "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
# 使用 to_pandas() 方法将时间序列转换为 Pandas DataFrame 格式。
# 输出的 DataFrame 包含两个列：timestamp（时间戳）和 value（数值）。
# 时间戳以纳秒为单位自 Unix 时间（1970年1月1日）开始计时。

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 默认是 end
# 5 个窗口分别包含 (1,2,3,1,1) 个点：
# 窗口 1: [(1, 1.0)]
# 窗口 2: [
# (101, 2.0),
# (200, 4.0)
# ]
# 窗口 3: [
# (201, 8.0),
# (200, 16.0),
# (300. 32.0)
# ]
# 窗口 4: [(1000, 64.0)]
# 窗口 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

上述代码中，F.periodic_aggregate("difference", "100ns") 函数用于对数据进行周期性差分聚合操作，series 是输入的数据序列。to_pandas() 方法将结果转换为 pandas 数据框格式。每个窗口内数据点的个数以及聚合结果被注释详细说明。

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 默认为 end
# 5 个窗口，分别包含 (1,2,3,1,1) 个点：
# 窗口 1: [(1, 1.0)]
# 窗口 2: [
# (101, 2.0),
# (200, 4.0)
# ]
# 窗口 3: [
# (201, 8.0),
# (200, 16.0),
# (300. 32.0)
# ]
# 窗口 4: [(1000, 64.0)]
# 窗口 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

这里的代码使用 F.periodic_aggregate 函数来计算每个窗口的百分比变化（percent_change），窗口长度为 100 纳秒（100ns）。to_pandas() 方法用于将结果转换为 Pandas DataFrame 格式。每个窗口中的变化按时间戳记录。

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个窗口，包含 (1,1,3,1,1,1) 个点：
# 窗口0: [(1, 1.0)]
# 窗口1: [(101, 2.0)]
# 窗口2: [
# (200, 4.0),
# (201, 8.0),
# (299, 16.0)
# ]
# 窗口3: [(300, 32.0)]
# 窗口4: [(1000, 64.0)]
# 窗口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

在这段代码中，F.periodic_aggregate 函数被用于计算一个时间序列中各个窗口的百分比变化。这里使用了 "100ns" 的时间窗口，从每个窗口的开始时间进行计算。最终结果被转换为 Pandas DataFrame 格式，以便于进一步的数据分析和处理。

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个窗口，每个窗口中包含的点数分别为(1,1,2,2,1,1)：
# 窗口 0: [(1, 1.0)]
# 窗口 1: [(101, 2.0)]
# 窗口 2: [
# (200, 4.0),
# (201, 8.0)
# ]
# 窗口 3: [
# (299, 16.0),
# (300, 32.0),
# ]
# 窗口 5: [(1000, 64.0)]
# 窗口 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

该代码段使用 F.periodic_aggregate 函数对 series 进行周期性百分比变化计算，窗口大小为100纳秒，并从50纳秒处对齐。每个窗口中包含的数据点数不同，计算结果通过 .to_pandas() 方法转换为 Pandas DataFrame 格式，显示时间戳和对应的计算值。

←

PREVIOUSfoundryts.functions.mean

NEXTfoundryts.functions.points

→