wannesm/dtaidistance

dtaidistance – 高速時間序列距離度量

是什麼 – 一個 Python 庫（支援可選的 C 加速後端），實作單變量與多變量時間序列的距離度量，其中最突出的是動態時間扭曲（DTW）。由魯汶大學 DTAI 研究小組開發，採用 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

# 兩個序列 → 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）以繪製扭曲路徑與聚類樹，並提供 ExplainPair 類用於基於 DSW 的解釋。

安裝

# 透過 pip（自動加入 NumPy 用於 C 擴充）
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。