wannesm/dtaidistance

dtaidistance – 高速時系列距離測定

何であるか – 単変量および多変量時系列の距離測定を実装するPythonライブラリ（オプションでC高速化バックエンドを備える）。最も代表的なのは動的時系列歪み（DTW）である。DTAI研究グループ（KU Leuven）によって開発され、Apache 2.0ライセンスで公開されている。

主な機能

• プア・PythonおよびCythonベースの実装；Cバージョンは30〜300倍高速で、OpenMPが利用可能であれば並列処理も可能。
• コアアルゴリズム：DTW距離、DTW歪み経路、完全歪み行列、DTWバリセンターアベレージング、説明可能性向けの動的部分列歪み（DSW）、部分列検索、モチーフ発見の補助機能。
• 多変量系列のサポート、オプションのNumPy/Pandas統合、分散ワークロード向けブロック単位の距離行列計算。
• SciPyのクラスタリング関数をラップしたクラスタリング（階層的、リンク）の補助ユーティリティ、歪み経路およびクラスタリング木の可視化ツール。
• 最小限の必須依存関係 – Python 3のみ必須；NumPy、Cython、Matplotlib、SciPy、tqdm、PyClusteringはオプション。

一般的なワークフロー

import numpy as np
from dtaidistance import dtw, clustering

# 2つの系列 → DTW距離（高速Cバージョン）
s1 = np.array([0,0,1,2,1,0,1,0,0], dtype=np.double)
s2 = np.array([0,1,2,0,0,0,0,0,0], dtype=np.double)
dist = dtw.distance_fast(s1, s2, use_pruning=True)
print('DTW距離:', dist)

# シリーズの集合 → 距離行列（並列Cコード）
series = [s1, s2, np.random.rand(9)]
matrix = dtw.distance_matrix_fast(series, parallel=True)

# 行列上の階層的クラスタリング
model = clustering.Hierarchical(dtw.distance_matrix_fast, {})
labels = model.fit(series)
print('クラスタラベル:', labels)

ライブラリは歪み経路やクラスタリング木のプロットを可能にする可視化ヘルパー（dtw_visualisation）と、DSWに基づく説明用のExplainPairクラスも提供している。

インストール

# pip経由（C拡張用にNumPyが自動追加）
pip install dtaidistance

# または conda-forge 経由（事前ビルド済みバイナリ）
conda install -c conda-forge dtaidistance

Cコードのコンパイルができない場合（例：OpenMPが不足）でも、純Pythonフォールバックは即座に動作する。

使用するべき場面

• 研究やプロダクションパイプラインで信頼性の高い、よくテストされたDTW実装が必要な場合。
• 大規模なペアワイズDTW計算が必要で、速度が重要（例：クラスタリング、最近傍探索）。
• 部分列歪みによる時系列類似性の説明可能性が必要な場合。
• 既にNumPy/Pandasを使用しているプロジェクトで、重いディープラーニングフレームワークを導入せずに即座に使える距離関数が必要な場合。

詳細情報の入手先

• 完全なドキュメント： https://dtaidistance.readthedocs.io
• APIリファレンスと例はリポジトリの examples/ フォルダ内にある。
• 学術論文で使用する場合はZenodo DOIでソフトウェアを引用すること。

---

上記のすべての情報はプロジェクトのREADMEから直接抜粋されています。