wannesm/dtaidistance

dtaidistance – Fast Time‑Series Distance Measures

What it is – A Python library (with an optional C‑accelerated backend) that implements a collection of distance measures for univariate and multivariate time‑series, the most prominent being Dynamic Time Warping (DTW). It is developed by the DTAI research group at KU Leuven and is released under the Apache 2.0 license.

Key capabilities

• Pure‑Python and Cython‑based implementations; the C version is 30‑300× faster and can run in parallel when OpenMP is present.
• Core algorithms: DTW distance, DTW warping path, full warping‑matrix, DTW‑Barycenter Averaging, Dynamic Subsequence Warping (DSW) for explainability, subsequence search, and motif discovery helpers.
• Support for multivariate series, optional NumPy/Pandas integration, and block‑wise distance‑matrix computation for distributed workloads.
• Helper utilities for clustering (hierarchical, linkage) that wrap SciPy’s clustering functions, plus visualisation tools for warping paths and clustering trees.
• Minimal mandatory dependencies – only Python 3; NumPy, Cython, Matplotlib, SciPy, tqdm, PyClustering are optional.

Typical workflow

import numpy as np
from dtaidistance import dtw, clustering

# two series → DTW distance (fast C version)
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 distance:', dist)

# whole collection → distance matrix (parallel C code)
series = [s1, s2, np.random.rand(9)]
matrix = dtw.distance_matrix_fast(series, parallel=True)

# hierarchical clustering on the matrix
model = clustering.Hierarchical(dtw.distance_matrix_fast, {})
labels = model.fit(series)
print('Cluster labels:', labels)

The library also provides visualisation helpers (dtw_visualisation) to plot warping paths and clustering trees, and an ExplainPair class for DSW‑based explanations.

Installation

# via pip (adds NumPy for the C extension)
pip install dtaidistance

# or via conda‑forge (pre‑built binaries)
conda install -c conda-forge dtaidistance

If you cannot compile the C code (e.g., missing OpenMP), the pure‑Python fallback works out‑of‑the‑box.

When to use it

• You need a reliable, well‑tested DTW implementation for research or production pipelines.
• Large‑scale pairwise DTW calculations where speed matters (e.g., clustering, nearest‑neighbor search).
• Explainability of time‑series similarity via subsequence warping.
• Projects that already use NumPy/Pandas and want a drop‑in distance function without pulling in heavyweight deep‑learning frameworks.

Where to learn more

• Full documentation: https://dtaidistance.readthedocs.io
• API reference and examples are in the repo’s examples/ folder.
• Cite the software with the Zenodo DOI if used in publications.

---

All information above is taken directly from the project's README.