dtw-python

library1.7.4pypypi✓ verified 35d ago

dtw-python is a comprehensive Python library that provides a faithful, functionally equivalent implementation of Dynamic Time Warping (DTW) algorithms, mirroring the capabilities of the popular R 'dtw' package. It enables optimal alignment between two time series, even if they have different lengths or time axes, and supports various local (slope) and global (window) constraints. The library is currently at version 1.7.4 and maintains an active, though irregular, release cadence, with several updates per year. It is widely used for classification and clustering tasks across domains like bioinformatics, econometrics, and general time series analysis.

ai-ml data

github ↗package ↗homepage ↗docs ↗

Install & Compatibility

Where this runs

tested against v1.7.5 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.940 runs

build_error

glibc

py 3.10–3.940 runs

installs and imports cleanly · install 9.3s · import 1.503s · 310MB

318MB installed

● package 318MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

The package name for pip is 'dtw-python', but the import statement is simply 'import dtw'.

import dtw

Common for interactive use, imports core functions like `dtw` and `rabinerJuangStepPattern` directly.

from dtw import *

This quickstart demonstrates how to compute Dynamic Time Warping between two NumPy arrays. It defines a query and a template time series, then uses the `dtw()` function to find their optimal alignment. The resulting `alignment` object contains the DTW distance and can be used for plotting the warping path (if `matplotlib` is installed).

import numpy as np from dtw import * # Create two noisy sine waves idx = np.linspace(0, 6.28, num=100) query = np.sin(idx) + np.random.uniform(size=100) / 10.0 template = np.cos(idx) # Compute DTW alignment alignment = dtw(query, template, keep_internals=True) # Print the distance print(f"DTW Distance: {alignment.distance:.2f}") # Optionally, visualize the alignment (requires matplotlib) try: import matplotlib.pyplot as plt alignment.plot(type="threeway") plt.title("DTW Alignment") plt.show() except ImportError: print("Matplotlib not installed. Install with `pip install dtw-python[plots]` to enable plotting.")

Debug

Known footguns

gotchaIndexing in `dtw-python` is 0-based, consistent with Python conventions. This differs from the 1-based indexing used in the R 'dtw' package, which can be a source of error when porting code or comparing results directly.

gotchaFunction argument names in Python use underscores (e.g., `keep_internals`) while the R version commonly uses dots (e.g., `keep.int`). Python does not accept abbreviated argument names.

gotchaPlotting functionality, such as `alignment.plot()`, relies on `matplotlib`. If `matplotlib` is not installed, these methods will raise an `ImportError` or fail silently.

gotchaThe `dtw` function may return `NaN` values in the cost matrix, particularly when using certain `dist_method` arguments like 'cosine' with inappropriate input data. This can lead to `ParameterError: DTW cost matrix C has NaN values.`

gotchaUncommon build issues related to `undefined symbol: alloca` or `C99 mode` can arise when compiling from source on older systems or with outdated compilers.

Upgrade

Version history

Breaking-change detection hasn't run for this library yet.

Audit

Security & dependencies

CVE tracking and dependency tree are planned for a later release.

Agent activity

23 hits · last 30 days

gptbot

ahrefsbot

amazonbot

newsai