WFSFA Harmonized Soil Moisture Data

主要输出是一个经过整理的、标准化的土壤湿度观测数据集，来自科罗拉多州东河流域Watershed Function Science Focus Area（WFSFA）的25个ESS-DIVE数据包。该协调数据集包括14个具有有效土壤湿度测量的协调数据包，采用标准化模式（包括通用变量名称、单位、时间格式），包含基于UUID的地理空间元数据，以及通过JSON映射文件链接协调变量与原始来源的完整溯源信息。关键特征包括：用于易于聚合和时间序列分析的长格式结构、体积含水量、重量含水量和水势测量、近似深度和缺失地理定位数据的质量控制标志、UTC时区的ISO-8601时间戳、以及链接的具有WGS-84坐标的站点元数据。The primary output is a curated and standardized soil moisture observation dataset sourced from 25 ESS-DIVE data packages from the East River Watershed within the Watershed Function Science Focus Area (WFSFA) in Colorado, USA. This harmonized dataset includes 14 harmonized data packages with valid soil moisture measurements, adhering to standardized schemas including uniform variable names, measurement units, and time formatting conventions. It also contains UUID-based geospatial metadata, as well as complete provenance information that links harmonized variables to their original sources via JSON mapping files. Key features include: long-format structure for straightforward aggregation and time-series analysis, volumetric water content, gravimetric water content and water potential measurements, quality control flags for approximate depth data and missing geolocation data, ISO-8601 compliant timestamps in the UTC timezone, and linked site metadata with WGS-84 geographic coordinates.

原始信息汇总

数据集概述

该仓库专注于从环境和生态数据源创建适用于AI的基准数据集，核心目标是整合异构数据集以支持机器学习和模型基准测试应用。

主要目标与功能

• 从环境数据仓库（如ESS-DIVE）发现和检索数据集
• 将异构数据整合为标准化、分析就绪的格式
• 为水文和陆地生态系统模型创建精选基准数据集
• 记录数据转换过程和来源，确保可重复性

当前重点: 美国科罗拉多州东河（East River）流域的流域功能科学重点区（WFSFA）的土壤湿度数据，数据存档于ESS-DIVE。

仓库结构

benchmark-datasets/ ├── data/ # 数据目录 │ ├── external/ # 第三方源数据 │ ├── intermediate/ # 过滤/处理的中间输出 │ └── processed/ # 处理后的数据集元数据 ├── berdl_import/ # BERDL导入工作流 │ ├── scripts/ # 构建、模式生成和导入脚本 │ ├── schema/ # 生成的BERDL模式文档 │ ├── downloaded_data/ # 下载的源文件 │ ├── data/ # 生成的BERDL导入包 │ └── local_logs/ # 本地管道日志 ├── notebooks/ # 数据处理脚本 ├── skills/ # AI辅助工作流技能 ├── src/ # Python包源码 └── tests/ # 单元和集成测试

关键数据集

WFSFA 整合土壤湿度数据

主要产出是一套精选、标准化的土壤湿度观测数据集，涵盖东河流域25个ESS-DIVE数据包，包含14个有效的整合数据包。

关键特征:

• 统一变量名、单位和时间格式的标准化模式
• 基于UUID的地点整合地理空间元数据
• 通过JSON映射文件提供完整的来源追踪
• 长格式结构，便于聚合和时间序列分析
• 包含体积含水量、重量含水量和水势测量值
• 针对近似深度和缺失地理定位数据的质量控制标志
• UTC时区的ISO-8601时间戳
• 附有WGS-84坐标的地点元数据

BERDL 流域SFA土壤湿度导入

将整合后的WFSFA土壤湿度文件转换为bervodata_watershed_sfa_soil_moisture BERDL数据库。

当前BERDL表集合包含:

• sdt_dataset
• sdt_location
• sdt_harmonized_location
• ddt_soil_moisture_observation
• ddt_ndarray
• sys_typedef
• sys_ddt_typedef
• sys_oterm

关键脚本与工作流

notebooks/scrape_ess-dive.py — ESS-DIVE数据集发现与检索

1. 通过API获取所有公开ESS-DIVE包的元数据
2. 按空间范围（东河流域边界框）筛选数据集
3. 识别土壤和地下相关数据包
4. 下载选定数据文件和元数据

notebooks/harmonize_ess-dive_soilmoisture_data.py — 数据整合工作流

1. 从ESS-DIVE包记录中提取元数据
2. 文件级变量映射和单位转换
3. 时间戳标准化为UTC ISO-8601格式
4. 深度单位归一化（地标以下米）
5. 宽表转长表格式重塑（每行一个测量值）
6. 通过空间聚类分配UUID进行地点整合
7. 质量控制和验证
8. 生成JSON映射文档

AI辅助工作流

WFSFA 土壤湿度整合技能

• 位置: skills/wfsfa_sm_harmonization/
• 功能: 交互式评估、代码生成、映射文档生成、质量保证
• 产出: 整合脚本Python代码、JSON映射条目、包含/排除决策、质量控制标志

流域SFA土壤湿度BERDL查询技能

• 位置: skills/watershed-sfa-soil-moisture-berdl-query/
• 功能: 根据当前WFSFA土壤湿度表名和列名撰写BERDL SQL查询

数据访问

整合数据集可通过以下文件中的Google Drive URL获取:

• ess-dive_harmonized_soil_urls.csv — 整合CSV文件的直接下载链接
• ess-dive_wfsfa_soil_dataset_urls.csv — 原始源包目录链接

依赖与使用

依赖项: Python 3.8+, pandas, numpy, requests, aiohttp, pyproj

示例用法:

• 加载单个整合数据集
• 加载所有整合数据集并与地点元数据合并
• 检查数据转换来源映射

许可协议

整合数据和代码采用**Creative Commons Attribution 4.0 International (CC-BY 4.0)**许可。原始ESS-DIVE数据集保留各自许可证（通常为CC-BY 4.0）。

搜集汇总

数据集介绍

构建方式

在流域水文与地表过程研究中，土壤水分观测数据对于理解水循环与生态响应至关重要，然而其来源碎片化、格式异构的问题长期困扰着数据驱动的建模应用。该数据集依托于美国能源部旗下Watershed Function Science Focus Area（WFSFA）框架，聚焦科罗拉多州East River流域，通过精密的自动化流程构建而成。首先借助ESS-DIVE数据仓库的应用程序接口进行元数据爬取与大批量检索，再对空间范围与学科归属进行双重过滤，锁定25个数据集包。其后采用自定义的Python编排脚本，对原始CSV文件实施变量名映射、物理单位转换、时间戳规范化至ISO-8601 UTC标准、深度均一化为地表以下米数，并通过空间聚类算法为观测站点赋予一致性UUID标识，最终将宽表重塑为长格式观测记录，辅以完整的JSON映射文件以记录每步数据转换的血缘与溯源信息。

特点

该数据集的最大特征在于实现了多种土壤水分观测指标的高层语义对齐与高质量整合。横跨14个经严格筛选与清洗的有效数据包，同时容纳体积含水量、质量含水量与基质势三类关键观测量，极大丰富了水文过程分析的变量维度。每条记录均携带标准化的时空标签与质量标志，尤其对深度近似值缺失精确定位的情形以质量控制标记予以明示。尤为突出的是，通过UUID驱动的空间位置统一化机制，将分散在不同数据包中的站点信息进行智能归并与关联，使得跨源联合回归或时间序列聚合得以在统一的地理对象上流畅展开。配合详尽的数据转换血统文档，用户在开展机器学习建模或模型标定时，可以透明追溯每一个观测值的来源与处理逻辑，大幅提升了结果的科学可信度与可复现性。

使用方法

研究人员可通过Python的数据科学生态便捷地接入该数据集。推荐使用pandas库以批量方式加载目录下所有以'harmonized.csv'结尾的表格文件，将'datetime_UTC'列解析为时间戳以实现按时间窗口的切片分析，再通过关键字段'site_id'将观测主表与附带的站点元数据表'location_data_harmonized_with_uuid.csv'进行左连接，从而为每个土壤水分观测点绑定WGS-84坐标及其他地理属性。若需深入了解变量变换细节，可使用json库读取数据集目录下的'sm_data_harmonization_mapping.json'，从中提取每个原始数据包的源变量名、映射目标字段、具体的转换函数与单位换算系数，便于定制化的二次清洗或模型特征工程。此外，项目还提供了兼容BERDL数据库的导入工作流脚本，支持将经过质量验证的整合数据直接推送至标准化关系数据库环境，配合内建的查询技能，从而实现从数据发现、预处理到数据库编排的一站式高效使用模式。

背景与挑战

背景概述

WFSFA Harmonized Soil Moisture Data数据集诞生于美国劳伦斯伯克利国家实验室主导的流域功能科学聚焦区（WFSFA）项目，聚焦科罗拉多州东河（East River）流域的土壤水分观测数据整合，创建时间可追溯至2025年。该数据集由环境数据科学团队开发，核心研究问题在于解决多源异构土壤水分观测数据在空间、时间及变量定义上的离散与不一致性，为水文与陆地生态系统模型提供统一、高质量且具备完整溯源的基准数据。其影响力体现在通过构建14个标准化数据包，覆盖体积含水量、重量含水量及水势等关键参数，并引入UUID空间聚类实现位置统一，为跨站点时序分析奠定了坚实基础，推动了环境数据科学向AI就绪格式的转化。

当前挑战

该数据集面临的挑战首先在于领域问题的复杂性：不同原始数据包采用迥异的记录格式、量纲及时间表示法（如深度单位不统一、时间戳非ISO-8601），需在保留原始信息完整性的前提下实现语义对齐。其次，构建过程中遭遇了数据缺失（如地理位置近似化、深度估计不精确）及质量控制的困难，需通过自动化脚本来识别并标记低置信度记录。空间位置的精准匹配亦是一大难题，依赖WGS-84坐标系下的空间聚类算法生成UUID，但部分站点元数据稀疏，增加了精准关联的难度。此外，从ESS-DIVE仓库抓取数据时需应对API接口限制和大型文件的传输稳定性，而最终的BERDL数据库导入则要求严格遵循预定义的表结构与本体映射，诸如此类环节均考验着流程的可复现性与鲁棒性。

常用场景

经典使用场景

在生态水文学与陆面过程建模领域，该数据集常被用于多站点、长时间尺度的土壤水分动态分析。研究人员通过加载14个经质量控制的土壤水分观测数据包，结合统一的体积含水量、基质势等标准化变量，对科罗拉多州东河流域山地生态系统的土壤水分时空异质性开展统计建模与趋势分析。其长格式结构化存储与UUID标识的地理空间元数据，使得跨数据源的聚合计算与时间序列分析变得高效便捷，为理解和量化流域尺度水循环驱动机制提供了规范化的数据基础。

衍生相关工作

围绕该数据集已衍生出一系列具有影响力的学术工作。其中，交互式数据融合技能（WFSFA Soil Moisture Harmonization Skill）实现了AI辅助的数据评估与映射文档自动生成，降低了跨源数据复用的技术门槛。基于BERTL架构的查询技能（Watershed SFA Soil Moisture BERDL Query Skill）则为学者提供了标准化数据库接口，使得对本体术语、数据类型定义与多维观测表的联合查询成为可能。这些衍生工具共同构成了一个集数据融合、存储与智能检索于一体的开放科学工作流，为生态水文领域的基准数据集建设树立了范式参考。

数据集最近研究

最新研究方向

当前，水文与陆地生态系统建模领域正经历从数据碎片化向标准化、可互操作范式的深刻转变。WFSFA Harmonized Soil Moisture Data数据集作为这一转型的前沿实践，聚焦于科罗拉多州东河流域，通过整合来自25个ESS-DIVE数据包的异构土壤湿度观测，构建了包含体积含水量、质量含水量和水势等关键变量的标准化长格式时间序列。该数据集不仅统一了变量命名、单位及时间格式（ISO-8601 UTC），还引入UUID进行空间位置协调，并附带了完整的溯源JSON映射文件，极大提升了数据的可复用性与模型基准测试的可靠性。其与BERDL数据库的深度融合，标志着水文数据正朝着AI-ready的端到端工作流演进，为理解山地流域水循环响应气候与人类活动变化提供了关键支撑。