---

章节	描述
安装	安装依赖项和tslearn
入门	tslearn的快速使用介绍
可用功能	tslearn功能的全面概述
文档	我们的API参考链接和示例图库
贡献	针对有意贡献的开发者的指南
引用	学术文章中引用tslearn的方式

安装

安装tslearn有多种方式：

• PyPi：python -m pip install tslearn
• Conda：conda install -c conda-forge tslearn
• Git：python -m pip install https://github.com/tslearn-team/tslearn/archive/main.zip

为确保安装成功，必须先安装所需的依赖项。有关如何安装tslearn的更详细指南，请参阅文档。

入门

1. 将数据整理成正确格式

tslearn期望时间序列数据集以三维numpy数组的形式呈现。这三个维度分别对应时间序列的数量、每个时间序列的测量点数以及每个时间序列的维度数（n_ts, max_sz, d）。为了将数据整理成正确格式，有以下几种方法：

• 可以使用诸如to_time_series_dataset之类的实用函数。
• 可以从其他流行的Python时间序列工具包中进行转换。
• 可以直接加载UCR数据集中符合要求的数据集。
• 可以使用generators模块生成合成数据。

此外，需要注意的是，tslearn还支持变长时间序列。

>>> from tslearn.utils import to_time_series_dataset
>>> my_first_time_series = [1, 3, 4, 2]
>>> my_second_time_series = [1, 2, 4, 2]
>>> my_third_time_series = [1, 2, 4, 2, 2]
>>> X = to_time_series_dataset([my_first_time_series,
                                my_second_time_series,
                                my_third_time_series])
>>> y = [0, 1, 1]

2. 数据预处理与变换

可选地，tslearn提供了一些用于数据预处理的工具。为了促进不同算法的收敛，可以对时间序列进行缩放。或者，为了加快训练速度，还可以对数据进行重采样或应用分段变换。

>>> from tslearn.preprocessing import TimeSeriesScalerMinMax
>>> X_scaled = TimeSeriesScalerMinMax().fit_transform(X)
>>> print(X_scaled)
[[[0.] [0.667] [1.] [0.333] [nan]]
 [[0.] [0.333] [1.] [0.333] [nan]]
 [[0.] [0.333] [1.] [0.333] [0.333]]]

3. 训练模型

在将数据整理成正确格式后，就可以开始训练模型了。根据具体的应用场景，tslearn支持分类、聚类和回归等任务。如需了解更全面的可能性，请查看我们的示例图库。

>>> from tslearn.neighbors import KNeighborsTimeSeriesClassifier
>>> knn = KNeighborsTimeSeriesClassifier(n_neighbors=1)
>>> knn.fit(X_scaled, y)
>>> print(knn.predict(X_scaled))
[0 1 1]

可以看出，tslearn中的模型遵循与知名scikit-learn相同的API。此外，它们与scikit-learn完全兼容，因此可以使用scikit-learn的各种工具，例如超参数调优和流水线。

4. 更多分析

tslearn还允许执行各种类型的分析。例如，可以计算一组时间序列的质心，或者使用多种距离度量来计算时间序列之间的距离。

可用功能

数据	处理	聚类	分类	回归	度量方法
UCR 数据集	缩放	TimeSeriesKMeans	KNN 分类器	KNN 回归器	动态时间规整
生成器	分段	KShape	TimeSeriesSVC	TimeSeriesSVR	全局对齐核
转换(1, 2)		KernelKmeans	LearningShapelets	MLP	质心
			早期分类		矩阵概况

文档

文档托管在 readthedocs 上。它包括 API、示例图库 和 用户指南。

贡献

如果您希望为 tslearn 做出贡献，请查看我们的 贡献指南。有趣待办事项列表可以在这里找到 这里。如果您希望将其他针对时间序列的机器学习方法添加到此待办事项列表中，请随时 提交一个问题!

引用 tslearn

如果您在科学出版物中使用 tslearn，我们非常感谢您能进行引用：

@article{JMLR:v21:20-091,
  author  = {Romain Tavenard 和 Johann Faouzi 和 Gilles Vandewiele 和 
             Felix Divo 和 Guillaume Androz 和 Chester Holtz 和 
             Marie Payne 和 Roman Yurchak 和 Marc Ru{\ss}wurm 和 
             Kushal Kolar 和 Eli Woods},
  title   = {Tslearn，一个用于时间序列数据的机器学习工具包},
  journal = {机器学习研究期刊},
  year    = {2020},
  volume  = {21},
  number  = {118},
  pages   = {1-6},
  url     = {http://jmlr.org/papers/v21/20-091.html}
}

致谢

作者谨向 Mathieu Blondel 表示感谢，感谢他提供了 Kernel k-means 和 Soft-DTW 的代码；同时也感谢 Mehran Maghoumi 提供了与 torch 兼容的 SoftDTW 实现 pytorch-softdtw-cuda。

tslearn 快速上手指南

tslearn 是一个专为 Python 设计的时序分析机器学习工具包，提供了丰富的时序数据处理、聚类、分类和回归算法，并完美兼容 scikit-learn 接口。

环境准备

• 操作系统：支持 Windows、macOS 和 Linux。
• Python 版本：需要 Python 3.10 或更高版本。
• 前置依赖：安装时会自动处理核心依赖（如 numpy, scipy, scikit-learn 等），无需手动预装。

安装步骤

推荐使用国内镜像源以加速下载。你可以选择以下任意一种方式进行安装：

方式一：使用 pip 安装（推荐）

python -m pip install tslearn -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：使用 Conda 安装

如果你使用 Anaconda 或 Miniconda 环境：

conda install -c conda-forge tslearn

方式三：从源码安装（最新开发版）

python -m pip install https://github.com/tslearn-team/tslearn/archive/main.zip

基本使用

tslearn 的使用流程与 scikit-learn 高度一致，主要分为数据格式化、预处理和模型训练三个步骤。

1. 数据格式化

tslearn 要求输入数据为三维 numpy 数组，形状为 (样本数, 时间步长, 特征维度)。它原生支持变长时间序列。

from tslearn.utils import to_time_series_dataset

# 原始变长数据
my_first_time_series = [1, 3, 4, 2]
my_second_time_series = [1, 2, 4, 2]
my_third_time_series = [1, 2, 4, 2, 2]

# 转换为 tslearn 所需的格式 (自动填充 NaN 以对齐长度)
X = to_time_series_dataset([my_first_time_series,
                            my_second_time_series,
                            my_third_time_series])
y = [0, 1, 1]  # 标签

2. 数据预处理

为了提高模型收敛速度和效果，通常需要对时序数据进行缩放（Scaling）。

from tslearn.preprocessing import TimeSeriesScalerMinMax

# 使用最小 - 最大归一化
scaler = TimeSeriesScalerMinMax()
X_scaled = scaler.fit_transform(X)

3. 模型训练与预测

以下示例展示了如何使用 KNN 进行时序分类，其 API 风格与 scikit-learn 完全相同。

from tslearn.neighbors import KNeighborsTimeSeriesClassifier

# 初始化模型
knn = KNeighborsTimeSeriesClassifier(n_neighbors=1)

# 训练模型
knn.fit(X_scaled, y)

# 进行预测
predictions = knn.predict(X_scaled)
print(predictions)
# 输出: [0 1 1]

提示：由于兼容 scikit-learn，你可以直接将 tslearn 的模型放入 sklearn.pipeline.Pipeline 中，或使用 sklearn.model_selection.GridSearchCV 进行超参数调优。