開発者ツールチェーンFoundryTSAPI リファレンスNodeCollection

注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。

foundryts.NodeCollection

クラス foundryts.NodeCollection(*nodes, **kwargs)

FunctionNode または SummarizerNode のコレクションです。

NodeCollection は反復可能なオブジェクトで、複数の時系列を受け取る関数に渡したり、コレクション内の各ノードを関数にマッピングしたりできます。

生の系列およびポイントセットの場合、NodeCollection のデータフレームには、ポイントが属する系列を示す series という追加の列が含まれます。series の値は、時系列の同期で設定された系列ID、または foundryts.functions.points() のエイリアスで設定された系列IDになります。

注

単一の入力時系列を受け取る関数に NodeCollection を直接渡さないでください。操作でエラーが発生します。ノードのすべての要素に同じ関数を適用するには、 NodeCollection.map() を使用します。このメソッドは、変換されたポイントまたは概要を、最終的なデータフレーム内の系列にマッピングします。関数の入力数を確認するには、FoundryTS 関数のドキュメントを参照してください。

例

Copied!1
2
3
4
5
6
7
8
9
10
11
12
>>> series_1 = F.points((1, 100.0), (2, 200.0), (3, 300.0), name="series-1")
>>> series_1.to_pandas()
                      timestamp  value
0 1970-01-01 00:00:00.000000001  100.0
1 1970-01-01 00:00:00.000000002  200.0
2 1970-01-01 00:00:00.000000003  300.0
>>> series_2 = F.points((1, 200.0), (2, 400.0), (3, 600.0), name="series-2")
>>> series_2.to_pandas()
                      timestamp  value
0 1970-01-01 00:00:00.000000001  200.0
1 1970-01-01 00:00:00.000000002  400.0
2 1970-01-01 00:00:00.000000003  600.0

Copied!1
2
3
4
5
6
7
8
9
>>> nc = NodeCollection([series_1, series_2])
>>> nc.to_pandas()
     series                     timestamp  value
0  series-1 1970-01-01 00:00:00.000000001  100.0
1  series-1 1970-01-01 00:00:00.000000002  200.0
2  series-1 1970-01-01 00:00:00.000000003  300.0
3  series-2 1970-01-01 00:00:00.000000001  200.0
4  series-2 1970-01-01 00:00:00.000000002  400.0
5  series-2 1970-01-01 00:00:00.000000003  600.0

Copied!1
2
3
4
5
6
>>> scatter_plt = F.scatter()(nc) # scatter() は入力時系列をちょうど2個使用します
>>> scatter_plt.to_pandas()
   is_truncated  points.first_value  points.second_value              points.timestamp
0         False               100.0                200.0 1970-01-01 00:00:00.000000001
1         False               200.0                400.0 1970-01-01 00:00:00.000000002
2         False               300.0                600.0 1970-01-01 00:00:00.000000003

Copied!1
2
3
4
5
6
7
8
9
10
>>> scaled_nc = F.scale(10)(nc) # エラー - scale() は単一の入力系列に対して動作します
>>> scaled_nc = nc.map(F.scale(10)) # 正常 - 集合内の各系列を scale() の結果にマッピングしています
>>> scaled_nc.to_pandas()
     series                     timestamp   value
0  series-1 1970-01-01 00:00:00.000000001  1000.0
1  series-1 1970-01-01 00:00:00.000000002  2000.0
2  series-1 1970-01-01 00:00:00.000000003  3000.0
3  series-2 1970-01-01 00:00:00.000000001  2000.0
4  series-2 1970-01-01 00:00:00.000000002  4000.0
5  series-2 1970-01-01 00:00:00.000000003  6000.0

columns()

このコレクションをデータフレームとして評価したときに生成される pandas.DataFrame の列名を表す文字列のタプルを返します。

注

ネストされたオブジェクトのキーは、ネストされたキーを . で結合したタプルにフラット化されます。

構造が均一でないコレクションには、コレクション内の各要素のすべての列の和集合が含まれます。

戻り値： コレクションを評価した結果のデータフレームの列名を含むタプル。
戻り値の型： Tuple[str]

例

Copied!1
2
>>> series_1 = F.points((1, 100.0), (2, 200.0), (3, 300.0), name="series-1")
>>> series_2 = F.points((1, 200.0), (2, 400.0), (3, 600.0), name="series-2")

Copied!1
2
3
>>> nc = NodeCollection(series_1, series_2)
>>> nc.columns() # series 列が追加されていることに注目してください
('series', 'timestamp', 'value')

Copied!1
2
3
4
>>> dist = F.distribution()(nc)
>>> dist.columns()
('delta', 'distribution_values.count', 'distribution_values.end', 'distribution_values.start',
'end', 'end_timestamp', 'start', 'start_timestamp')

Copied!1
2
3
4
5
6
>>> mixed_nc = NodeCollection([F.distribution()(series_1), F.statistics()(series_2)])
('series', 'delta', 'distribution_values.count', 'distribution_values.end',
'distribution_values.start', 'end', 'end_timestamp', 'start', 'start_timestamp',
'count', 'earliest_point.timestamp', 'earliest_point.value', 'largest_point.timestamp',
'largest_point.value', 'latest_point.timestamp', 'latest_point.value', 'mean', 'smallest_point.timestamp',
'smallest_point.value')

map(func)

コレクション内の各時系列を、入力関数の出力にマッピングします。

時系列のコレクションに同じクエリをまとめて適用する場合に便利です。

パラメーター： func ( ( ) -> FunctionNode | SummarizerNode) – コレクション内の各時系列に適用する、FoundryTS でサポートされている関数。
戻り値： 各項目が func の適用による対応する出力にマッピングされた、更新後の NodeCollection。
戻り値の型： Iterable[NodeCollection]

関連項目

NodeCollection.map_intervals()

例

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
>>> series_1 = F.points((1, 100.0), (2, 200.0), (3, 300.0), name="series-1")
>>> series_1.to_pandas()
                    timestamp  value
0 1970-01-01 00:00:00.000000001  100.0
1 1970-01-01 00:00:00.000000002  200.0
2 1970-01-01 00:00:00.000000003  300.0
>>> series_2 = F.points((1, 200.0), (2, 400.0), (3, 600.0), name="series-2")
>>> series_2.to_pandas()
                    timestamp  value
0 1970-01-01 00:00:00.000000001  200.0
1 1970-01-01 00:00:00.000000002  400.0
2 1970-01-01 00:00:00.000000003  600.0
>>> nc = NodeCollection([series_1, series_2])

Copied!1
2
3
4
5
6
7
8
9
>>> scaled_nc = nc.map(F.scale(10))
>>> scaled_nc.to_pandas()
     series                     timestamp   value
0  series-1 1970-01-01 00:00:00.000000001  1000.0
1  series-1 1970-01-01 00:00:00.000000002  2000.0
2  series-1 1970-01-01 00:00:00.000000003  3000.0
3  series-2 1970-01-01 00:00:00.000000001  2000.0
4  series-2 1970-01-01 00:00:00.000000002  4000.0
5  series-2 1970-01-01 00:00:00.000000003  6000.0

Copied!1
2
3
4
5
6
7
8
9
>>> mapped_summary_nc = nc.map(F.distribution())
>>> mapped_summary_nc.to_pandas()
     series  delta  distribution_values.count  distribution_values.end  distribution_values.start    end end_timestamp  start               start_timestamp
0  series-1   20.0                          1                    120.0                      100.0  300.0    2262-01-01  100.0 1677-09-21 00:12:43.145225216
1  series-1   20.0                          1                    200.0                      180.0  300.0    2262-01-01  100.0 1677-09-21 00:12:43.145225216
2  series-1   20.0                          1                    300.0                      280.0  300.0    2262-01-01  100.0 1677-09-21 00:12:43.145225216
3  series-2   40.0                          1                    240.0                      200.0  600.0    2262-01-01  200.0 1677-09-21 00:12:43.145225216
4  series-2   40.0                          1                    400.0                      360.0  600.0    2262-01-01  200.0 1677-09-21 00:12:43.145225216
5  series-2   40.0                          1                    600.0                      560.0  600.0    2262-01-01  200.0 1677-09-21 00:12:43.145225216

map_intervals(intervals, interval_name=None)

区間を使用して、コレクション内のすべての時系列に時間範囲を作成します。

各区間は、入力時系列に foundryts.functions.time_range() を作成するために使用され、さらに変換や分析を行うことができます。これは、Interval を手動で作成する場合、または foundryts.functions.time_range() の結果を Interval に変換して作成する場合に最適です。

結果のデータフレームには、interval.start および interval.end の追加の列が含まれます。

パラメーター：
- intervals (Interval | List [Interval ]) – コレクション内のすべての時系列に時間範囲を作成するための1個以上の区間。
- interval_name (str , 任意) – データフレーム内の区間の列に使用する任意のエイリアス。
戻り値： 各項目が func の適用による対応する出力にマッピングされた、更新後の NodeCollection。
戻り値の型： Iterable[NodeCollection]

例

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
>>> series_1 = F.points((1, 100.0), (2, 200.0), (3, 300.0), name="series-1")
>>> series_1.to_pandas()
                      timestamp  value
0 1970-01-01 00:00:00.000000001  100.0
1 1970-01-01 00:00:00.000000002  200.0
2 1970-01-01 00:00:00.000000003  300.0
>>> series_2 = F.points((1, 200.0), (2, 400.0), (3, 600.0), name="series-2")
>>> series_2.to_pandas()
                      timestamp  value
0 1970-01-01 00:00:00.000000001  200.0
1 1970-01-01 00:00:00.000000002  400.0
2 1970-01-01 00:00:00.000000003  600.0
>>> nc = NodeCollection([series_1, series_2])
>>> from foundryts.core.interval import Interval
>>> intervals = [Interval(1, 2), Interval(2, 3), Interval(3, 4), Interval(1, 3)]

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
>>> nc = nc.map_intervals(intervals, interval_name="interval")
>>> nc.to_pandas()
     series interval  interval.start  interval.end                     timestamp  value
0  series-1                        1             2 1970-01-01 00:00:00.000000001  100.0
1  series-1                        2             3 1970-01-01 00:00:00.000000002  200.0
2  series-1                        3             4 1970-01-01 00:00:00.000000003  300.0
3  series-1                        1             3 1970-01-01 00:00:00.000000001  100.0
4  series-1                        1             3 1970-01-01 00:00:00.000000002  200.0
5  series-2                        1             2 1970-01-01 00:00:00.000000001  200.0
6  series-2                        2             3 1970-01-01 00:00:00.000000002  400.0
7  series-2                        3             4 1970-01-01 00:00:00.000000003  600.0
8  series-2                        1             3 1970-01-01 00:00:00.000000001  200.0
9  series-2                        1             3 1970-01-01 00:00:00.000000002  400.0

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
>>> scaled_nc = nc.map(F.scale(1000))
>>> scaled_nc.to_pandas() # 区間から作成された各時間範囲に scale() 関数を適用します
     series interval  interval.start  interval.end                     timestamp     value
0  series-1                        1             2 1970-01-01 00:00:00.000000001  100000.0
1  series-1                        2             3 1970-01-01 00:00:00.000000002  200000.0
2  series-1                        3             4 1970-01-01 00:00:00.000000003  300000.0
3  series-1                        1             3 1970-01-01 00:00:00.000000001  100000.0
4  series-1                        1             3 1970-01-01 00:00:00.000000002  200000.0
5  series-2                        1             2 1970-01-01 00:00:00.000000001  200000.0
6  series-2                        2             3 1970-01-01 00:00:00.000000002  400000.0
7  series-2                        3             4 1970-01-01 00:00:00.000000003  600000.0
8  series-2                        1             3 1970-01-01 00:00:00.000000001  200000.0
9  series-2                        1             3 1970-01-01 00:00:00.000000002  400000.0

to_dataframe(numPartitions=16)

コレクション内のすべての時系列を評価し、結果を pyspark.sql.DataFrame に連結します。

PySpark のデータフレームでは、分散データ処理と並列変換が可能です。行数が多いデータフレームを扱う場合に便利です。たとえば、生の系列のすべてのポイントや FunctionNode の結果を読み込む場合、または複数の SummarizerNode や FunctionNode の結果をまとめて評価する場合などです。

追加の series 列には、系列IDまたは foundryts.functions.points() のエイリアスを使用して、結果が属する系列が示されます。

パラメーター： numPartitions (int , 任意) – コレクション内の時系列データを Spark のエグゼキューターに分散するためのパーティション数を指定し、並列データ処理を最適化します。エグゼキューターの数が多い場合は値を大きくするとパフォーマンスが向上する可能性があり、エグゼキューターが少ない場合は値を小さくすると効率が上がる可能性があります。時系列コレクションのサイズと Spark の設定（エグゼキューターの数やエグゼキューターのメモリーなど）に基づいて調整します（デフォルトは16）。
戻り値： コレクション内のすべての時系列および操作を評価した出力を含む PySpark データフレーム。
戻り値の型： pyspark.sql.DataFrame

関連項目

NodeCollection.to_pandas()

注

大きなコレクションでは、numPartitions を適切な値に設定してください。

例

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
>>> series_1 = F.points((1, 100.0), (2, 200.0), (3, 300.0), name="series-1")
>>> series_1.to_pandas()
                      timestamp  value
0 1970-01-01 00:00:00.000000001  100.0
1 1970-01-01 00:00:00.000000002  200.0
2 1970-01-01 00:00:00.000000003  300.0
>>> series_2 = F.points((1, 200.0), (2, 400.0), (3, 600.0), name="series-2")
>>> series_2.to_pandas()
                      timestamp  value
0 1970-01-01 00:00:00.000000001  200.0
1 1970-01-01 00:00:00.000000002  400.0
2 1970-01-01 00:00:00.000000003  600.0
>>> nc = NodeCollection(series_1, series_2)
>>> nc.to_dataframe()
+---------+-----------------------------+-----+
|  series |                 timestamp   |value|
+---------+-----------------------------+-----+
|series-1 |1970-01-01 00:00:00.000000001|100.0|
|series-1 |1970-01-01 00:00:00.000000002|200.0|
|series-1 |1970-01-01 00:00:00.000000003|300.0|
|series-2 |1970-01-01 00:00:00.000000001|200.0|
|series-2 |1970-01-01 00:00:00.000000002|400.0|
|series-2 |1970-01-01 00:00:00.000000003|600.0|
+---------+-----------------------------+-----+

to_pandas(parallel=4, mode='thread')

このコレクション内の時系列クエリを評価し、結果を pandas.DataFrame に連結します。

データフレームの形式の詳細については、FunctionNode.to_pandas() および SummarizerNode.to_pandas() を参照してください。

追加の series 列には、系列IDまたは foundryts.functions.points() のエイリアスを使用して、結果が属する系列が示されます。

パラメーター：
- parallel (int , 任意) – 時系列クエリの評価に使用する並列スレッドまたはプロセスの数。1に設定すると、マルチプロセッシングは行われません（デフォルトは4）。
- mode (str , 任意) – 有効な選択肢は process または thread で、マルチプロセッシングのスレッドプールの種類をそれぞれ制御します。
戻り値： コレクション内の時系列クエリを評価した出力を含む Pandas データフレーム。
戻り値の型： pd.DataFrame

関連項目

NodeCollection.to_dataframe()

注

コレクション内の各時系列クエリの結果はローカルに保存され、最終的なデータフレームに連結されるため、結果がメモリーに収まる必要があります。

並列実行では、メモリー使用量とリソース消費量が増加します。process モードを使用すると、オーバーヘッドが発生する場合があります。並列度が高すぎると、パフォーマンスが低下する可能性があります。

例

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
>>> series_1 = F.points((1, 100.0), (2, 200.0), (3, 300.0), name="series-1")
>>> series_1.to_pandas()
                      timestamp  value
0 1970-01-01 00:00:00.000000001  100.0
1 1970-01-01 00:00:00.000000002  200.0
2 1970-01-01 00:00:00.000000003  300.0
>>> series_2 = F.points((1, 200.0), (2, 400.0), (3, 600.0), name="series-2")
>>> series_2.to_pandas()
                      timestamp  value
0 1970-01-01 00:00:00.000000001  200.0
1 1970-01-01 00:00:00.000000002  400.0
2 1970-01-01 00:00:00.000000003  600.0
>>> nc = NodeCollection(series_1, series_2)

Copied!1
2
3
4
5
6
7
8
>>> nc.to_pandas()
      series                     timestamp  value
0  series-1 1970-01-01 00:00:00.000000001  100.0
1  series-1 1970-01-01 00:00:00.000000002  200.0
2  series-1 1970-01-01 00:00:00.000000003  300.0
3  series-2 1970-01-01 00:00:00.000000001  200.0
4  series-2 1970-01-01 00:00:00.000000002  400.0
5  series-2 1970-01-01 00:00:00.000000003  600.0

to_rdd(numPartitions=16)

非推奨

バージョン 1.0.0 以降は非推奨です。

このコレクション内のノードを評価して、(key, object) の RDD を返します。この NodeCollection 内のノードがグループ化またはウィンドウ操作によって生成された場合、対応するキーには指定されたメタデータキーまたは区間が含まれます。それ以外の場合は、ノードの系列識別子になります。

パラメーター： numPartitions (int) – Spark の実行に使用するパーティション数
戻り値の型： pyspark.RDD

types()

コレクションをデータフレームとして評価したときに生成される pandas.DataFrame の列のデータ型をタプルで返します。

戻り値： コレクションの評価結果となるデータフレームの列のデータ型を含むタプル。
戻り値の型： Tuple[Type]

注

均一でないコレクションには、コレクション内の各要素のすべてのデータ型の和集合が含まれます。

例

Copied!1
2
>>> series_1 = F.points((1, 100.0), (2, 200.0), (3, 300.0), name="series-1")
>>> series_2 = F.points((1, 200.0), (2, 400.0), (3, 600.0), name="series-2")

Copied!1
2
3
>>> nc = NodeCollection(series_1, series_2)
>>> nc.types()
(<class 'str'>, <class 'int'>, <class 'float'>)

Copied!1
2
3
4
5
>>> dist = F.distribution()(nc)
>>> dist.types()
(<class 'float'>, <class 'int'>, <class 'float'>, <class 'float'>, <class 'float'>,
<class 'pandas._libs.tslibs.timestamps.Timestamp'>, <class 'float'>,
<class 'pandas._libs.tslibs.timestamps.Timestamp'>)

Copied!1
2
3
4
5
6
7
8
9
>>> mixed_nc = NodeCollection([F.distribution()(series_1), F.statistics()(series_2)])
>>> print(mixed_nc.types())
(<class 'str'>, <class 'float'>, <class 'int'>, <class 'float'>, <class 'float'>,
<class 'float'>, <class 'pandas._libs.tslibs.timestamps.Timestamp'>, <class 'float'>,
<class 'pandas._libs.tslibs.timestamps.Timestamp'>, <class 'int'>,
<class 'pandas._libs.tslibs.timestamps.Timestamp'>, <class 'float'>,
<class 'pandas._libs.tslibs.timestamps.Timestamp'>, <class 'float'>,
<class 'pandas._libs.tslibs.timestamps.Timestamp'>, <class 'float'>,
<class 'float'>, <class 'pandas._libs.tslibs.timestamps.Timestamp'>, <class 'float'>)

←

PREVIOUSInterval

NEXTfunctions.cumulative_aggregate

→