foundryts.functions.time_series_search

foundryts.functions.time_series_search(predicate, labels=None, start=None, end=None, interval_values=None, before='nearest', internal='default', after='nearest', min_duration=None, max_duration=None)

指定された述語を使用して時系列内の区間を検索する関数を返します。

この関数は、述語が true となる時間区間を返します。

返された各区間について、対応する statistics() が評価されます。 interval_values 内の dsl() 式は、最終的な statistics() の評価に使用されます。

指定された補間方法は、欠落しているタイムスタンプを埋めるために使用されます。補間と補間方法の詳細については、interpolate() を参照してください。

この関数が生成する区間は、Quiver のイベントに相当します。これは、時系列が区間ごとの挙動を示し、時系列の分析でその区間へのアクセスが必要な場合に特に役立ちます。その後、time_range() を使用して各時系列を範囲に分割し、各区間を新しい time_range() とすることで、各時間範囲に対して個別に操作を適用できます。

パラメーター：
- predicate (str) – dsl() 条件プログラムを使用して区間を検索するための述語です。
- labels (Union [str , List [str ] ] , 任意) – predicate と interval_values 内で各入力時系列を参照するためのエイリアスです。（デフォルトは [‘a’, ‘b’, …, ‘aa’, ‘ab’, …] です）。
- start (int | datetime | str , 任意) – 時系列内の区間の評価を開始するタイムスタンプ（この値を含む）です。 start タイムスタンプと重なる区間については、区間全体が出力に含まれます（デフォルトは pandas.Timestamp.min です）。
- end (int | datetime | str , 任意) – 時系列内の区間の評価を終了するタイムスタンプ（この値を含まない）です。 end タイムスタンプと重なる区間については、区間全体が出力に含まれます（デフォルトは pandas.Timestamp.max` です）。
- interval_values (str , 任意) – 区間の統計量の計算対象となる値を変換する dsl() プログラムです。数値以外のデータでは統計量を計算できないため、数値以外の入力時系列では必須です。（デフォルトは最初の入力時系列です）。
- before (Union [str , List [str ] ] , 任意) – 時系列の最初の点より前にある点を補間する方法です。時系列ごとのリストとして指定することもできます。 interpolate() の有効な補間方法を使用します（デフォルトは NEAREST です）。
- internal (Union [str , List [str ] ] , 任意) – 既存の点の間にある点を補間する方法です。時系列ごとのリストとして指定することもできます。 interpolate() の有効な値を使用します（デフォルトは、数値の時系列では LINEAR、列挙型の時系列では PREVIOUS です）。
- after (Union [str , List [str ] ] , 任意) – 時系列の最後の点より後にある点を補間する方法です。時系列ごとのリストとして指定することもできます。 interpolate() の有効な補間方法を使用します（デフォルトは NEAREST です）。
- min_duration (int | str | datetime.timedelta , 任意) – 時間範囲が区間とみなされるために、述語が true であり続ける必要がある最小期間です。
- max_duration (int | str | datetime.timedelta , 任意) – 時間範囲が区間とみなされるために、述語が true であり続ける期間の上限です。
戻り値： 入力時系列について、述語を満たす区間の統計量を返す関数です。
戻り値の型： (Union[FunctionNode, NodeCollections]) -> SummaryNode

データフレームのスキーマ

列名	データ型	説明
count	int	区間内のデータポイントの件数です。
earliest_point.timestamp	datetime	区間内の最初のデータポイントのタイムスタンプです。
earliest_point.value	float	区間内の最初のデータポイントの値です。
end_timestamp	datetime	区間の終了タイムスタンプ（この値を含まない）です。
largest_point.timestamp	datetime	区間内で最大値を持つデータポイントのタイムスタンプです。
largest_point.value	float	区間内の最大値です。
latest_point.timestamp	datetime	区間内の最新のデータポイントのタイムスタンプです。
latest_point.value	float	区間内の最新のデータポイントの値です。
mean	float	区間内のすべてのデータポイントの平均値です。
smallest_point.timestamp	datetime	区間内で最小値を持つデータポイントのタイムスタンプです。
smallest_point.value	float	区間内の最小値です。
start_timestamp	datetime	区間内の最初のデータポイントのタイムスタンプです。
standard_deviation	float	区間内のデータポイントの標準偏差です。
duration.seconds	int	区間の期間（秒単位）です。
duration.subsecond_nanos	int	区間の期間（ナノ秒単位）です。

例

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
30
31
>>> discrete_series = F.points(
...     (0, 1.0),
...     (1, 2.0),
...     (2, 2.0),
...     (3, 3.0),
...     (4, 5.0),
...     (5, 6.0),
...     (6, 4.0),
...     (7, 2.0),
...     (8, 6.0),
...     (9, 7.0),
...     (10, 8.0),
...     (11, 10.0),
...     (12, 11.0),
...     name="discrete",
... )
>>> discrete_series.to_pandas()
                       timestamp  value
0  1970-01-01 00:00:00.000000000    1.0
1  1970-01-01 00:00:00.000000001    2.0
2  1970-01-01 00:00:00.000000002    2.0
3  1970-01-01 00:00:00.000000003    3.0
4  1970-01-01 00:00:00.000000004    5.0
5  1970-01-01 00:00:00.000000005    6.0
6  1970-01-01 00:00:00.000000006    4.0
7  1970-01-01 00:00:00.000000007    2.0
8  1970-01-01 00:00:00.000000008    6.0
9  1970-01-01 00:00:00.000000009    7.0
10 1970-01-01 00:00:00.000000010    8.0
11 1970-01-01 00:00:00.000000011   10.0
12 1970-01-01 00:00:00.000000012   11.0

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
>>> even_search = F.time_series_search(
...     predicate="discrete % 2 == 0",
...     interval_values="discrete",
...     labels="discrete",
... )(discrete_series)
# ポイントを含む3個の区間：
# 区間 1: [(1, 2.0), (2, 2.0)]
# 区間 2: [(5, 6.0), (6, 4.0), (7, 2.0), (8, 6.0)]
# 区間 3: [(10, 8.0), (11, 10.0)]
>>> even_search.to_pandas()
   count  duration.seconds  duration.subsecond_nanos      earliest_point.timestamp  earliest_point.value                      end_time       largest_point.timestamp  largest_point.value        latest_point.timestamp  latest_point.value  mean      smallest_point.timestamp  smallest_point.value  standard_deviation                    start_time
0      2                 0                         2 1970-01-01 00:00:00.000000001                   2.0 1970-01-01 00:00:00.000000003 1970-01-01 00:00:00.000000002                  2.0 1970-01-01 00:00:00.000000002                 2.0   2.0 1970-01-01 00:00:00.000000002                   2.0            0.000000 1970-01-01 00:00:00.000000001
1      4                 0                         4 1970-01-01 00:00:00.000000005                   6.0 1970-01-01 00:00:00.000000009 1970-01-01 00:00:00.000000008                  6.0 1970-01-01 00:00:00.000000008                 6.0   4.5 1970-01-01 00:00:00.000000007                   2.0            1.658312 1970-01-01 00:00:00.000000005
2      2                 0                         2 1970-01-01 00:00:00.000000010                   8.0 1970-01-01 00:00:00.000000012 1970-01-01 00:00:00.000000011                 10.0 1970-01-01 00:00:00.000000011                10.0   9.0 1970-01-01 00:00:00.000000010                   8.0            1.000000 1970-01-01 00:00:00.000000010

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
>>> search_formula = F.time_series_search(
...     predicate="discrete % 2 == 0",
...     interval_values="discrete * 2",
...     labels="discrete",
... )(discrete_series)
# ポイントを含む3個の区間（値を2倍にしたもの）：
# 区間 1: [(1, 4.0), (2, 4.0)]
# 区間 2: [(5, 12.0), (6, 8.0), (7, 4.0), (8, 12.0)]
# 区間 3: [(10, 16.0), (11, 20.0)]
>>> search_formula.to_pandas()
   count  duration.seconds  duration.subsecond_nanos      earliest_point.timestamp  earliest_point.value                      end_time       largest_point.timestamp  largest_point.value        latest_point.timestamp  latest_point.value  mean      smallest_point.timestamp  smallest_point.value  standard_deviation                    start_time
0      2                 0                         2 1970-01-01 00:00:00.000000001                   4.0 1970-01-01 00:00:00.000000003 1970-01-01 00:00:00.000000002                  4.0 1970-01-01 00:00:00.000000002                 4.0   4.0 1970-01-01 00:00:00.000000002                   4.0            0.000000 1970-01-01 00:00:00.000000001
1      4                 0                         4 1970-01-01 00:00:00.000000005                  12.0 1970-01-01 00:00:00.000000009 1970-01-01 00:00:00.000000008                 12.0 1970-01-01 00:00:00.000000008                12.0   9.0 1970-01-01 00:00:00.000000007                   4.0            3.316625 1970-01-01 00:00:00.000000005
2      2                 0                         2 1970-01-01 00:00:00.000000010                  16.0 1970-01-01 00:00:00.000000012 1970-01-01 00:00:00.000000011                 20.0 1970-01-01 00:00:00.000000011                20.0  18.0 1970-01-01 00:00:00.000000010                  16.0            2.000000 1970-01-01 00:00:00.000000010

Copied!1
2
3
4
5
6
7
8
9
10
11
12
>>> min_duration_search = F.time_series_search(
...     predicate="discrete % 2 == 0",
...     interval_values="discrete",
...     labels="discrete",
...     min_duration="3ns",
... )(discrete_series)
# duration < 3 のため、最初と最後の区間は絞り込みにより除外されます。
# ポイントを含む1個の区間：
# [(5, 6.0), (6, 4.0), (7, 2.0), (8, 6.0)]
>>> min_duration_search.to_pandas()
   count  duration.seconds  duration.subsecond_nanos      earliest_point.timestamp  earliest_point.value                      end_time       largest_point.timestamp  largest_point.value        latest_point.timestamp  latest_point.value  mean      smallest_point.timestamp  smallest_point.value  standard_deviation                    start_time
0      4                 0                         4 1970-01-01 00:00:00.000000005                   6.0 1970-01-01 00:00:00.000000009 1970-01-01 00:00:00.000000008                  6.0 1970-01-01 00:00:00.000000008                 6.0   4.5 1970-01-01 00:00:00.000000007                   2.0            1.658312 1970-01-01 00:00:00.000000005

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
>>> max_duration_search = F.time_series_search(
...     predicate="discrete % 2 == 0",
...     interval_values="discrete",
...     labels="discrete",
...     max_duration="3ns",
... )(discrete_series)
# duration > 3 のため、2番目の区間は絞り込みにより除外されます。
# ポイントを含む2個の区間：
# 区間 1: [(1, 2.0), (2, 2.0)]
# 区間 2: [(10, 8.0), (11, 10.0)]
>>> max_duration_search.to_pandas()
   count  duration.seconds  duration.subsecond_nanos      earliest_point.timestamp  earliest_point.value                      end_time       largest_point.timestamp  largest_point.value        latest_point.timestamp  latest_point.value  mean      smallest_point.timestamp  smallest_point.value  standard_deviation                    start_time
0      2                 0                         2 1970-01-01 00:00:00.000000001                   2.0 1970-01-01 00:00:00.000000003 1970-01-01 00:00:00.000000002                  2.0 1970-01-01 00:00:00.000000002                 2.0   2.0 1970-01-01 00:00:00.000000002                   2.0                 0.0 1970-01-01 00:00:00.000000001
1      2                 0                         2 1970-01-01 00:00:00.000000010                   8.0 1970-01-01 00:00:00.000000012 1970-01-01 00:00:00.000000011                 10.0 1970-01-01 00:00:00.000000011                10.0   9.0 1970-01-01 00:00:00.000000010                   8.0                 1.0 1970-01-01 00:00:00.000000010

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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
>>> toggle_series = F.points(
...     (0, "OFF"),
...     (1, "ON"),
...     (2, "OFF"),
...     (3, "OFF"),
...     (4, "ON"),
...     (5, "ON"),
...     (6, "ON"),
...     (7, "OFF"),
...     (8, "ON"),
...     (9, "ON"),
...     (10, "OFF"),
...     (11, "OFF"),
...     (12, "ON"),
...     name="toggle",
... )
>>> toggle_series.to_pandas()
                       timestamp value
0  1970-01-01 00:00:00.000000000   OFF
1  1970-01-01 00:00:00.000000001    ON
2  1970-01-01 00:00:00.000000002   OFF
3  1970-01-01 00:00:00.000000003   OFF
4  1970-01-01 00:00:00.000000004    ON
5  1970-01-01 00:00:00.000000005    ON
6  1970-01-01 00:00:00.000000006    ON
7  1970-01-01 00:00:00.000000007   OFF
8  1970-01-01 00:00:00.000000008    ON
9  1970-01-01 00:00:00.000000009    ON
10 1970-01-01 00:00:00.000000010   OFF
11 1970-01-01 00:00:00.000000011   OFF
12 1970-01-01 00:00:00.000000012    ON
>>> cross_series_search = F.time_series_search(
...     predicate='toggle == "ON"',
...     interval_values="discrete",
...     labels=["toggle", "discrete"],
... )([toggle_series, discrete_series])
# toggle_series の述語が true となる区間から discrete_series に作成された4個の区間：
# 区間 1: [(1, 2.0)]
# 区間 2: [(4, 5.0), (5, 6.0), (6, 4.0)]
# 区間 3: [(8, 6.0), (9, 7.0)]
# 区間 4: [(12, 11.0)]
>>> cross_series_search.to_pandas()
   count  duration.seconds  duration.subsecond_nanos      earliest_point.timestamp  earliest_point.value                      end_time       largest_point.timestamp  largest_point.value        latest_point.timestamp  latest_point.value  mean      smallest_point.timestamp  smallest_point.value  standard_deviation                    start_time
0      1                 0                         1 1970-01-01 00:00:00.000000001                   2.0 1970-01-01 00:00:00.000000002 1970-01-01 00:00:00.000000001                  2.0 1970-01-01 00:00:00.000000001                 2.0   2.0 1970-01-01 00:00:00.000000001                   2.0            0.000000 1970-01-01 00:00:00.000000001
1      3                 0                         3 1970-01-01 00:00:00.000000004                   5.0 1970-01-01 00:00:00.000000007 1970-01-01 00:00:00.000000005                  6.0 1970-01-01 00:00:00.000000006                 4.0   5.0 1970-01-01 00:00:00.000000006                   4.0            0.816497 1970-01-01 00:00:00.000000004
2      2                 0                         2 1970-01-01 00:00:00.000000008                   6.0 1970-01-01 00:00:00.000000010 1970-01-01 00:00:00.000000009                  7.0 1970-01-01 00:00:00.000000009                 7.0   6.5 1970-01-01 00:00:00.000000008                   6.0            0.500000 1970-01-01 00:00:00.000000008
3      1                 0                         1 1970-01-01 00:00:00.000000012                  11.0 1970-01-01 00:00:00.000000013 1970-01-01 00:00:00.000000012                 11.0 1970-01-01 00:00:00.000000012                11.0  11.0 1970-01-01 00:00:00.000000012                  11.0            0.000000 1970-01-01 00:00:00.000000012

←

PREVIOUSfunctions.time_range

NEXTfunctions.time_shift

→