sktime 时间序列聚类 API 全指南从 K-Means 到时空聚类的统一框架【免费下载链接】sktimeA unified framework for machine learning with time series项目地址: https://gitcode.com/GitHub_Trending/sk/sktimesktime 的sktime.clustering模块为时间序列聚类提供了统一的算法家族划分式K-Means、K-Medoids、K-Shape、谱与核聚类、密度聚类DBSCAN、层次聚类Agglomerative、基于可见图网络的聚类K-visibility以及面向空间观测的时空聚类ST-DBSCAN并提供ClustererPipeline、ClustererAsTransformer等组合工具。本文将以 clustering.rst 的 API 目录为骨架结合模块源码讲解每个算法的参数、调用链与实战用法帮助你基于统一接口完成从选算法到端到端聚类流水线的全过程。模块定位一切从sktime.clustering开始sktime.clustering模块源码位于 sktime/clustering/集中了所有时间序列聚类算法。与分类、回归等模块一致所有 clusterer 都遵循同一套BaseClusterer接口因此会用一个就会用全部。模块目录结构如下base.py抽象基类BaseClusterer定义统一接口与输入校验partitioning/通用划分式算法底层实现BaseTimeSeriesLloyds类 Lloyd 迭代框架k_means/、k_medoids.py、k_shapes.py划分式聚类kernel_k_means.py核/谱聚类dbscan.py密度聚类agglomerative.py层次聚类kvisibility.py图可见图网络聚类spatio_temporal/时空聚类STDBSCANcompose/ClustererPipeline、SklearnClustererPipeline、ClustererAsTransformermetrics/聚类内部使用的平均/中位数medoids计算工具例如metrics.averaging、metrics.medoids。如何发现与检索所有 clusterer官方 API 文档明确给出了三条发现算法的途径sktime.registry.all_estimators通过estimator_typesclusterer列出全部 clusterer并可按标签tag过滤。该工具在 sktime/registry/_lookup.py 中实现例如from sktime.registry import all_estimators all_clusterers all_estimators(estimator_typesclusterer) # 返回 [(name, estimator_class), ...] 形式的列表 # 按标签过滤只保留支持多元时间序列的 clusterer multivar_clusterers all_estimators( estimator_typesclusterer, filter_tags{capability:multivariate: True}, )sktime.registry.all_tags列出 clusterer 的合法标签全集便于组合过滤条件对应实现同样位于 sktime/registry/_lookup.pyall_tags(estimator_types)函数。Estimator 搜索页仓库文档中的 estimator_overview.md 提供了可视化检索表在 Estimator type 下拉框中选择 clustering 即可按标签筛选算法。clusterer 的核心标签tag定义在 base.py 的_tags中主要包括标签默认值含义capability:multivariateFalse是否支持多元时间序列capability:unequal_lengthFalse是否支持不等长序列capability:missing_valuesFalse是否支持缺失值capability:out_of_sampleTrue是否支持对未见样本预测capability:predict/capability:predict_probaTrue是否支持predict/predict_probaX_inner_mtypenumpy3D内部_fit/_predict接受的输入 mtype统一接口BaseClusterer所有 clusterer 都继承自 BaseClusterer基类定义了六个公共方法与一组输入校验逻辑。核心方法fit(X, yNone)拟合模型。调用前会执行reset()清空状态通过_check_clusterer_input校验输入后调用私有方法_fit并记录fit_time_毫秒y仅为 API 一致性保留实际被忽略。predict(X, yNone) - np.ndarray返回形状(n_instances,)的一维数组每个元素是样本所属簇的索引。fit_predict(X, yNone) - np.ndarray等价于fit(X)后紧跟predict(X)的便捷方法源码实现非常直观。predict_proba(X)返回形状(n_instances, n_classes)的概率矩阵默认实现把预测簇概率置 1、其余置 0基类默认逻辑中还将-1噪声/无簇样本的概率行全置 0。score(X, yNone) - float评估聚类质量默认由子类实现。输入数据格式fit/predict接受任意Panelscitype 的 mtype基类通过check_is_scitype校验后统一转换到X_inner_mtype详见 base.py 的_check_clusterer_input。常见输入包括numpy3D3D 数组形状[n_instances, n_dimensions, series_length]要求等长pd-multiindexpd.DataFrame列对应变量MultiIndex第一层为实例索引、第二层为时间索引其他受支持的 Panel mtype 可参考 sktime/datatypes/_registry.py。基类还通过_check_capabilitiesbase.py依据标签校验数据能力若数据含缺失值、多元或不等长而标签不允许会抛出明确错误信息。此外聚类模块不支持分类特征输入会抛TypeError。派生接口与魔术乘法BaseClusterer还重载了__rmul__base.py使transformer * clusterer可以自动构造ClustererPipeline这是后面组合器章节的语法糖基础。划分式Partitioning聚类划分式聚类是本模块最常用的算法族核心是把时间序列按某种距离度量划分到n_clusters个簇中。模块同时提供 sktime 原生实现与 tslearn 适配实现。TimeSeriesKMeans原生时间序列 K-MeansTimeSeriesKMeans 继承自BaseTimeSeriesLloyds是性能优化的原生实现底层依赖 numba 加速的pairwise_distance。关键参数如下参数默认值说明n_clusters8簇数量即质心数量init_algorithmrandom初始化方法可选[kmeans, random, forgy]也可直接传形状(n_clusters, n_dimensions, series_length)的 3D 数组作为初始质心metricdtw距离度量可选[dtw, euclidean, erp, edr, lcss, squared, ddtw, wdtw, wddtw]n_init10以不同质心种子运行的次数最终返回惯性inertia最优的一次max_iter300单次运行最大迭代次数tol1e-6两次迭代质心差异的 Frobenius 范数相对容差用于判定收敛averaging_methodmean簇内平均方法可选[mean, dba]DBA DTW Barycenter Averaging也支持Callable[[np.ndarray], np.ndarray]average_params/distance_paramsNone分别传递给平均方法与距离度量的关键字参数拟合后产生的属性包括cluster_centers_形状(n_clusters, n_dimensions, series_length)的质心序列、labels_各样本簇标签、inertia_样本到最近质心距离平方和与n_iter_实际迭代次数。值得注意的是 DBA 路径的底层优化_fit会先用pairwise_distance预计算样本间两两距离矩阵之后在_compute_new_cluster_centers同一文件中按簇内索引切片复用避免重复计算。源码中还处理了 DDTW/WDDTW 到 DTW/WDTW 的距离回落见__init__。官方 docstring 提供了基于 ArrowHead 数据集的最小示例from sktime.datasets import load_arrow_head from sktime.clustering.k_means import TimeSeriesKMeans X_train, y_train load_arrow_head(splittrain) X_test, y_test load_arrow_head(splittest) clusterer TimeSeriesKMeans(n_clusters3) clusterer.fit(X_train) y_pred clusterer.predict(X_test)TimeSeriesKMeansTslearntslearn 适配版TimeSeriesKMeansTslearn定义于 sktime/clustering/k_means/_k_means_tslearn.py是 tslearn 官方 K-Means 的轻量适配接口与原生版对齐n_clusters8、metricdtw、n_init10、max_iter300等适合需要与 tslearn 生态对齐或依赖其 Soft-DTW 等实现的场景。TimeSeriesKMedoidsK-MedoidsTimeSeriesKMedoids 以簇内实际样本medoids作为簇代表对噪声和异常值更稳健且天然支持任意距离度量无需计算平均。其默认init_algorithmforgy、max_iter30其余参数n_clusters8、metricdtw、n_init10、tol1e-6与 K-Means 一致底层通过 sktime/clustering/metrics/medoids.py 的medoids函数计算簇代表。TimeSeriesKShapesK-ShapeTimeSeriesKShapes 基于 tslearn 的KShape实现专为形状相似性设计使用互相关cross-correlation度量并通过归一化对齐消除幅值与相位影响适合形态驱动的聚类任务。其标签声明支持多元序列capability:multivariateTrue。谱与核聚类TimeSeriesKernelKMeansTimeSeriesKernelKMeans 通过_TslearnAdapter直接接口tslearn.clustering.KernelKMeans。核方法将序列隐式映射到高维特征空间能够捕获线性不可分的结构。参数默认值说明n_clusters8簇数量kernelgak核函数gakGlobal Alignment Kernel或 scikit-learnpairwise_kernels接受的度量字符串kernel_paramsNone核参数GAK 仅关注sigmaauto时基于训练集采样自动计算默认 1n_init/max_iter/tol10/300/1e-4与 K-Means 语义一致n_jobsNoneGAK 交叉相似矩阵计算的并行任务数-1表示使用全部处理器密度聚类TimeSeriesDBSCANTimeSeriesDBSCAN 是 sklearnDBSCAN与 sktime 时间序列距离的桥接把时间序列距离喂给 DBSCAN自动发现任意形状的簇并把噪声标记为-1。其distance参数支持三种形态详见 dbscan.py字符串从sktime.dists_kernels._numba_distances选取硬编码距离可选euclidean, squared, dtw, ddtw, wdtw, wddtw, lcss, edr, erp, msm, twe这类距离性能好但默认不支持不等长或多元序列sktime 成对 transformer实现pairwise-transformer接口的对象位于sktime.dists_kernels可通过capability:unequal_length、capability:multivariate标签筛选支持不等长/多元的版本且可组合可调用对象签名(X: Panel, X2: Panel) - np.ndarray参数经distance_params传入。其余关键参数eps0.5邻域最大距离需按数据与距离函数调优、min_samples5核心点最小邻域样本数含自身、algorithmauto、leaf_size30、n_jobsNone。拟合后可从labels_噪声为-1、core_sample_indices_、components_读取结果。层次聚类TimeSeriesAgglomerativeClusteringTimeSeriesAgglomerativeClustering 基于 scipy 实现自底向上的凝聚式聚类每次递归合并使指定链接linkage距离增量最小的两个簇。参数默认值说明n_clusters2目标簇数量linkageaverage链接准则如ward,average,complete,singledistancedtw距离度量字符串或成对 transformer字符串取值受 sktime/base/_panel/knn.py 的DISTANCES_SUPPORTED约束并会校验distance_paramsNone传给距离度量的参数该算法标签声明支持多元、不等长与缺失值capability:multivariate/unequal_length/missing_valuesTrue但capability:out_of_sampleFalse即只能对训练数据本身预测。其_fitagglomerative.py通过_SklearnDistanceAdapter将距离适配给 scipy 的linkage/fcluster拟合后可访问labels_与linkage_matrix_。图/网络聚类TimeSeriesKvisibilityTimeSeriesKvisibility 采用可见图visibility graph思想先把每条时间序列转换为图基于图的结构度量构造特征再用 sklearn 的KMeans完成聚类。其initk-means、n_initautoauto时根据init取值自动选择运行次数random/callable 时为 10k-means/数组时为 1、n_clusters5。时空聚类STDBSCAN时空聚类器假设时间序列是或包含空间位置的观测。STDBSCAN 实现了 Birant 等人提出的 ST-DBSCAN 算法依据空间与时间双重邻近阈值聚类。参数默认值说明eps10.5空间邻域最大距离eps210时间邻域最大距离min_samples5形成核心点的最小样本数metriceuclidean空间距离度量euclidean,manhattan,chebyshev等sparse_matrix_threshold20000超过该样本数时切换为稀疏矩阵方式计算距离避免内存爆炸frame_size/frame_overlapNone/eps2分帧处理的时间点跨度与帧间重叠用于大规模数据的分治n_jobs-1距离计算并行数Compose组合器与流水线sktime.clustering.compose提供了三个与聚类相关的组合器。ClustererPipeline / SklearnClustererPipelineClustererPipeline 将一串 transformer 与一个 clusterer 串成流水线fit时依次对X执行trafo1.fit_transform → trafo2.fit_transform → … → clst.fitpredict/predict_proba同理先transform再交给 clusterer。构造方式有两种from sktime.transformations.pca import PCATransformer from sktime.clustering.k_means import TimeSeriesKMeans from sktime.clustering.compose import ClustererPipeline # 方式一显式构造 pipeline ClustererPipeline( clustererTimeSeriesKMeans(), transformers[PCATransformer()], ) # 方式二魔术乘法dunder——transformer 在 * 左边 pipeline PCATransformer() * TimeSeriesKMeans()流水线的能力标签是动态推导的见__init__只有当 clusterer 与全部 transformer 都支持时capability:multivariate等标签才为True但若 transformer 链能消除问题如capability:missing_values:removes、capability:unequal_length:removes则对应能力也会被开启。get_params/set_params遵循 sklearn 嵌套命名规范。SklearnClustererPipeline是同一组合器的 sklearn 版本变体用于混入 sklearn 聚类器场景。ClustererAsTransformerClustererAsTransformer 把 clusterer 包装成 transformer将序列 → 原始特征的变换转换为序列 → 簇指派series-to-primitives即transform直接调度到predict。它常用于强制类型转换场景要求目标 clusterer 具备capability:predict。示例见官方 docstring_as_transform.pyfrom sktime.clustering.compose import ClustererAsTransformer from sktime.clustering.dbscan import TimeSeriesDBSCAN from sktime.dists_kernels import AggrDist from sktime.datasets import load_unit_test X, _ load_unit_test(splittrain) clusterer TimeSeriesDBSCAN(AggrDist.create_test_instance()) cluster_assign_trafo ClustererAsTransformer(clusterer) cluster_assign_trafo.fit(X) cluster_assignment cluster_assign_trafo.transform(X)底层框架BaseTimeSeriesLloydsBaseTimeSeriesLloydssktime/clustering/partitioning/_lloyds.py是所有 Lloyd 式迭代聚类器TimeSeriesKMeans、TimeSeriesKMedoids等的公共基类。它固化了初始化质心 → 指派样本 → 依据_compute_new_cluster_centers更新质心 → 检查收敛的迭代骨架子类只需实现质心更新逻辑即可复用整套参数体系与收敛控制。这解释了为什么 K-Means 与 K-Medoids 的构造参数高度一致。端到端实战示例结合上述 API一个完整的聚类与流水线实战如下数据集与示例可参考仓库的 partition_based_clustering.ipynbfrom sktime.datasets import load_arrow_head from sktime.clustering.k_means import TimeSeriesKMeans from sktime.clustering.compose import ClustererPipeline from sktime.transformations.pca import PCATransformer from sktime.registry import all_estimators # 1) 探索列出全部 clusterer 并按标签过滤 clusterers all_estimators( estimator_typesclusterer, filter_tags{capability:multivariate: False}, ) # 2) 加载数据Panel scitype X_train, _ load_arrow_head(splittrain) X_test, _ load_arrow_head(splittest) # 3) 直接使用原生 K-MeansDTW DBA 平均 kmeans TimeSeriesKMeans( n_clusters3, metricdtw, averaging_methoddba, random_state42, ) kmeans.fit(X_train) labels kmeans.predict(X_test) proba kmeans.predict_proba(X_test) # 4) 或构造 PCA K-Means 流水线 pipeline ClustererPipeline( clustererTimeSeriesKMeans(n_clusters3), transformers[PCATransformer()], ) pipeline.fit(X_train) pipe_pred pipeline.predict(X_test)注意使用dba平均或非默认距离时可通过average_params、distance_params传入相应超参数例如 DBA 的medoids_distance_metric、averaging_distance_metric见 k_means/_k_means.py 的解析逻辑。测试与质量保障本模块的算法行为由一套统一测试与针对性单测覆盖是理解接口契约的可靠参考sktime/clustering/tests/test_all_clusterers.py框架级全量 clusterer 测试通过get_test_params构造实例sktime/clustering/tests/test_k_means.py、test_k_medoids.py、test_k_shapes.py、test_kernel_k_means.py、test_lloyds.py、test_agglomerative.py各算法的针对性验证sktime/clustering/compose/tests/test_pipeline.py流水线组合与魔术乘法行为测试。小结sktime.clustering的价值在于统一接口 算法谱系 组合能力三位一体无论是划分式、核、密度、层次、图还是时空聚类都共享 BaseClusterer 的fit/predict/fit_predict/predict_proba契约与标签驱动的能力声明通过all_estimators可按标签在十余种算法中精准检索通过ClustererPipeline与魔术乘法可以极简地把预处理变换与聚类器组装成端到端流水线。对于性能敏感场景优先使用 numba 加速的原生TimeSeriesKMeans并合理配置averaging_method与distance_params对于需要表达力的复杂结构则可在核聚类、层次与图聚类之间按数据特性取舍。【免费下载链接】sktimeA unified framework for machine learning with time series项目地址: https://gitcode.com/GitHub_Trending/sk/sktime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考