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	各周期ウィンドウ内の最後の値。
`time_weighted("average")`	各周期ウィンドウ内の値の時間加重平均です。各値が有効な期間で重み付けされます。積分方法と境界の補間オプションについては、`time_weighted()` を参照してください。
`time_weighted("integral")`	各周期ウィンドウ内の曲線下の面積です。積分方法と境界の補間オプションについては、`time_weighted()` を参照してください。

パラメーター：
- aggregate (str または time_weighted() が返す値) – 適用する集計です。上記の集計関数テーブルから有効な選択肢を使用します。
- window (int , datetime.timedelta , str) – 各周期ウィンドウの長さです（例：5ms または 5e6）。
- window_type (str , 任意) –
  
  適用するウィンドウの種類です（デフォルトは「end」）。
  
  start: ウィンドウは開始時点を含み、終了時点を含みません。集計のタイムスタンプはウィンドウの開始時点です。 end: ウィンドウは開始時点を含まず、終了時点を含みます。集計のタイムスタンプはウィンドウの終了時点です。
- alignment_timestamp (str | float | datetime.datetime , 任意) – 結果を揃えるために使用するタイムスタンプです。結果の時系列の目盛りは、このタイムスタンプからウィンドウの長さの整数倍だけ離れた位置に配置されます（デフォルトは0）。
戻り値： 単一の時系列を入力として受け取り、各周期ウィンドウに対して指定された集計を計算する関数です。
戻り値の型： (FunctionNode) -> FunctionNode

Dataframe スキーマ

列名	データ型	説明
timestamp	pandas.Timestamp	データポイントのタイムスタンプ
value	Union[float, str]	データポイントの値

例

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 のデフォルトは end です
# (1,2,3,1,1) 個の点を含む5個のウィンドウ：
# ウィンドウ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

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 です
# (1,2,3,1,1) 個の点を含む5個のウィンドウ：
# ウィンドウ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

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)
# (1,1,3,1,1,1) 個の点を含む6個のウィンドウ：
# ウィンドウ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

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)
# (1,1,2,2,1,1) 個の点を含む6個のウィンドウ：
# ウィンドウ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

←

PREVIOUSfunctions.mean

NEXTfunctions.points

→