時系列ライブラリの使用

時系列ライブラリを使い始めるには、 Python のノートブックまたはアプリケーションにライブラリをインポートしてください。

時系列ライブラリをインポートするには、次のコマンドを使用してください：

# Import the package
import tspy

時系列の作成

時系列データを作成し、ライブラリの関数を使用するには、データソースを決定する必要があります。 対応しているデータソースは以下の通りです：

  • インメモリリスト
  • pandas DataFrames
  • 観測値のインメモリ・コレクション（` ObservationCollection construct` を使用）
  • ユーザー定義のリーダー（` TimeSeriesReader construct` を使用）

次の例は、インメモリリストからデータを読み込む方法を示しています：

ts = tspy.time_series([5.0, 2.0, 4.0, 6.0, 6.0, 7.0])
ts

出力は以下の通りです：

TimeStamp: 0     Value: 5.0
TimeStamp: 1     Value: 2.0
TimeStamp: 2     Value: 4.0
TimeStamp: 3     Value: 6.0
TimeStamp: 4     Value: 6.0
TimeStamp: 5     Value: 7.0

また、` MultiTimeSeries construct` を使用することで、複数の時系列を同時に処理することもできます。 A MultiTimeSeries は本質的に時系列の辞書であり、各時系列には固有のキーが割り当てられています。 時系列データは時間軸が揃っていません。

この MultiTimeSeries コンストラクトは、単一の時系列コンストラクトと同様に、変換や取り込みを行うためのメソッドを提供しています：

mts = tspy.multi_time_series({
	"ts1": tspy.time_series([1.0, 2.0, 3.0]),
	"ts2": tspy.time_series([5.0, 2.0, 4.0, 5.0])
})

出力は以下の通りです：

ts2 time series
------------------------------
TimeStamp: 0     Value: 5.0
TimeStamp: 1     Value: 2.0
TimeStamp: 2     Value: 4.0
TimeStamp: 3     Value: 5.0
ts1 time series
------------------------------
TimeStamp: 0     Value: 1.0
TimeStamp: 1     Value: 2.0
TimeStamp: 2     Value: 3.0

時間の解釈

デフォルトでは、時系列データは、特定の観測値が作成された時刻を示すためにデータ long 型を使用しており、これを「タイムティック」と呼びます。 時刻参照システムは、人間が解釈可能なタイムスタンプを持つ時系列データに使用されます。 「時間参照システムの使用」を参照してください。

次の例は、各インデックスが開始時刻の翌日を 1990-01-01表す、単純な時系列を作成する方法を示しています：

import datetime
granularity = datetime.timedelta(days=1)
start_time = datetime.datetime(1990, 1, 1, 0, 0, 0, 0, tzinfo=datetime.timezone.utc)

ts = tspy.time_series([5.0, 2.0, 4.0, 6.0, 6.0, 7.0], granularity=granularity, start_time=start_time)
ts

出力は以下の通りです：

TimeStamp: 1990-01-01T00:00Z     Value: 5.0
TimeStamp: 1990-01-02T00:00Z     Value: 2.0
TimeStamp: 1990-01-03T00:00Z     Value: 4.0
TimeStamp: 1990-01-04T00:00Z     Value: 6.0
TimeStamp: 1990-01-05T00:00Z     Value: 6.0
TimeStamp: 1990-01-06T00:00Z     Value: 7.0

簡単な変換を行う

変換とは、1つ以上の時系列が与えられた際に、新しい時系列を返す関数のことである。

たとえば、時系列データを各ウィンドウが であり size=3、2件ずつスライドするウィンドウに分割するには、次の方法を使用できます：

window_ts = ts.segment(3, 2)
window_ts

出力は以下の通りです：

TimeStamp: 0     Value: original bounds: (0,2) actual bounds: (0,2) observations: [(0,5.0),(1,2.0),(2,4.0)]
TimeStamp: 2     Value: original bounds: (2,4) actual bounds: (2,4) observations: [(2,4.0),(3,6.0),(4,6.0)]

この例では、時系列の各値に1を加算する方法を示しています：

add_one_ts = ts.map(lambda x: x + 1)
add_one_ts

出力は以下の通りです：

TimeStamp: 0     Value: 6.0
TimeStamp: 1     Value: 3.0
TimeStamp: 2     Value: 5.0
TimeStamp: 3     Value: 7.0
TimeStamp: 4     Value: 7.0
TimeStamp: 5     Value: 8.0

あるいは、時系列データを一時的に左結合することもできます。例えば、別の時系列 ts データと結合する場合 ts2などです：

ts2 = tspy.time_series([1.0, 2.0, 3.0])
joined_ts = ts.left_join(ts2)
joined_ts

出力は以下の通りです：

TimeStamp: 0     Value: [5.0, 1.0]
TimeStamp: 1     Value: [2.0, 2.0]
TimeStamp: 2     Value: [4.0, 3.0]
TimeStamp: 3     Value: [6.0, null]
TimeStamp: 4     Value: [6.0, null]
TimeStamp: 5     Value: [7.0, null]

トランスフォーマーの使用

transformers パッケージには、豊富な組み込みトランスフォーマーが用意されています。 提供されているトランスフォーマー関数を使用するには、パッケージをインポートしてください：

from tspy.builders.functions import transformers

パッケージを追加したら、`time` メソッド transform を使用して時系列データを変換することができます。

たとえば、時系列データに対して差分計算を行うには：

ts_diff = ts.transform(transformers.difference())

ここでの出力は次のとおりです：

TimeStamp: 1     Value: -3.0
TimeStamp: 2     Value: 2.0
TimeStamp: 3     Value: 2.0
TimeStamp: 4     Value: 0.0
TimeStamp: 5     Value: 1.0

リデューサーの使用

transformers パッケージと同様に、reducers パッケージが提供するメソッドを使用して、時系列データを集約することができます。 reducers パッケージは、次のようにインポートできます：

from tspy.builders.functions import reducers

パッケージをインポートしたら、` reduce `メソッドを使用して時系列の平均値を算出します。例えば：

avg = ts.reduce(reducers.average())
avg

これによって、次のように出力されます：

5.0

リデューサーには、セグメンテーション変換（1時間ごとの合計、エラー発生前のウィンドウ内の平均など）と併用できるという特別な特性があります。 の出力は segmentation + reducer 時系列であるため、この transform 手法が用いられる。

たとえば、3つのウィンドウに分割し、各ウィンドウの平均値を算出するには、次のようにします：

avg_windows_ts = ts.segment(3).transform(reducers.average())

その結果、次のようになります：

imeStamp: 0     Value: 3.6666666666666665
TimeStamp: 1     Value: 4.0
TimeStamp: 2     Value: 5.333333333333333
TimeStamp: 3     Value: 6.333333333333333

時系列データのグラフ化

時系列をグラフ化する際には、遅延評価が用いられる。 時系列データをグラフ化する際、以下のいずれかの操作を行うことができます：

  • 時系列の観測値を収集し、その結果として BoundTimeSeries
  • 時系列データを単一の値または値の集合に集約する
  • 保存または印刷を行う

たとえば、時系列データのすべての値を収集して返すには：

observations = ts.materialize()
observations

その結果、次のようになります：

[(0,5.0),(1,2.0),(2,4.0),(3,6.0),(4,6.0),(5,7.0)]

時系列データから範囲を取得するには、次のようにします：

observations = ts[1:3] # same as ts.materialize(1, 3)
observations

ここでの出力は次のとおりです：

[(1,2.0),(2,4.0),(3,6.0)]

なお、時系列データが周期的な性質を持つ場合、範囲クエリに対して最適化されます。

現在の時系列データ describe に対して を使用すると、その時系列データもグラフ化されます：

describe_obj = ts.describe()
describe_obj

出力は次のとおりです：

min inter-arrival-time: 1
max inter-arrival-time: 1
mean inter-arrival-time: 1.0
top: 6.0
unique: 5
frequency: 2
first: TimeStamp: 0     Value: 5.0
last: TimeStamp: 5     Value: 7.0
count: 6
mean:5.0
std:1.632993161855452
min:2.0
max:7.0
25%:3.5
50%:5.5
75%:6.25

詳細情報