foundryts.functions.periodic_aggregate

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

離散的で定期的なウィンドウに対して単一のtime seriesを集約する関数を返します。

定期的なウィンドウはtime seriesを固定の期間で分割します。各ウィンドウに対して、集約関数がそのウィンドウ内のポイントに適用されます。その結果は、各ウィンドウの集約を表す値を持つtime seriesとなります。データポイントがないウィンドウは出力に含まれません。

このメソッドは、連続的なデータストリームから毎時、毎日、または毎週の要約を生成するなど、定期的な期間でデータを要約するのに便利です。

サポートされている集約関数:

集約関数	説明
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 , optional) –
  
  適用するウィンドウの種類（デフォルトは「end」）:
  
  start: ウィンドウは開始時に包含し、終了時に排他です。集約のタイムスタンプはウィンドウの開始です。 end: ウィンドウは開始時に排他で、終了時に包含です。集約のタイムスタンプはウィンドウの終了です。
- alignment_timestamp (str | float | datetime.datetime , optional) – 結果を整列させるために使用されるタイムスタンプで、結果のtime seriesの目盛りが整列タイムスタンプからウィンドウ期間の整数倍の位置にあるようにします（デフォルトは 0）。
戻り値: 単一のtime seriesを入力として受け取り、各定期ウィンドウの指定された集約を計算する関数。
戻り値の型: (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
22
23
24
25
26
27
28
29
>>> 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 関数を使ってポイントのシリーズを作成しています。
# 各ポイントはタプル (timestamp, value) で表されています。
# 例: (1, 1.0) はタイムスタンプ1で値が1.0です。

>>> series.to_pandas()
# 上記で作成したシリーズを Pandas DataFrame に変換しています。

                      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
# DataFrame の出力は、各行がタイムスタンプとその値を示しています。
# タイムスタンプはナノ秒単位で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") を使って、時間的なデータの差分を計算しています。デフォルトのウィンドウタイプは end です。結果は pandas の DataFrame 形式で表示され、各タイムスタンプに対応する差分値が示されています。

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つのウィンドウに分割され、それぞれのウィンドウには次のようなポイントが含まれています:
# ウィンドウ 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

このコードは、与えられたデータシリーズに対して100ナノ秒ごとにパーセンテージの変化を集計します。F.periodic_aggregate関数を使用し、デフォルトでウィンドウタイプは"end"に設定されています。各ウィンドウ内のポイントがリストされています。to_pandas()メソッドで、結果がPandas DataFrame形式で表示されます。最初のタイムスタンプで始まり、計算された変化率がvalueとして出力されます。

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

このコードは、時系列データに対して定期的な割合の変化を計算し、指定された時間間隔（100ナノ秒）ごとに集約を行います。F.periodic_aggregate関数を使用し、集約の種類を"percent_change"として指定し、結果をPandas DataFrameに変換しています。出力された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)
# (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

このコードは、percent_changeという関数を使って時系列データを100ナノ秒のウィンドウに分割し、各ウィンドウの変化率を計算しています。alignment_timestampとして50を指定しているため、ウィンドウの開始が50ナノ秒に合わせて調整されます。to_pandas()メソッドで結果をPandasのデータフレーム形式で表示しています。出力にはタイムスタンプとその時の変化率の値が含まれています。