DTAIDistance is a Python library providing highly optimized distance measures for time series, primarily focusing on Dynamic Time Warping (DTW). It features both a pure Python implementation and a significantly faster C implementation, making it suitable for performance-critical applications. The library also includes functionalities for time series clustering, multi-dimensional DTW, and subsequence search. It is actively maintained by the DTAI Research Group, with the current stable version being 2.4.0.
pip install dtaidistanceVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to calculate the Dynamic Time Warping (DTW) distance between two NumPy arrays using the `distance_fast` method for optimal performance. It also includes an optional step to visualize the warping path, which requires `matplotlib`.
Ensure NumPy is installed (`pip install numpy`) if you are passing NumPy arrays to DTAIDistance functions. If you encounter compilation issues without NumPy, ensure Cython is installed or use pre-compiled binaries via Conda.
Replace calls to `dtw.distance()` with `dtw.distance_fast()` and `dtw.distance_matrix()` with `dtw.distance_matrix_fast()`. Ensure the C library is correctly compiled and available (see 'Problems' section).
On Windows, ensure 'Build Tools for Visual Studio' (with C++ development workload) are installed. On Unix, ensure `gcc` and `OpenMP` development libraries are present. If OpenMP linking issues persist, try `pip install --global-option=--noopenmp dtaidistance` or refer to documentation for `--forcegnugcc`, `--forcellvm` options. Verify C library availability with `dtw.try_import_c(verbose=True)`.
For extremely large datasets, consider strategies to reduce the matrix size (e.g., computing only a `block` of distances), using pruning options like `max_dist` or `window`, or exploring approximate DTW methods outside of `dtaidistance` if exact DTW is not feasible for your scale. Monitor memory usage carefully.
Ensure your system has a C/C++ compiler (e.g., 'Build Tools for Visual Studio' on Windows, `gcc` on Linux/macOS) and OpenMP support. Reinstall using `pip install --no-cache-dir --force-reinstall dtaidistance`. If OpenMP issues persist, try `pip install --global-option=--noopenmp dtaidistance`. You can check the C library status with `from dtaidistance import dtw; dtw.try_import_c(verbose=True)`.
Reduce the number of series or the length of individual series if possible. Use the `block` argument in `distance_matrix_fast` to compute only a subset of the matrix. Consider using pruning options like `max_dist` or `window` to reduce the computation cost per pair, although this doesn't reduce the matrix storage itself.
This is often a symptom of the 'C library not available' problem. Follow the steps to ensure your C/C++ compiler and OpenMP setup are correct and reinstall the library. Using `dtw.distance_fast()` or `dtw.distance_matrix_fast()` explicitly will also trigger this warning if the C library is indeed missing.