sktime Datasets 模块完全指南：数据集对象、加载器与文件格式读写

sktime Datasets 模块完全指南数据集对象、加载器与文件格式读写【免费下载链接】sktimeA unified framework for machine learning with time series项目地址: https://gitcode.com/GitHub_Trending/sk/sktime导读sktime的datasets模块是统一机器学习框架中时间序列数据接入的枢纽本文以官方 API 参考文档 datasets.rst 为骨架系统讲解其四类核心能力数据集对象内存中的数据集表示程序化访问的首选方式、加载器函数从互联网数据仓库拉取数据集并转换为 sktime 兼容格式、玩具数据生成器教学与示例用以及时间序列专属文件格式的读写工具。读完本文你将掌握如何用一行代码加载 Airline、GunPoint、M5 等经典数据集理解数据集对象与加载器函数两条 API 路线的取舍并能自由读写.ts、.tsf、.arff、.tsv等时序专用格式。一、datasets 模块全景四类组件的定位根据 datasets.rst 的开篇定义sktime.datasets模块包含四类组件组件类型作用推荐使用场景数据集对象dataset objects时间序列数据集的内存表示程序化访问数据集的首选方式常规建模、实验脚本、需要元数据标签仓库加载器repository loaders从互联网数据仓库sktime huggingface space、Monash 仓库等拉取数据返回 sktime 兼容格式基准测试benchmarking、大体积数据集单数据集加载器individual dataset loaders获取单个常用数据集通常用于示例演示快速试验、文档示例、教学玩具数据生成器toy data generators生成教学与说明用的人造数据教程、单元测试、算法原型文件格式读写工具file format IO读写时间序列专属文件格式与外部工具链交换.ts/.tsf/.arff/.tsv数据这一设计的分层意图很明确数据集对象是一等公民加载器是底层实现细节文件格式工具则是互操作性保障。1.1 模块目录结构与导出面datasets包的组织与上述分层一一对应见 sktime/datasetsbase/数据集基类BaseDatasetforecasting/预测数据集airline.py、longley.py、lynx.py、macroeconomic.py、pbs.py、shampoo_sales.py、solar.py、uschange.py、m5_competition.py、hierarchical_sales_toydata.py、monash/classification/分类数据集acsf1.py、arrow_head.py、basic_motions.py、gunpoint.py、italy_power_demand.py、japanese_vowels.py、osuleaf.py、plaid.py、ucr_uea_archive/regression/回归数据集tecator.py_readers_writers/.ts、.tsf、.arff、.tsv、长表格式的读写实现data/随包分发的内置数据文件如Airline/Airline.csv、GunPoint/GunPoint_TRAIN.ts等。所有公开符号统一从 sktime/datasets/init.py 导出因此from sktime.datasets import load_airline与from sktime.datasets.forecasting import Airline均可正常工作。二、数据集对象程序化访问数据的推荐方式2.1 核心接口BaseDataset所有数据集对象继承自BaseDataset定义于 sktime/datasets/base/_base.py它提供了一套统一的访问协议load(*args)加载数据集。不传参数时等价于load(X, y)传入一个字符串返回单个容器传入两个及以上字符串返回同序元组。例如dataset.load(y)只取目标序列dataset.load(X_train, y_train)取训练划分keys()返回可用数据集的名称列表。无固定划分时返回[X, y]单次划分n_splits 1时额外返回X_train,y_train,X_test,y_test多次划分n_splits 1时追加cv__getitem__(key)支持dataset[y]的下标访问语法等价于dataset.load(y)get_params()/set_tags()继承自BaseObject的超参数检查与标签tags设置机制。2.2 标签tags驱动的元数据数据集对象的另一大特色是标签系统。每个数据集通过_tags字典声明自身特征例如预测数据集基类BaseForecastingDataset见 sktime/datasets/forecasting/_base.py声明的标签包括标签含义默认值is_univariate是否为单变量针对y的维度Trueis_equally_spaced观测是否等间距Truehas_nans是否含缺失值Falsehas_exogenous是否含外生变量Falsen_instances/n_instances_train/n_instances_test总体/训练/测试实例数应等于y.shape[0]None/0/0n_timepoints/n_timepoints_train/n_timepoints_test每条序列的时间点数不等长时取最大值Nonefrequency序列频率M、D等Mn_dimensionsy的列数1n_panels数据集中唯一时间序列的数量1n_hierarchy_levels层级索引层数不含时间索引0以内置的Airline为例sktime/datasets/forecasting/airline.py其标签精确刻画了数据形态is_univariateTrue、is_one_seriesTrue、n_instances1、n_timepoints144、frequencyM、n_hierarchy_levels0。标签让用户能在不加载数据的前提下查询数据形态也是测试框架 test_all_datasets.py 自动化校验数据对象与标签一致性的基础。2.3_DatasetFromLoaderMixin对象与加载器的桥接大多数内置数据集对象并不自己解析文件而是通过_DatasetFromLoaderMixinsktime/datasets/base/_base.py包装一个底层加载器函数类属性loader_func指向某个load_*函数_encode_args会把X_train/X_test等字符串映射为加载器的splitTRAIN/TEST参数并在加载器不支持划分时抛出明确的ValueError。Airline的loader_func load_airline正是这一模式的直接体现load(X, y)时还会通过_split_into_y_and_X把加载器的(y, X)输出规范化为统一的(X, y)顺序。三、预测Forecasting数据集3.1 数据集仓库ForecastingDataForecastingData 是通用预测仓库加载器接口指向 Monash 时间序列预测仓库load_forecastingdata覆盖金融、旅游、医疗、能源、零售等领域的基准数据集。使用方式from sktime.datasets import ForecastingData dataset ForecastingData(namecif_2016_dataset) y dataset.load(y)其实现要点见 monash/_forecasting_data.py构造函数按name查表DATASET_TAGS定义于 monash/_tags.py自动为对象打上对应数据集的元数据标签预测数据没有固定的 train/test 划分因此ForecastingData._encode_args对X_train等字符串直接抛出InvalidSetError提示请自行做时间划分load方法在 monash/_forecasting_data.py 中有完整实现数据在首次使用时从 sktime 的 huggingface space 下载并缓存cached on first use返回pd_multiindex格式实例 × 时间点双层索引的目标序列y与可选外生变量X频率映射表把仓库的yearly/quarterly/monthly/daily/hourly等标签转换为 pandas 的YS/QS/ms/D/H频率对 M4 系列等时间戳存在原始错误的子集FORCE_RANGEINDEX则退化为RangeIndex并给出警告。3.2 随包内置的预测数据集离线可用以下数据集对象随 sktime 分发无需网络即可使用数据文件位于 sktime/datasets/data数据集对象数据内容文件位置AirlineBox Jenkins 经典航空旅客月度数据1949–1960144 个点单变量、月度data/Airline/Airline.csvLongley宏观经济计量学经典数据集就业人口等 7 个变量1947–1962data/Longley/Longley.csvLynx1821–1934 年加拿大山猫皮毛年捕获量单变量data/Lynx/Lynx.csvMacroeconomic美国宏观经济时间序列季度data/下对应 csvPBS澳大利亚药品补贴计划PBS处方数据层级序列data/PBS_dataset/PBS_dataset.csvShampooSales月度洗发水销量经典示例数据data/ShampooSales/ShampooSales.csvUSChange美国个人消费支出增长率等多变量季度数据1960–2016data/Uschange/Uschange.csvHierarchicalSalesToydata层级销售玩具数据教学用层级结构清晰_hierarchical_demo.py生成M5DatasetM5 预测竞赛数据集详见下节随包注册但数据按需下载下载后缓存典型用法来自 Airline 的 docstring 示例from sktime.datasets.forecasting import Airline dataset Airline() y dataset.load(y) # 只取目标序列3.3 下载型预测数据集M5Dataset与Solar这两个对象属于下载后缓存类型对象本身随包可用但数据体积大首次load时自动下载M5Datasetm5_competition.pyM5 Accuracy 竞赛数据包含约 5900 万行日度销售记录、30,490 条底层序列、5 级层级state_id → store_id → dept_id → cat_id → item_id → date六层多索引。加载过程将sales_train_evaluation.csv、sell_prices.csv、calendar.csv三个文件合并为y销售额与X事件、促销、售价等外生变量并按最后 28 天为测试集切分从而支持load(X_train, y_train)等划分调用。下载源为 Zenodom5-forecasting-accuracy.zip经 DatasetDownloader 处理首次下载后缓存Solar太阳能发电预测数据集同样按需下载、缓存。from sktime.datasets.forecasting import M5Dataset dataset M5Dataset() y, X dataset.load(y, X) # 全量 y_train, X_train dataset.load(y_train, X_train) # 最后 28 天之前四、分类Classification数据集4.1 数据集仓库UCRUEADatasetUCRUEADataset 是 UCR/UEA 时间序列分类档案库的程序化接口。数据从 sktime 的 huggingface space 下载并首次使用后缓存实例化时指定档案库中的数据集名称即可from sktime.datasets.classification import UCRUEADataset dataset UCRUEADataset(nameArrowHead) X_train, y_train dataset.load(X_train, y_train) X_test, y_test dataset.load(X_test, y_test)由于 UCR/UEA 档案自带固定 train/test 划分n_splits1keys()会返回全部六个集合。底层加载逻辑由 _data_io.py 的_load_dataset承担先在sktime/datasets/data目录查找本地文件找不到则检查缓存目录local_data仍不存在则通过多镜像下载——主镜像为 timeseriesclassification.com 的 aeon-toolkit备用镜像为 sktime-datasets 仓库下载失败会抛RuntimeError。4.2 随包内置的分类数据集离线可用数据集对象特点文件位置ACSF1声学/工业信号分类data/ACSF1ArrowHead单变量等长序列箭镞轮廓分类data/ArrowHeadBasicMotions等长多变量序列人体动作识别data/BasicMotionsGunPoint150 点的动作识别二分类data/GunPointItalyPowerDemand意大利电网日负荷二分类data/ItalyPowerDemandJapaneseVowels日语元音识别多分类data/JapaneseVowelsOSULeaf叶片轮廓分类6 类427 点data/OSULeafPLAID不等长序列的典型示例电器负荷识别data/PLAIDfrom sktime.datasets.classification import OSULeaf dataset OSULeaf() X, y dataset.load() # 等价于 load(X, y) X_train, y_train dataset.load(X_train, y_train)分类基类同样继承BaseDataset各数据集标签声明了n_instances、n_timepoints、类别数等形态信息可被测试套件 test_all_classification_datasets.py 自动校验。五、回归Regression数据集回归任务目前内置一个数据集对象Tecatorsktime/datasets/regression/tecator.py数据来源通过近红外吸收光谱波长 850–1050 nm测量肉类脂肪含量形态单变量、每条序列 100 个光谱点训练 172 例、测试 43 例共 215 个样本目标变量连续值脂肪含量因此load_tecator的默认y_dtypefloat与分类数据集的str形成对比见 _single_problem_loaders.py。from sktime.datasets.regression import Tecator dataset Tecator() X, y dataset.load()六、加载器函数Loader Functions文档明确指出加载器是返回 sktime 兼容格式的原始函数程序化访问数据集时应优先使用上文的数据集对象加载器主要用于基准测试与底层复用。所有加载器统一从sktime.datasets导出。6.1 数据集仓库加载器支持按字符串指定数据集函数数据来源典型用途load_forecastingdata(name, ...)Monash 预测仓库huggingface space首次使用缓存基准测试的多数据集批量访问load_fpp3(dataset, temp_folderNone)R 生态 fpp3 包的数据_fpp3_loaders.py复现《Forecasting: Principles and Practice》示例load_m5(extract_pathNone, include_eventsFalse)M5 竞赛Zenodo大规模层级预测基准_single_problem_loaders.pyload_UCR_UEA_dataset(name, splitNone, return_X_yTrue, return_typeNone, extract_pathNone, y_dtypestr)UCR/UEA 档案库多镜像下载分类/回归基准测试load_UCR_UEA_dataset是最常用的基准测试入口其关键参数splitNone默认训练测试合并加载、train或test按name_TRAIN.ts/name_TEST.ts加载return_X_yTrue时分别返回(X, y)False时把类别标签拼进X的最后一列return_type控制返回的内存格式Panel mtype常用取值包括numpy3D/np3D3D 数组实例×变量×时间、numpy2d/np2d2D 数组、pd-multiindex实例×时间双层索引 DataFrame、默认nested_univ单元格内嵌pd.Series的嵌套 DataFrame若数据无法转换为请求类型会抛出异常extract_path指定查找/下载数据的目标路径默认先在sktime/datasets/data查本地文件否则下载到local_datay_dtype标签的 dtype默认str。from sktime.datasets import load_UCR_UEA_dataset X, y load_UCR_UEA_dataset(nameArrowHead) # 全量合并 X_train, y_train load_UCR_UEA_dataset( nameArrowHead, splittrain, return_typenumpy3D # 转 3D 数组 )6.2 单条时间序列加载器这些函数加载单条单变量/多变量时间序列返回pd.Series如load_airline或(y, X)元组如load_uschange函数返回说明load_airline()y144 点月度航空旅客量索引被规范为月度PeriodIndex实现见 _single_problem_loaders.py#L921-L961load_longley()yLongley 宏观经济数据集load_lynx()y加拿大山猫年捕获量load_macroeconomic()y美国宏观经济季度数据load_shampoo_sales()y月度洗发水销量load_solar()y太阳能数据下载型load_uschange(y_nameConsumption)(y, X)多变量消费、收入、生产、储蓄、失业率可用y_name指定目标列实现见 #L964-L1016from sktime.datasets import load_airline, load_uschange y load_airline() # pd.Series月度索引 y, X load_uschange(y_nameIncome) # 目标列切换为收入6.3 面板Panel加载器面板加载器返回多个时间序列实例集合对应分类/回归任务。文档列出分类面板load_acsf1、load_arrow_head、load_basic_motions、load_gunpoint、load_italy_power_demand、load_japanese_vowels、load_osuleaf另有load_plaid在 __init__.py 中一并导出回归面板load_tecator特殊面板load_macroeconomic文档中同时列于单序列与面板节按多变量序列处理。这些函数共享统一签名(splitNone, return_X_yTrue, return_typeNone)split取值None/TRAIN/TEST注意与load_UCR_UEA_dataset的小写train不同return_type语义与上文一致from sktime.datasets import load_gunpoint, load_tecator X, y load_gunpoint() # 训练测试合并 X_train, y_train load_gunpoint(splitTRAIN) # 仅训练集 X, y load_tecator(y_dtypefloat) # 回归任务连续目标6.4 玩具数据生成器层级数据load_hierarchical_sales_toydata()定义于 sktime/datasets/_hierarchical_demo.py生成带层级结构如区域→店铺→商品的销售数据返回 sktime 的pd_multiindex_hier格式 DataFrame。它常被用于快速验证层级聚合、层级预测等流水线无需下载任何外部数据from sktime.datasets import load_hierarchical_sales_toydata data load_hierarchical_sales_toydata()七、时间序列专属文件格式读写工具文档强调这些工具处理时间序列专属格式对于非时序专属格式如普通 CSV应使用pandas.read_csv等通用工具。所有读写函数均从sktime.datasets导出。7.1 读取器函数格式说明load_from_tsfile(full_file_path_and_name, ...).tsUCR/UEA 档案的标准格式每行一条可能多变量时间序列维度以冒号分隔、序列内数值以逗号分隔文件头包含problemName、dimension、timestamps、classLabel等元数据标签load_from_tsfile_to_dataframe(...).ts将.ts文件读入 DataFrame 的精简封装核心解析逻辑见 _readers_writers/ts.py支持return_separate_X_and_y、replace_missing_vals_withNaN、encoding、y_dtype参数load_from_ucr_tsv_to_dataframe(...).tsvUCR 老式制表符分隔格式见 _readers_writers/tsv.pyload_from_arff_to_dataframe(...).arffWEKA 生态的 ARFF 格式见 _readers_writers/arff.pyload_from_long_to_dataframe(full_file_path_and_name, separator,)长表每行一个观测的实例、时间点、值长表格式见 _readers_writers/long.pyload_tsf_to_dataframe(...).tsfForecasting.org/Monash 仓库的.tsf格式见 _readers_writers/tsf.py支持replace_missing_vals_withNaN仓库中附带测试文件如 data/UnitTest/UnitTest.tsf典型用法——从磁盘读取一个.ts分类数据集并指定内存格式from sktime.datasets import load_from_tsfile_to_dataframe X, y load_from_tsfile_to_dataframe( path/to/Dataset_TRAIN.ts, return_separate_X_and_yTrue, y_dtypestr, )7.2 写入器函数用途write_panel_to_tsfile(data, path, problem_name..., ...)把面板数据写为.ts文件write_dataframe_to_tsfile(...)把 DataFrame嵌套或多索引写为.ts文件write_ndarray_to_tsfile(...)把 3D/2D ndarray 面板写为.ts文件write_tabular_transformation_to_arff(...)把表格型特征变换结果写为.arffWEKA 兼容write_results_to_uea_format(estimator_name, dataset_name, ...)把分类器在基准数据集上的预测结果按 UEA 官方格式写出便于结果汇总与复现签名见 _readers_writers/utils.py配合读取器可以形成完整的外部数据 → sktime 建模 → 结果导出闭环。write_results_to_uea_format尤其适合复现经典分类基准实验的评测流程。八、底层机制与工程细节8.1 下载与缓存策略无论是UCRUEADataset、ForecastingData还是load_UCR_UEA_dataset下载流程统一收敛到 DatasetDownloader优先从 sktime 的 huggingface space 拉取支持fallback_urls备用源_cache_dataset_data_io.py实现了多镜像、按序重试repeats参数、verbose 进度打印策略。下载后的数据缓存在sktime/datasets/data内置或local_data下载缓存目录BaseDataset.cache_files_directory()与cleanup_cache_files()提供了缓存目录查询与清理能力见 base/_base.py。8.2 加载器的查找优先级_load_dataset_data_io.py的查找链为用户指定extract_path→ 内置sktime/datasets/data→ 下载缓存local_data→ 联网下载。_list_available_datasets通过检查目录内是否存在name_TRAIN.tsname_TEST.ts分类或name.tsf预测仓库来判断数据集是否已就绪。8.3 数据集对象与加载器的一致性保障仓库提供了多套自动化测试来保证两类 API 的结果一致性与标签正确性test_all_datasets.py通用数据集对象校验load()、keys()、标签一致性test_all_forecasting_datasets.py 与 test_all_classification_datasets.py分别校验预测与分类数据集的形态标签test_readers_writers.py对.ts/.tsf等格式做读写往返round-trip测试test_loaders.py 与 test_single_problem_loaders.py验证各加载器的输出格式与分割行为。这也是建议优先使用数据集对象的原因之一它们把加载 元数据 划分约定封装为可测试、可自查的单一入口。九、实践决策对象还是函数综合全文两条 API 路线的选择可归纳如下优先用数据集对象Airline()、UCRUEADataset(name...)、M5Dataset()等当需要元数据标签、希望获得X/y/X_train/y_train等统一的程序化访问协议、或需要缓存清理等附加能力时用加载器函数load_UCR_UEA_dataset、load_forecastingdata、load_airline等当只需一次性获取数据、按字符串批量枚举仓库数据集做基准测试、或作为自定义数据集的底层实现即loader_func时。两者共享同一套.ts/.tsf等格式解析内核与下载缓存机制结果完全互通可按场景自由切换。总结sktime.datasets模块通过数据集对象 加载器函数 文件格式 IO三层结构覆盖了时间序列数据接入的全部典型场景从开箱即用的 Airline、GunPoint、OSULeaf 等内置示例数据到 UCR/UEA 档案与 Monash/M5 等大型基准仓库的程序化访问再到.ts/.tsf/.arff/.tsv等时序专属格式的读写互操作。理解 datasets.rst 勾勒的这一体系是高效使用 sktime 进行预测、分类、回归与基准测试的第一步——无论是快速原型验证还是大规模可复现实验都能找到对应的标准接入方式。【免费下载链接】sktimeA unified framework for machine learning with time series项目地址: https://gitcode.com/GitHub_Trending/sk/sktime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考