.. -- mode: rst --

soft-DTW

soft-DTW 的 Python 实现。

这是什么？

著名的动态时间规整（Dynamic Time Warping, DTW）[1] 将两个可能长度不同的时间序列之间的差异定义为它们的最小对齐代价。尽管可能的对齐方式数量随两个时间序列长度呈指数增长，但 [1] 表明 DTW 可以通过动态规划在仅二次方时间内计算完成。

Soft-DTW [2] 提出将该最小值替换为软最小值（soft minimum）。与原始 DTW 一样，soft-DTW 也可以使用动态规划在二次方时间内计算。然而，soft-DTW 的主要优势在于它处处可微，并且其梯度也可以在二次方时间内计算。这使得 soft-DTW 可用于时间序列平均，或作为损失函数——例如在神经网络端到端训练中，用于衡量真实时间序列与网络预测时间序列之间的差异，并通过反向传播（backpropagation）进行优化。

支持的功能

• soft-DTW（前向计算）及其梯度（反向计算），使用 Cython 实现以提升速度
• 时间序列重心（barycenters，即时间序列平均）
• 支持加载 UCR archive <http://www.cs.ucr.edu/~eamonn/time_series_data/>_ 数据集
• Chainer <http://chainer.org>_ 函数

示例

.. code-block:: python

from sdtw import SoftDTW
from sdtw.distance import SquaredEuclidean

# 时间序列 1：numpy 数组，形状为 [m, d]，其中 m 为长度，d 为维度
X = ...
# 时间序列 2：numpy 数组，形状为 [n, d]，其中 n 为长度，d 为维度
Y = ...

# D 也可以是任意距离矩阵：numpy 数组，形状为 [m, n]
D = SquaredEuclidean(X, Y)
sdtw = SoftDTW(D, gamma=1.0)
# soft-DTW 差异值，当 gamma -> 0 时趋近于 DTW
value = sdtw.compute()
# 对 D 的梯度，形状为 [m, n]，同时也是期望的对齐矩阵
E = sdtw.grad()
# 对 X 的梯度，形状为 [m, d]
G = D.jacobian_product(E)

安装

目前没有提供二进制包。

本项目需从其 Git 仓库安装。假设你已有一个可用的 C 编译器。

1. 获取源代码::

   git clone https://github.com/mblondel/soft-dtw.git

或者，如果未安装 git，可从 GitHub 下载 ZIP 文件 <https://github.com/mblondel/soft-dtw/archive/master.zip>_。

2. 安装依赖项::

   通过 pip

   pip install numpy scipy scikit-learn cython nose

   通过 conda

   conda install numpy scipy scikit-learn cython nose

3. 构建并安装 soft-dtw::

   cd soft-dtw make cython python setup.py build sudo python setup.py install

参考文献

.. [1] Hiroaki Sakoe, Seibi Chiba.
Dynamic programming algorithm optimization for spoken word recognition.
In: IEEE Trans. on Acoustics, Speech, and Sig. Proc, 1978.

.. [2] Marco Cuturi, Mathieu Blondel.
Soft-DTW: a Differentiable Loss Function for Time-Series.
In: Proc. of ICML 2017.
[PDF <https://arxiv.org/abs/1703.01541>_]

作者

• Mathieu Blondel, 2017

soft-dtw 快速上手指南

环境准备

• 系统要求：支持 Linux、macOS 或 Windows（需能编译 C/C++ 代码）
• 前置依赖：
  • Python 3.x
  • C 编译器（如 GCC 或 MSVC）
  • 以下 Python 包：numpy、scipy、scikit-learn、cython、nose

💡 建议使用国内镜像源加速安装，例如清华源：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple numpy scipy scikit-learn cython nose

安装步骤

1. 克隆仓库（或下载 ZIP）：

   git clone https://github.com/mblondel/soft-dtw.git
   

2. 安装 Python 依赖（推荐使用国内源）：

   pip install -i https://pypi.tuna.tsinghua.edu.cn/simple numpy scipy scikit-learn cython nose
   

3. 编译并安装 soft-dtw：

   cd soft-dtw
   make cython
   python setup.py build
   sudo python setup.py install  # Windows 用户可省略 sudo
   

基本使用

以下是最简单的使用示例，计算两个时间序列之间的 soft-DTW 差异及其梯度：

from sdtw import SoftDTW
from sdtw.distance import SquaredEuclidean
import numpy as np

# 定义两个时间序列：X 形状为 [m, d]，Y 形状为 [n, d]
X = np.random.randn(10, 3)  # 长度 10，维度 3
Y = np.random.randn(15, 3)  # 长度 15，维度 3

# 构建平方欧氏距离矩阵
D = SquaredEuclidean(X, Y)

# 创建 soft-DTW 实例（gamma 控制“软”程度，越小越接近标准 DTW）
sdtw = SoftDTW(D, gamma=1.0)

# 计算 soft-DTW 值
value = sdtw.compute()
print("soft-DTW 值:", value)

# 计算对距离矩阵 D 的梯度（即期望对齐矩阵）
E = sdtw.grad()

# 计算对原始序列 X 的梯度
G = D.jacobian_product(E)
print("X 的梯度形状:", G.shape)