earth2studio-data-fetch

Earth2Studio 数据获取技能

目的

指导用户通过 Earth2Studio 数据源 API 下载天气／气候数据。通过检查词汇表识别兼容的数据源，验证变量支持情况，并生成可运行的获取脚本，输出 xarray DataArray。

前提条件

• 已安装 Earth2Studio（uv pip install earth2studio 或等效方式）
• 可访问远程数据存储（GCS、S3、CDS API 等）
• 对于基于 CDS 的数据源：已配置有效的 CDS API 密钥（~/.cdsapirc）
• Python 3.10+

说明

你正在帮助用户使用 Earth2Studio 的数据源 API 下载指定的天气／气候数据。你的任务是确定哪些数据源能够提供所请求的变量，通过词汇表系统验证兼容性，并生成可运行的获取脚本。

核心原则：实时文档和词汇表是事实依据

数据源 API、可用变量和词汇表会随着版本更新而变化。在推荐数据源或编写获取脚本之前：

1. 获取相关的数据源文档页面，确认 API 签名和构造函数参数。
2. 检查词汇表，确认所请求的变量受该数据源支持。

实时文档参考（仅获取用户请求所需的内容）：

• 分析数据源： https://nvidia.github.io/earth2studio/modules/datasources_analysis.html
• 预报数据源： https://nvidia.github.io/earth2studio/modules/datasources_forecast.html
• DataFrame 数据源： https://nvidia.github.io/earth2studio/modules/datasources_dataframe.html
• 词汇表基类： https://github.com/NVIDIA/earth2studio/blob/main/earth2studio/lexicon/base.py
• 各数据源的词汇表： https://github.com/NVIDIA/earth2studio/tree/main/earth2studio/lexicon

交互流程

第 1 步：了解用户的请求

从用户的描述中提取以下信息（如有需要，可追问，最多 3 个问题）：

• 变量——用户需要什么？使用 Earth2Studio 变量名称（例如 t2m、u500、z850、tp、msl）。如果用户使用自然语言（“500 hPa 位势高度”），请检查实时 base.py 中的 E2STUDIO_VOCAB，将其映射为 E2Studio 名称。
• 时间——需要什么日期／时间范围？单个时间戳、一个范围，还是多个离散时间？
• 数据类型——分析／再分析（历史状态）还是预报（基于预报时效）？
• 预报时效（仅限预报）——需要提前多长时间？使用哪个起报时间？
• 区域——全球还是区域（例如 HRRR 的北美区域）？
• 输出格式——xarray DataArray（默认），还是保存到文件（NetCDF/Zarr）？

第 2 步：确定候选数据源

根据请求类型缩小候选范围：

分析／再分析（特定时间的历史状态）：

• 使用分析数据源页面查找可用选项
• 常见选择：GFS（业务运行，近期数据）、HRRR（北美区域，逐小时）、 IFS/IFS_ENS（ECMWF）、ARCO/CDS/WB2ERA5/NCAR_ERA5（ERA5 再分析）、 GOES/MRMS/JPSS（观测数据）

预报（基于起报时间和预报时效的预测）：

• 使用预报数据源页面查找可用选项
• 常见选择：GFS_FX、GEFS_FX、HRRR_FX、IFS_FX、IFS_ENS_FX、 AIFS_FX、CFS_FX

需要重点说明的差异：

• 时间覆盖范围——业务运行数据源（GFS、HRRR）的历史数据有限；再分析数据（通过 ARCO/CDS/WB2 获取的 ERA5）可追溯数十年
• 空间分辨率——HRRR 仅覆盖北美，分辨率为 3km；GFS 覆盖全球，分辨率为 0.25°； WB2ERA5_32x64 覆盖全球，分辨率为 5.625°
• 更新频率——有些数据源提供实时数据，有些则延迟数天

步骤 3. 通过词汇表验证变量支持情况

这一步至关重要。每个数据源都有一个词汇表文件，用于定义它能提供哪些 E2Studio 变量。

验证方法：

1. 从 https://github.com/NVIDIA/earth2studio/blob/main/earth2studio/lexicon/<source>.py 获取数据源的词汇表文件（例如 gfs.py、hrrr.py、cds.py、arco.py、wb2.py）
2. 检查用户请求的变量是否作为键出现在数据源的 VOCAB 字典中
3. 如果变量不在某个数据源的词汇表中，该数据源就无法提供它——请尝试其他数据源

词汇表中的 VOCAB 将 Earth2Studio 变量名映射到特定数据源标识符。如果某个变量键存在于 VOCAB 中，则该数据源支持此变量。

清楚地呈现结果："GFS 支持 t2m、u500、z850。HRRR 也支持这些变量，但覆盖范围仅限北美。ARCO（ERA5）支持全部三个变量，且数据可追溯至 1959 年。"

步骤 4. 与用户确认数据源选择

列出可行选项及其权衡：

数据源	变量	覆盖范围	分辨率	时间范围
...	...	...	...	...

让用户选择。如果有一个明显更合适的选项，请推荐该选项并征求确认。

步骤 5. 生成获取脚本

编写一个使用所选数据源获取所需数据的 Python 脚本。脚本结构取决于所选数据源是分析数据源还是预报数据源。

分析数据源模式：

import datetime
from earth2studio.data import <SourceClass>

# Initialize data source
ds = <SourceClass>()

# Fetch data
# Analysis sources use: ds(time, variable) -> xr.DataArray
time = [datetime.datetime(YYYY, M, D, H)]  # or array of times
variable = ["var1", "var2"]  # E2Studio variable names

data = ds(time, variable)

预报数据源模式：

import datetime
from earth2studio.data import <SourceClass>

# Initialize data source
ds = <SourceClass>()

# Forecast sources use: ds(time, lead_time, variable) -> xr.DataArray
time = [datetime.datetime(YYYY, M, D, H)]  # initialization time
lead_time = [datetime.timedelta(hours=H)]   # or array of lead times
variable = ["var1", "var2"]

data = ds(time, lead_time, variable)

编写脚本前，务必获取特定数据源的 API 文档页面，以确认确切的构造函数参数和调用签名——它们可能有所不同（有些需要身份验证令牌、缓存路径或特定参数）。

在脚本中包含：

• 适当的导入语句
• 清晰的注释，说明每个步骤
• 如何检查结果（print(data)、data.shape、data.coords）
• 可选：如果用户有要求，则将数据保存到文件

步骤 6. 提供后续步骤

提供脚本后，说明：

• 如何更改变量或时间，而无需重写整个脚本
• 如果用户可能想将这些数据输入模型，请引导他们使用 discover 技能
• 缓存行为（首次获取后，数据会通过 EARTH2STUDIO_CACHE 缓存在本地）

职责范围与不负责事项

负责： 根据用户请求的变量和时间确定数据源，通过词汇表验证变量支持情况，生成数据获取脚本，说明分析数据源与预报数据源之间的区别。

不负责： 安装（earth2studio-install）、模型选择（earth2studio-discover）、推理流水线、自定义数据源创建（引导用户参考扩展示例），以及文档未说明的数据源身份验证设置。

示例

典型调用：

"我需要 2020 年 1 月 1 日 00Z 的 ERA5 500 hPa 位势高度和 2m 气温。"

此技能将：

1. 将自然语言映射为 z500、t2m
2. 检查 ARCO/CDS/WB2ERA5 词汇表，确认是否支持
3. 推荐 ARCO（免费，无需 API 密钥）或 CDS（官方数据源，需要密钥）
4. 使用所选数据源生成获取脚本

限制

• 需要网络连接——所有数据源都从远程存储获取数据（GCS、S3、CDS API）
• 不支持加载本地文件——对于本地 NetCDF/Zarr，请直接使用 DataArrayFile/DataSetFile
• 每个脚本只能使用一种数据源类型——无法在一次调用中混用分析数据源和预报数据源
• 变量可用性因数据源而异——并非所有数据源都提供所有变量；务必通过词汇表进行验证
• 速率限制——CDS API 采用基于队列的限流；GCS/S3 数据源通常更快

故障排查

错误	原因	解决方案
KeyError: '<var>'	不在词典中	检查词典；尝试其他数据源
FileNotFoundError / 404	时间数据不可用	验证时间覆盖范围
CDS API timeout	队列拥堵	重试，或使用 ARCO 获取 ERA5
ModuleNotFoundError	未安装	uv pip install earth2studio
DataArray 为空	时间/变量不匹配	检查日期时间和变量名称