hydrodataset:统一水文数据下载与读取工具
数据集简介
设计理念
hydrodataset 的核心目标是为水文建模与深度学习工作流提供一致的数据访问体验。它被设计为 AquaFetch 包之上的数据适配层,把来源各异、命名不一的公开水文数据集收敛到同一套接口之下。使用者无需为每个数据集分别编写下载与解析脚本,也无需在建模前手工对齐变量名——包内统一了变量命名,使数据可以直接进入 torchhydro 等水文建模库的训练流程。
安装方式
项目以 MIT 许可证开放,公开免费使用,可通过多种 Python 包管理工具安装:
- pip:
pip install hydrodataset - uv:以 uv 方式安装同一包
- conda-forge:从 conda-forge 渠道获取
快速开始
首次访问某个数据集时,hydrodataset 会经 AquaFetch 自动下载原始数据,并标准化处理为缓存文件。主要入口包括:
open_dataset(dataset_id, source="local"|"cloud"):按数据集标识打开数据,source参数决定读取本地还是云端缓存。resolve_data_path(dataset_id):解析指定数据集的存储路径。available_static_features/available_dynamic_features:查询数据集提供的静态与动态特征。
数据以「时间序列 + 属性」的形式组织,对应水文建模中常见的动态强迫与静态流域属性两类输入。
本地与云端数据访问
标准化后的数据按访问方式落入两种存储形态:本地为 NetCDF 缓存,云端为 Zarr 缓存,后者支持即时加载。存储位置与默认数据源通过用户主目录下的 ~/hydro_setting.yml 配置,涉及 storage.local.root 与 storage.default_source 两项设置。
支持的数据集
当前覆盖 27 个公开水文数据集,包括 CAMELS-US、CAMELS-AUS、CAMELS-BR、CAMELS-CL、CAMELS-COL、LamaH-CE、HYSETS 等。各数据集规模差异明显:CAMELS-CL、CAMELS-COL 等不足 1GB,而 HYSETS 等大型数据集超过 30GB,下载耗时约 3–6 小时甚至更久。
关键特性
- 27 个水文数据集共用一致的 API,降低多数据集实验的切换成本。
- 首次访问自动下载并标准化,后续直接读取缓存。
- 本地 NetCDF、云端 Zarr 双形态缓存,兼顾离线分析与云端即时加载。
- 统一变量命名,便于与 torchhydro 等建模库集成。
项目状态
仓库目录包含 .github、docs、examples、hydrodataset、scripts、tests,提供文档、示例与测试代码。项目当前版本发布于 2026-10-13。
致谢
仓库作者为 OuyangWenyu;数据获取依赖 hyex-research 的 AquaFetch 包,本库在其之上承担数据适配层角色。