foundryts.functions.rolling_aggregate

foundryts.functions.rolling_aggregate(aggregate, window)

単一のtime seriesに対してロールウィンドウで値を集計する関数を返します。

ロールウィンドウとは、現在のタイムスタンプ（含む）で終了し、指定された期間（ウィンドウサイズ）をカバーするデータポイントの移動サブセットです。新しいデータポイントが追加されると、指定された期間外の古いポイントはウィンドウから外れます。

ロールウィンドウは、データのスムージング、トレンドの検出、time series分析におけるノイズの削減によく使用されます。

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

集計関数	説明
min	ウィンドウ内の最小値。
max	ウィンドウ内の最大値。
count	ウィンドウ内のポイント数。
sum	ウィンドウ内の値の合計。
product	ウィンドウ内の値の積。
mean	ウィンドウ内の値の平均。
standard_deviation	ウィンドウ内の値の標準偏差。
difference	ウィンドウ内の最初のポイントの値と最後のポイントの値の差を提供し、ウィンドウ内での相対的な変化を示します。
percent_change	ウィンドウ内の最初のポイントの値から最後のポイントの値までの変化率を提供し、ウィンドウ内での相対的な変化率を示します。
first	ウィンドウ内の最初の値。
last	ウィンドウ内の最後の値。

パラメーター:
- aggregate (str) – 適用する集計関数。上記の集計関数を参照してください。
- window (str | int | datetime.timedelta | pandas.Timedelta) – ロールウィンドウの期間で、任意の時点で評価されるポイントの数を決定します。たとえば、5msや5e6。
返り値: 単一のtime seriesを入力として受け取り、ロールウィンドウ内の各ポイントに対して指定された集計を計算する関数。
返り値の型: (FunctionNode) -> FunctionNode

データフレームスキーマ

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

例

Copied!1
2
3
4
5
6
>>> series = F.points(
...     (2, 10.0), (5, 20.0), (6, 30.0), (7, 40.0), (8, 50.0), (12, 60.0), name="series"
... )
# これは、Fモジュールのpointsメソッドを使用して、複数のデータポイントを含む時系列データを作成しています。
# 各タプルは(x, y)の形式で、xはポイントの位置、yはその位置での値を示します。
# 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

このコードは、seriesというデータをPandas DataFrameに変換する例です。to_pandas()メソッドを使用して、以下のようなタイムスタンプと値のペアを持つDataFrameに変換しています。タイムスタンプはナノ秒単位で表されており、valueはそれぞれの時点での数値データです。

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

このコードは、「difference」演算を3ナノ秒のウィンドウで適用するローリング集約を計算しています。rolling_differenceオブジェクトをPandasデータフレームに変換して表示しています。各行はタイムスタンプとその時点での値の差分を示しています。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
>>> rolling_percentage_change = F.rolling_aggregate("percent_change", "3ns")(series)
# "percent_change"という3ナノ秒のウィンドウでローリング集計を行っています。
>>> rolling_percentage_change.to_pandas()
# 結果を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
# 各行はタイムスタンプとその時点での変化率を示しています。