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。