wannesm/dtaidistance

dtaidistance – 고속 시계열 거리 측정

무엇인가요 – 단변량 및 다변량 시계열에 대한 거리 측정을 구현하는 Python 라이브러리 (옵션으로 C 가속 백엔드 포함). 가장 대표적인 것은 동적 시간 왜곡(DTW)입니다. KU 루벤의 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)와 DSW 기반 설명을 위한 ExplainPair 클래스도 제공합니다.

설치

# pip를 통한 설치 (C 확장용 NumPy 자동 추가)
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에서 직접 인용되었습니다.