foundryts.functions.time_weighted

foundryts.functions.time_weighted(aggregate, method='linear', bounds_interpolation=None)

cumulative_aggregate()、 rolling_aggregate()、 periodic_aggregate() などの集計関数に aggregate 引数として渡せる時間加重集計の仕様を返します。

すべての点に同じ重みを付ける標準的な集計とは異なり、時間加重集計では、隣接する点の間の線分を積分することで、各点の値が有効である期間に応じて重みを付けます。これは、センサーの測定値や次の更新まで保持されるステータス値など、不規則な間隔でサンプリングされた時系列に適した選択です。

サポートされている時間加重集計：

集計	説明
`average`	各値が有効である期間で重み付けした、範囲全体にわたる時系列の平均値です。曲線下の面積を範囲の期間で割った値に相当します。
`integral`	指定された積分 `method` を使用して計算した、範囲全体にわたる曲線下の面積です。

サポートされている積分方法（method）：

方法	説明
`lhs`（左端和）	次の点が現れるまで、前の点の値を一定に保持します。各点が、そのタイムスタンプから始まる値を表す場合に、このオプションを使用します。
`linear`（台形則）	隣接する点を直線で結び、その結果できる台形を積分します。元の値がサンプル間で滑らかに変化する場合に、このオプションを使用します。これがデフォルトです。
`rhs`（右端和）	後の点の値を、前の点までさかのぼって一定に保持します。各点が、そのタイムスタンプで終わる値を表す場合に、このオプションを使用します。

境界の補間オプション（bounds_interpolation）：

デフォルト（None）では、範囲内にあるデータ点の間の面積のみが集計に寄与します。範囲の境界と、その境界に最も近い範囲内の点との間の空白は無視されます。そのため、範囲の境界が時系列のサンプリングタイムスタンプと一致しない場合、集計値が過小になることがあります。

bounds_interpolation を指定すると、選択した方式を使用して曲線が範囲の境界まで延長されます。各方式が既知の点の間の値をどのように推定するかについては、時系列の補間を参照してください。

値	説明
`default`	デフォルトの補間方式を使用します。数値時系列には `linear`、`enum` 時系列には `previous` を使用します。
`linear`	範囲外の点と、それに最も近い範囲内の点との間を線形補間して、境界での値を求めます。
`nearest`	境界の前後で最も近い点の値を使用します。
`next`	次の点の値を使用し、境界までさかのぼって一定に保持します。
`none`	外挿しません。`None`（デフォルト）を渡すことと同じです。
`previous`	前の点の値を使用し、境界まで一定に保持します。

パラメーター：
- aggregate (str) – 計算する時間加重集計です。average または integral を指定します。
- method (str , 任意) – 隣接する点の間の面積の計算に使用する積分方法です。lhs、linear、rhs のいずれかを指定します（デフォルトは linear）。
- bounds_interpolation (str , 任意) – 集計を計算する際に、曲線を範囲の境界まで延長するために使用する補間方式です。default、linear、nearest、next、none、previous のいずれかを指定します。None（デフォルト）の場合、外挿は行われません。
戻り値： cumulative_aggregate()、 rolling_aggregate()、 periodic_aggregate() などの集計関数に aggregate 引数として渡せる TimeWeightedSpec 集計仕様です。

例

Copied!1
2
3
4
5
6
7
8
>>> series = F.points(
...     (1, 5.0), (3, 15.0), (6, 30.0), name="series"
... )
>>> series.to_pandas()
                      timestamp  value
0 1970-01-01 00:00:00.000000001    5.0
1 1970-01-01 00:00:00.000000003   15.0
2 1970-01-01 00:00:00.000000006   30.0

デフォルトの線形積分方法を使用した累積時間加重平均です。t=1 では、結果は最初の点の値だけです。t=3 では、t=1 と t=3 の間隔が 2 ns であるため、累積平均ではこれらの値に同じ重みが付けられます。t=6 では、値 30.0 までの間隔が 3 ns と長いため、平均値が引き上げられます。

Copied!1
2
3
4
5
6
>>> twa = F.cumulative_aggregate(F.time_weighted("average"))(series)
>>> twa.to_pandas()
                      timestamp  value
0 1970-01-01 00:00:00.000000001    5.0
1 1970-01-01 00:00:00.000000003   10.0
2 1970-01-01 00:00:00.000000006   17.5

5 ns のウィンドウで右端和の積分方法を使用して計算したローリング積分です。出力値の単位は value × seconds であるため、科学表記法で表示されます。t=1 では、ウィンドウに点が1個しかないため、積分するものがありません。t=3 では、ウィンドウに (1, 5.0) と (3, 15.0) が含まれ、RHS 法では後の値 15.0 が 2 ns の間隔全体で一定に保持されるため、15 × 2ns = 3e-08 になります。t=6 では、t=1 の点がウィンドウから外れ、(3, 15.0) と (6, 30.0) が残ります。RHS 法では 30.0 が 3 ns の間隔全体で一定に保持されるため、30 × 3ns = 9e-08 になります。

Copied!1
2
3
4
5
6
7
8
>>> rolling_integral = F.rolling_aggregate(
...     F.time_weighted("integral", method="rhs"), "5ns"
... )(series)
>>> rolling_integral.to_pandas()
                      timestamp         value
0 1970-01-01 00:00:00.000000001  0.000000e+00
1 1970-01-01 00:00:00.000000003  3.000000e-08
2 1970-01-01 00:00:00.000000006  9.000000e-08

2 ns のウィンドウで計算する周期的な時間加重平均です。各ウィンドウの境界の値は、周囲の点から線形補間されます。t=2 で終わるウィンドウには、点 (1, 5.0) のみが含まれます。t=2 の境界値は、(1, 5.0) と (3, 15.0) の間で 10.0 に補間され、台形の平均は 7.5 になります。t=4 で終わるウィンドウでは、両方の境界が補間されます。t=2 は 10.0 に、t=4 は 20.0 に補間され、2 ns のウィンドウ全体にわたる線形曲線の平均は 15.0 になります。t=6 で終わるウィンドウでは、左の境界 t=4 が 20.0 に補間され、右の境界は実際の点 (6, 30.0) であるため、平均は 25.0 になります。

Copied!1
2
3
4
5
6
7
8
>>> periodic_twa = F.periodic_aggregate(
...     F.time_weighted("average", bounds_interpolation="linear"), "2ns"
... )(series)
>>> periodic_twa.to_pandas()
                      timestamp  value
0 1970-01-01 00:00:00.000000002    7.5
1 1970-01-01 00:00:00.000000004   15.0
2 1970-01-01 00:00:00.000000006   25.0

←

PREVIOUSfoundryts.functions.time_shift

NEXTfoundryts.functions.timestamp_scale

→