foundryts.functions.interpolate

foundryts.functions.interpolate(before=None, internal=None, after=None, frequency=None, rename_columns_by=None, static_column_name=None)

1 つ以上のtime seriesを結合し、入力シリーズごとに列を持つ単一のtime seriesを返す関数を提供します。

↗ Interpolation は、他のseriesにポイントが存在するタイムスタンプについて、series内の欠落ポイントの値を推定します。関数は、構成された補間戦略を使用して、欠落ポイントがある入力seriesデータをリサンプリングし、整列します。

time seriesの補間は、3 つの異なる時間範囲に分けることができます: before、internal、after。

各時間範囲は、time series内の異なる部分の欠落値を補間します。

before: 補間されるseriesの最初のポイントより前のすべてのポイントを補間します。たとえば、以下のexternal_interpolated_seriesの例では、補間によってseries 2の最初のポイントの前に新しいポイントが作成され、最も近い値で埋められます。
internal: 補間されるtime series内の既存データポイント間の値を補間します。たとえば、以下のlinear_interpolated_seriesの例では、補間によって両seriesのtime_extent()内のポイントの値が推定されます。
after: 補間されるseriesの最後のデータポイントより後のすべてのポイントを補間します。たとえば、以下のexternal_interpolated_seriesの例では、補間によってseries 1の最後のポイントの後に新しいポイントが作成され、最も近い値で埋められます。

各seriesに異なる戦略を適用する場合、上記の時間範囲ごとに戦略をリストとして渡すことができます。リストの各要素は、対応する入力seriesに使用される戦略に対応しています。単一の戦略が渡された場合、すべての入力seriesに同じ戦略が適用されます。

内部補間にサポートされている補間戦略:

Strategy	Description
LINEAR	補間されるタイムスタンプの直前と直後の2ポイントの最適フィットラインを使用して線形補間を行います。
NEAREST	入力seriesの1つでタイムスタンプに最も近いポイントの値を使用します。
PREVIOUS	入力time seriesで定義された前のポイントの値を使用します。
NEXT	入力time seriesで次に発生するポイントの値を使用します。
NONE	補間をスキップします。入力seriesのいずれのポイントも存在しないタイムスタンプでは、出力dfにnull値が使用されます。

外部補間（before、after）にサポートされている補間戦略:

Strategy	Description
NEAREST	最初または最後のポイントのいずれかの定義されたポイントの値を取得します。
NONE (default)	最初のポイントの前や最後のポイントの後で補間を行わない。

指定された頻度でのみタイムスタンプを補間するために、オプションのfrequencyを設定できます。頻度を指定すると、入力seriesが完全にリサンプリングされ、指定された頻度でのみポイントが作成され、補間されます。リサンプリングされた出力の例については、以下のinterpolated_every_10ns_seriesおよびmultiple_interpolated_every_10ns_seriesの例を参照してください。

パラメーター:
- before (Union [str , List [str ] ] , optional) – seriesの最初のポイントの前のポイントを補間するための戦略で、シリーズごとにリストにすることができ、上記の外部補間表から有効な戦略を使用します（デフォルトはNONE）。
- internal (Union [str , List [str ] ] , optional) – 既存のポイント間のポイントを補間するための戦略で、シリーズごとにリストにすることができ、上記の内部補間表から有効な値を使用します（デフォルトはNONE）。
- after (Union [str , List [str ] ] , optional) – seriesの最初のポイントの後のポイントを補間するための戦略で、シリーズごとにリストにすることができ、上記の外部補間表から有効な戦略を使用します（デフォルトはNONE）。
- frequency (Union [str , pandas.Timedelta ] , optional) – 補間されたポイントの出力頻度で、値はそれぞれのヘルツとして処理されます。たとえば、'5ms'、'1s'（デフォルトは固定頻度なしで、他のseriesに存在するタイムスタンプのみが補間されます）
- rename_columns_by (str | Callable [ *[*N.FunctionNode ] , str ] , optional) – 結果でseries列を識別するためのメタデータキー、または各seriesの名前を返す呼び出し可能なもの（デフォルトはseries識別子です）。
- static_column_name (str , optional) – 値の列の静的な名前で、rename_columns_byを上書きします。
戻り値: 構成された戦略を使用して補間されたseriesを返す関数。
戻り値の型: (Union[FunctionNode, NodeCollections]) -> Union[FunctionNode, NodeCollection]

データフレームスキーマ

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

注意

enum seriesにLINEAR補間を使用しないでください。この操作は失敗します。

この関数の出力は単一シリーズまたは複数シリーズのデータフレームであり、他の関数が期待する対応する入力としか動作しません。

例

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
>>> series_1 = F.points((1, 1.0), (101, 2.0), (200, 4.0), (201, 8.0), name="series-1")
>>> series_2 = F.points((2, 11.0), (102, 12.0), (201, 14.0), (202, 18.0), name="series-2")
>>> series_1.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
>>> series_2.to_pandas()
                    timestamp  value
0 1970-01-01 00:00:00.000000002   11.0
1 1970-01-01 00:00:00.000000102   12.0
2 1970-01-01 00:00:00.000000201   14.0
3 1970-01-01 00:00:00.000000202   18.0
>>> nc = NodeCollection([series_1, series_2])

Copied!1
2
3
4
5
# series_1 に (1, 1.0), (101, 2.0), (200, 4.0), (201, 8.0) のポイントを追加し、"series-1" という名前を付けます。
# series_2 に (2, 11.0), (102, 12.0), (201, 14.0), (202, 18.0) のポイントを追加し、"series-2" という名前を付けます。
# series_1 を pandas の DataFrame に変換します。
# series_2 を pandas の DataFrame に変換します。
# series_1 と series_2 を NodeCollection に追加します。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
>>> linear_interpolated_series = F.interpolate(internal="LINEAR")(nc)
# 線形補間を使用して、欠損しているデータポイントを補完します。

>>> linear_interpolated_series.to_pandas()
# 補間されたデータをPandasのデータフレームとして表示します。
                    timestamp  series-1   series-2
0 1970-01-01 00:00:00.000000001  1.000000        NaN
1 1970-01-01 00:00:00.000000002  1.010000  11.000000
2 1970-01-01 00:00:00.000000101  2.000000  11.990000
3 1970-01-01 00:00:00.000000102  2.020202  12.000000
4 1970-01-01 00:00:00.000000200  4.000000  13.979798
5 1970-01-01 00:00:00.000000201  8.000000  14.000000
6 1970-01-01 00:00:00.000000202       NaN  18.000000
# series-1およびseries-2に対する線形補間の結果を示しています。
# timestampは各行のタイムスタンプで、series-1とseries-2は補間されたデータです。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
>>> nearest_interpolated_series = F.interpolate(internal="NEAREST")(nc)
# NEAREST（最近傍）補間を用いて系列データを補間しています。
>>> nearest_interpolated_series.to_pandas()
# 補間されたデータをPandasデータフレームに変換して表示しています。
                    timestamp  series-1  series-2
0 1970-01-01 00:00:00.000000001       1.0       NaN
1 1970-01-01 00:00:00.000000002       1.0      11.0
2 1970-01-01 00:00:00.000000101       2.0      12.0
3 1970-01-01 00:00:00.000000102       2.0      12.0
4 1970-01-01 00:00:00.000000200       4.0      14.0
5 1970-01-01 00:00:00.000000201       8.0      14.0
6 1970-01-01 00:00:00.000000202       NaN      18.0
# 各タイムスタンプに対応する補間後のデータが表示されています。
# 'series-1' と 'series-2' は補間された系列データの列です。
# NaN はその位置にデータがないことを示しています。

Copied!1
2
3
4
5
6
7
8
9
10
>>> previous_interpolated_series = F.interpolate(internal="PREVIOUS")(nc)
>>> previous_interpolated_series.to_pandas()
                    timestamp  series-1  series-2
0 1970-01-01 00:00:00.000000001       1.0       NaN
1 1970-01-01 00:00:00.000000002       1.0      11.0
2 1970-01-01 00:00:00.000000101       2.0      11.0
3 1970-01-01 00:00:00.000000102       2.0      12.0
4 1970-01-01 00:00:00.000000200       4.0      12.0
5 1970-01-01 00:00:00.000000201       8.0      14.0
6 1970-01-01 00:00:00.000000202       NaN      18.0

このコードは、時間に基づいてデータを補間するためのものです。F.interpolate(internal="PREVIOUS")を用いることで、欠損値に対して「直前の値」を使用して補間を行います。データをPandasのDataFrame形式に変換して表示しています。series-1とseries-2のカラムには、NaN（欠損値）がある場合、直前のタイムスタンプの値が使用されています。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
>>> next_interpolated_series = F.interpolate(internal="NEXT")(nc)
# データの補間を行う関数F.interpolateを使用して、データセット'nc'に対して'NEXT'法で補間を実施
>>> next_interpolated_series.to_pandas()
# 補間された結果をPandas DataFrame形式で表示
                    timestamp  series-1  series-2
0 1970-01-01 00:00:00.000000001       1.0       NaN
# 初期タイムスタンプにおける'series-1'の値は1.0で、'series-2'は欠損値
1 1970-01-01 00:00:00.000000002       2.0      11.0
# タイムスタンプ000000002では'series-1'は2.0、'series-2'は11.0
2 1970-01-01 00:00:00.000000101       2.0      12.0
# タイムスタンプ000000101では'series-1'は前の値を保持し2.0、'series-2'は12.0
3 1970-01-01 00:00:00.000000102       4.0      12.0
# タイムスタンプ000000102では'series-1'は4.0に更新、'series-2'は前の値を保持し12.0
4 1970-01-01 00:00:00.000000200       4.0      14.0
# タイムスタンプ000000200では'series-1'は4.0を保持、'series-2'は14.0に更新
5 1970-01-01 00:00:00.000000201       8.0      14.0
# タイムスタンプ000000201では'series-1'は8.0に更新、'series-2'は前の値を保持し14.0
6 1970-01-01 00:00:00.000000202       NaN      18.0
# タイムスタンプ000000202では'series-1'は欠損値、'series-2'は18.0に更新

Copied!1
2
3
4
5
6
7
8
9
10
>>> none_interpolated_series = F.interpolate(internal="NONE")(nc) # 欠損値を無視した系列の補間を行わない
>>> none_interpolated_series.to_pandas()
                    timestamp  series-1  series-2
0 1970-01-01 00:00:00.000000001       1.0       NaN
1 1970-01-01 00:00:00.000000002       NaN      11.0
2 1970-01-01 00:00:00.000000101       2.0       NaN
3 1970-01-01 00:00:00.000000102       NaN      12.0
4 1970-01-01 00:00:00.000000200       4.0       NaN
5 1970-01-01 00:00:00.000000201       8.0      14.0
6 1970-01-01 00:00:00.000000202       NaN      18.0

上記のコードは、欠損値（NaN）を無視して補間を行わない設定でデータを処理しています。データがそのままの形で出力され、欠損値は埋められません。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
>>> external_interpolated_series = F.interpolate(before="NEAREST", after="NEAREST")(nc)
# interpolate関数を使用して、欠損値を補完しています。
# "before"と"after"の両方に"NEAREST"を指定しており、前後の最も近い値を用いて補完を行います。

>>> external_interpolated_series.to_dataframe()
# データフレームに変換して表示します。
                    timestamp  series-1  series-2
0 1970-01-01 00:00:00.000000001       1.0      11.0
1 1970-01-01 00:00:00.000000002       NaN      11.0  # 欠損値
2 1970-01-01 00:00:00.000000101       2.0       NaN  # 欠損値
3 1970-01-01 00:00:00.000000102            12.0  # series-1に欠損値
4 1970-01-01 00:00:00.000000200       4.0       NaN  # 欠損値
5 1970-01-01 00:00:00.000000201       8.0      14.0
6 1970-01-01 00:00:00.000000202       8.0      18.0
# タイムスタンプに対応する各シリーズの値が表示され、いくつかの行には欠損値（NaN）が存在します。

Copied!1
2
3
4
5
6
7
8
9
10
>>> interpolated_series = F.interpolate(internal=["LINEAR", "NONE"])(nc) # 各シリーズに対して異なる補間戦略を適用
>>> interpolated_series.to_pandas()
                    timestamp  series-1  series-2
0 1970-01-01 00:00:00.000000001  1.000000       NaN
1 1970-01-01 00:00:00.000000002  1.010000      11.0
2 1970-01-01 00:00:00.000000101  2.000000       NaN
3 1970-01-01 00:00:00.000000102  2.020202      12.0
4 1970-01-01 00:00:00.000000200  4.000000       NaN
5 1970-01-01 00:00:00.000000201  8.000000      14.0
6 1970-01-01 00:00:00.000000202       NaN      18.0

このコードでは、F.interpolate 関数を使用して、データシリーズに異なる補間戦略を適用しています。series-1 には線形補間 (LINEAR) が適用され、series-2 には補間が行われていません (NONE)。結果は Pandas のデータフレーム形式で出力されます。

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
>>> interpolated_every_10ns_series = F.interpolate(internal="NEAREST", frequency="10ns")(series_1)
# "NEAREST" 法を使用して、10ナノ秒間隔で補間を行います
>>> interpolated_every_10ns_series.to_pandas()
# 補間されたデータを Pandas DataFrame に変換して表示します
                        timestamp  series-1
0  1970-01-01 00:00:00.000000010       1.0
1  1970-01-01 00:00:00.000000020       1.0
2  1970-01-01 00:00:00.000000030       1.0
3  1970-01-01 00:00:00.000000040       1.0
4  1970-01-01 00:00:00.000000050       1.0
5  1970-01-01 00:00:00.000000060       2.0
6  1970-01-01 00:00:00.000000070       2.0
7  1970-01-01 00:00:00.000000080       2.0
8  1970-01-01 00:00:00.000000090       2.0
9  1970-01-01 00:00:00.000000100       2.0
10 1970-01-01 00:00:00.000000110       2.0
11 1970-01-01 00:00:00.000000120       2.0
12 1970-01-01 00:00:00.000000130       2.0
13 1970-01-01 00:00:00.000000140       2.0
14 1970-01-01 00:00:00.000000150       2.0
15 1970-01-01 00:00:00.000000160       4.0
16 1970-01-01 00:00:00.000000170       4.0
17 1970-01-01 00:00:00.000000180       4.0
18 1970-01-01 00:00:00.000000190       4.0
19 1970-01-01 00:00:00.000000200       4.0

このコードは、series_1 という時系列データを 10ナノ秒間隔で補間し、補間後のデータを表示しています。NEAREST 法により、最も近い値で補間を行います。

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
>>> multiple_interpolated_every_10ns_series = F.interpolate(
...     internal="NEAREST", frequency="10ns"
... )(nc)
# `F.interpolate` 関数を使用して、10ナノ秒ごとに補間を行う。
# `internal="NEAREST"` は最近傍補間を指定している。
>>> multiple_interpolated_every_10ns_series.to_pandas()
# 結果をPandasのデータフレームに変換して出力する。
                       timestamp  series-1  series-2
0  1970-01-01 00:00:00.000000010       1.0      11.0
1  1970-01-01 00:00:00.000000020       1.0      11.0
2  1970-01-01 00:00:00.000000030       1.0      11.0
3  1970-01-01 00:00:00.000000040       1.0      11.0
4  1970-01-01 00:00:00.000000050       1.0      11.0
5  1970-01-01 00:00:00.000000060       2.0      12.0
6  1970-01-01 00:00:00.000000070       2.0      12.0
7  1970-01-01 00:00:00.000000080       2.0      12.0
8  1970-01-01 00:00:00.000000090       2.0      12.0
9  1970-01-01 00:00:00.000000100       2.0      12.0
10 1970-01-01 00:00:00.000000110       2.0      12.0
11 1970-01-01 00:00:00.000000120       2.0      12.0
12 1970-01-01 00:00:00.000000130       2.0      12.0
13 1970-01-01 00:00:00.000000140       2.0      12.0
14 1970-01-01 00:00:00.000000150       2.0      12.0
15 1970-01-01 00:00:00.000000160       4.0      14.0
16 1970-01-01 00:00:00.000000170       4.0      14.0
17 1970-01-01 00:00:00.000000180       4.0      14.0
18 1970-01-01 00:00:00.000000190       4.0      14.0
19 1970-01-01 00:00:00.000000200       4.0      14.0

このコードは、指定された周波数（10ナノ秒）での時間補間を行い、結果をPandasのデータフレーム形式で出力しています。補間方法には「最近傍法」が使用されています。