Merlion: 時系列のための機械学習ライブラリ

目次

1. はじめに
2. 関連ライブラリとの比較
3. インストール
4. ドキュメント
5. クイックスタート
   1. 異常検知
   2. 予測
6. 評価とベンチマーキング
7. テクニカルレポートとMerlionの引用方法

はじめに

Merlionは、時系列インテリジェンスのためのPythonライブラリです。データの読み込みと変換、モデルの構築とトレーニング、モデル出力の後処理、モデルパフォーマンスの評価を含む、エンドツーエンドの機械学習フレームワークを提供します。単変量および多変量の時系列を対象とした、予測、異常検知、変化点検出など、さまざまな時系列学習タスクをサポートしています。このライブラリは、エンジニアや研究者が特定の時系列ニーズに合わせてモデルを迅速に開発し、複数の時系列データセット間でベンチマークできるワンストップソリューションを提供することを目的としています。

Merlionの主な特徴は次のとおりです。

• 幅広い予測および異常検知データセットに対応した、標準化され簡単に拡張可能なデータ読み込みとベンチマーキング。カスタムデータセットの透過的なサポートも含みます。
• 異常検知、予測、変化点検出のための多様なモデルのライブラリで、すべて共通のインターフェースの下で統一されています。モデルには、古典的な統計手法、ツリーアンサンブル、深層学習アプローチが含まれます。上級ユーザーは、各モデルを必要に応じて完全に設定できます。
• 効率的で、堅牢に優れたパフォーマンスを達成し、新しいユーザーの出発点となる抽象的なDefaultDetectorおよびDefaultForecasterモデル。
• ハイパーパラメータ調整とモデル選択を自動化するAutoML。
• 外生リグレッサを使用して幅広いモデルで予測するための統合API。
• 異常スコアをより解釈しやすくし、誤検知（false positives）の数を減らす、実用的で業界に着想を得た異常検知器向けの後処理ルール。
• 複数のモデルの出力を組み合わせて、より堅牢なパフォーマンスを実現する使いやすいアンサンブル。
• 本番環境でのモデルのライブデプロイと再トレーニングをシミュレートし、予測と異常検知の両方でパフォーマンスを評価する柔軟な評価パイプライン。
• クリック可能なビジュアルUIを含む、モデル予測の可視化のネイティブサポート。
• PySparkを使用した分散計算バックエンド。産業規模で時系列アプリケーションを提供するために使用できます。

関連ライブラリとの比較

以下の表は、Merlionの主要機能が、時系列の異常検知や予測を行う他のライブラリとどのように比較されるかを視覚的に示したものです。

Merlion 2.0で新しくなった機能は次のとおりです。

インストール

Merlionは2つのサブリポジトリで構成されています。merlionはライブラリのコアとなる時系列インテリジェンス機能を実装し、ts_datasetsは複数の時系列データセット用の標準化されたデータローダーを提供します。これらのローダーは、時系列を付随するメタデータとともにpandas.DataFrameとして読み込みます。

merlionは、pip install salesforce-merlion を実行するとPyPIからインストールできます。ソースからインストールする場合は、このリポジトリをクローンして pip install Merlion/ を実行するか、編集可能モードでインストールするには pip install -e Merlion/ を実行します。追加の依存関係は、pip install salesforce-merlion[all] または、ソースからインストールする場合は pip install "Merlion/[all]" を実行してインストールできます。オプションの依存関係には、GUIダッシュボード用のdashboard、PySparkを使用した分散計算バックエンド用のspark、すべての深層学習モデル用のdeep-learningが個別に含まれています。

データ読み込みパッケージts_datasetsをインストールするには、このリポジトリをクローンして pip install -e Merlion/ts_datasets/ を実行してください。データローダーを初期化する際に毎回データセットのルートディレクトリを手動で指定したくない場合は、このパッケージを編集可能モード（つまり -e フラグ付き）でインストールする必要があります。

以下の外部依存関係に注意してください。

1. 一部の予測モデルはOpenMPに依存しています。condaを使用する場合は、パッケージをインストールする前に conda install -c conda-forge lightgbm を実行してください。これにより、OpenMPがお使いのconda環境内のlightgbmパッケージ（依存関係の1つ）と連携するように構成されます。Macを使用する場合は、Homebrewをインストールして brew install libomp を実行し、モデルがOpenMPライブラリを利用できるようにしてください。

2. 一部の異常検知モデルはJava Development Kit（JDK）に依存しています。Ubuntuの場合は、 sudo apt-get install openjdk-11-jdk を実行してください。Mac OSの場合は、Homebrewをインストールして brew tap adoptopenjdk/openjdk && brew install --cask adoptopenjdk11 を実行してください。また、javaがPATH上で見つかること、およびJAVA_HOME環境変数が設定されていることを確認してください。

ドキュメント

サンプルコードとMerlionの入門については、examples内のJupyterノートブックと、こちらのガイド付きウォークスルーを参照してください。詳細なAPIドキュメント（サンプルコードを含む）はここにあります。テクニカルレポートは、Merlionの全体的なアーキテクチャを概説し、単変量および多変量の時系列に対する異常検知と予測の実験結果を示しています。

クイックスタート

最も簡単な始め方は、GUIベースのWebdashboardを使用することです。このダッシュボードは、独自のカスタムデータセットで多くのモデルをすばやく試すのに最適な方法を提供します。使用するには、オプションのdashboard依存関係を指定してMerlionをインストールし（例: pip install salesforce-merlion[dashboard]）、コマンドラインから python -m merlion.dashboard を実行します。ダッシュボードは http://localhost:8050 で表示できます。以下に、異常検知と予測の両方のダッシュボードのスクリーンショットを示します。

独自のコードでMerlionを使い始めるために、以下に異常検知と予測の両方でMerlionのデフォルトモデルを使用した最小限の例を示します。

異常検知

ここでは、上記の異常検知ダッシュボードの結果を再現するコードを示します。まず、MerlionのTimeSeriesクラスと、Numenta Anomaly Benchmark NAB用のデータローダーをインポートします。次に、このデータセットから特定の時系列をトレーニング分割とテスト分割に分けます。

from merlion.utils import TimeSeries
from ts_datasets.anomaly import NAB

# Data loader returns pandas DataFrames, which we convert to Merlion TimeSeries
time_series, metadata = NAB(subset="realKnownCause")[3]
train_data = TimeSeries.from_pd(time_series[metadata.trainval])
test_data = TimeSeries.from_pd(time_series[~metadata.trainval])
test_labels = TimeSeries.from_pd(metadata.anomaly[~metadata.trainval])

次に、MerlionのDefaultDetectorを初期化してトレーニングできます。DefaultDetectorは、パフォーマンスと効率性のバランスが取れた異常検知モデルです。また、テスト分割に対する予測も取得します。

from merlion.models.defaults import DefaultDetectorConfig, DefaultDetector
model = DefaultDetector(DefaultDetectorConfig())
model.train(train_data=train_data)
test_pred = model.get_anomaly_label(time_series=test_data)

次に、モデルの予測を可視化します。

from merlion.plot import plot_anoms
import matplotlib.pyplot as plt
fig, ax = model.plot_anomaly(time_series=test_data)
plot_anoms(ax=ax, anomaly_labels=test_labels)
plt.show()

最後に、モデルを定量的に評価できます。適合率（precision）と再現率（recall）は、モデルが3回のアラームを発報し、そのうち2件が真陽性、1件が偽陰性、1件が偽陽性であったことに基づいています。また、モデルが正しく検知した各異常を検知するのにかかった平均時間も評価します。

from merlion.evaluate.anomaly import TSADMetric
p = TSADMetric.Precision.value(ground_truth=test_labels, predict=test_pred)
r = TSADMetric.Recall.value(ground_truth=test_labels, predict=test_pred)
f1 = TSADMetric.F1.value(ground_truth=test_labels, predict=test_pred)
mttd = TSADMetric.MeanTimeToDetect.value(ground_truth=test_labels, predict=test_pred)
print(f"Precision: {p:.4f}, Recall: {r:.4f}, F1: {f1:.4f}\n"
      f"Mean Time To Detect: {mttd}")

Precision: 0.6667, Recall: 0.6667, F1: 0.6667
Mean Time To Detect: 1 days 10:22:30

予測

ここでは、上記の予測ダッシュボードの結果を再現するコードを示します。まず、MerlionのTimeSeriesクラスとM4データセット用のデータローダーをインポートします。次に、このデータセットから特定の時系列をトレーニング分割とテスト分割に分けます。

from merlion.utils import TimeSeries
from ts_datasets.forecast import M4

# Data loader returns pandas DataFrames, which we convert to Merlion TimeSeries
time_series, metadata = M4(subset="Hourly")[0]
train_data = TimeSeries.from_pd(time_series[metadata.trainval])
test_data = TimeSeries.from_pd(time_series[~metadata.trainval])

次に、MerlionのDefaultForecasterを初期化してトレーニングできます。DefaultForecasterは、パフォーマンスと効率性のバランスが取れた予測モデルです。また、テスト分割に対する予測も取得します。

from merlion.models.defaults import DefaultForecasterConfig, DefaultForecaster
model = DefaultForecaster(DefaultForecasterConfig())
model.train(train_data=train_data)
test_pred, test_err = model.forecast(time_stamps=test_data.time_stamps)

次に、モデルの予測を可視化します。

import matplotlib.pyplot as plt
fig, ax = model.plot_forecast(time_series=test_data, plot_forecast_uncertainty=True)
plt.show()

最後に、モデルを定量的に評価します。sMAPEは予測の誤差を0〜100のスケールで測定し（低いほど良い）、MSISは95%信頼帯の品質を0〜100のスケールで評価します（低いほど良い）。

# Evaluate the model's predictions quantitatively
from scipy.stats import norm
from merlion.evaluate.forecast import ForecastMetric

# Compute the sMAPE of the predictions (0 to 100, smaller is better)
smape = ForecastMetric.sMAPE.value(ground_truth=test_data, predict=test_pred)

# Compute the MSIS of the model's 95% confidence interval (0 to 100, smaller is better)
lb = TimeSeries.from_pd(test_pred.to_pd() + norm.ppf(0.025) * test_err.to_pd().values)
ub = TimeSeries.from_pd(test_pred.to_pd() + norm.ppf(0.975) * test_err.to_pd().values)
msis = ForecastMetric.MSIS.value(ground_truth=test_data, predict=test_pred,
                                 insample=train_data, lb=lb, ub=ub)
print(f"sMAPE: {smape:.4f}, MSIS: {msis:.4f}")

sMAPE: 4.1944, MSIS: 18.9331

評価とベンチマーキング

Merlionの主要機能の1つは、モデルのライブデプロイを履歴データ上でシミュレートする評価パイプラインです。これにより、本番環境で遭遇する可能性のある条件下で、関連するデータセット上のモデルを比較できます。当社の評価パイプラインは次の手順で進みます。

1. 最近の履歴トレーニングデータ（時系列のトレーニング分割として指定）で初期モデルをトレーニングします。
2. 定期的な間隔（例: 1日1回）で、最新データでモデル全体を再トレーニングします。これは時系列の全履歴またはより限定的なウィンドウ（例: 4週間）のいずれかになります。
3. 再トレーニングの間に発生する時系列値に対するモデルの予測（異常スコアまたは予測値）を取得します。これをバッチ（すべての値を一度に予測）、ストリーミング（完全に再トレーニングせずに各データポイントの後にモデルの内部状態を更新）、またはその中間の頻度のいずれで行うかをカスタマイズできます。
4. モデルの予測をグラウンドトゥルース（異常検知の場合はラベル付き異常、予測の場合は実際の時系列値）と比較し、定量的な評価メトリクスを報告します。

このパイプラインを使用して任意のモデルを任意のデータセットで評価できるスクリプトを提供しています。例えば、次を実行すると

python benchmark_anomaly.py --dataset NAB_realAWSCloudwatch --model IsolationForest --retrain_freq 1d

NABデータセットの「realAWSCloudwatch」サブセットに対するIsolationForest（1日1回再トレーニング）の異常検知パフォーマンスが評価されます。同様に、次を実行すると

python benchmark_forecast.py --dataset M4_Hourly --model ETS

M4データセットの「Hourly」サブセットに対するETSのバッチ予測パフォーマンス（つまり再トレーニングなし）が評価されます。これらのスクリプトを実行して得られた結果は、テクニカルレポートの実験セクションにあります。

テクニカルレポートとMerlionの引用方法

技術的な詳細は、テクニカルレポート（https://arxiv.org/abs/2109.09265）で参照できます。

Merlionを研究やアプリケーションで使用する場合は、次のBibTeXを使用して引用してください。

@article{bhatnagar2021merlion,
      title={Merlion: A Machine Learning Library for Time Series},
      author={Aadyot Bhatnagar and Paul Kassianik and Chenghao Liu and Tian Lan and Wenzhuo Yang
              and Rowan Cassius and Doyen Sahoo and Devansh Arpit and Sri Subramanian and Gerald Woo
              and Amrita Saha and Arun Kumar Jagota and Gokulakrishnan Gopalakrishnan and Manpreet Singh
              and K C Krithika and Sukumar Maddineni and Daeki Cho and Bo Zong and Yingbo Zhou
              and Caiming Xiong and Silvio Savarese and Steven Hoi and Huan Wang},
      year={2021},
      eprint={2109.09265},
      archivePrefix={arXiv},
      primaryClass={cs.LG}
}

今後の予定

私たちは、GPUを使用した時系列モデリングを活用して、Merlionの速度とスループットをさらに向上させるよう努めています。今後の展開にご期待ください。 ...