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°です
• 更新頻度 — リアルタイムのものもあれば、数日の遅延があるものもあります

Step 3. lexicon で変数のサポートを確認する

これは重要です。各データソースには、提供可能な E2Studio 変数を定義した lexicon ファイルがあります。

確認方法：

1. 次の場所からデータソースの lexicon ファイルを取得します。 https://github.com/NVIDIA/earth2studio/blob/main/earth2studio/lexicon/<source>.py （例：gfs.py、hrrr.py、cds.py、arco.py、wb2.py）
2. ユーザーがリクエストした変数が、データソースの VOCAB dict のキーとして含まれていることを確認します。
3. 変数がデータソースの lexicon に含まれていない場合、そのデータソースでは提供できません。別のデータソースを試してください。

lexicon の VOCAB は、Earth2Studio の変数名からデータソース固有の 識別子への対応を定義します。変数キーが VOCAB に存在すれば、そのデータソースはその変数をサポートしています。

結果は明確に提示してください。例：「GFS は t2m、u500、z850 をサポートしています。HRRR もこれらをサポートしていますが、北米に限定されます。ARCO（ERA5）は3つすべてをサポートし、1959年まで遡るデータがあります。」

Step 4. ユーザーにデータソースの選択を確認する

メリットとデメリットを添えて、利用可能な選択肢を提示します。

データソース	変数	範囲	解像度	期間
...	...	...	...	...

ユーザーに選んでもらいます。明らかに最適な選択肢が1つある場合は、それを推奨して確認を求めます。

Step 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）
• 任意：ユーザーがリクエストした場合はファイルへの保存

Step 6. 次のステップを提案する

スクリプトを提示した後、次の内容に触れます。

• 全体を書き直さずに変数や時刻を変更する方法
• モデルに入力する予定がある場合は、discover スキルを案内します。
• キャッシュの動作（EARTH2STUDIO_CACHE を通じて、初回取得後にデータがローカルにキャッシュされます）

担当範囲と対象外

担当範囲： ユーザーが指定した変数や時刻に適したデータソースの特定、lexicon による変数サポートの確認、データ取得スクリプトの生成、解析データソースと予報データソースの違いの説明。

対象外： インストール（earth2studio-install）、モデルの選択（earth2studio-discover）、推論パイプライン、カスタムデータソースの作成（拡張例を案内）、ドキュメントに記載された範囲を超えるデータソースの認証設定。

例

一般的な呼び出し例：

「2020年1月1日 00Z の ERA5 から、500 hPa のジオポテンシャル高度と2 m 気温を取得したいです。」

このスキルでは次の処理を行います。

1. 平易な言葉を z500、t2m に対応付けます。
2. ARCO／CDS／WB2ERA5 の lexicon を確認し、対応状況を調べます。
3. ARCO（無料、API キー不要）または CDS（公式、キーが必要）を推奨します。
4. 選択したデータソースを使って、データ取得スクリプトを生成します。

制限事項

• ネットワークが必要です — すべてのデータソースはリモートストア（GCS、S3、CDS API）からデータを取得します。
• ローカルファイルの読み込みには対応していません — ローカルの NetCDF／Zarr には、DataArrayFile／DataSetFile を直接使用してください。
• 1つのスクリプトにつきデータソースの種類は1つです — 1回の呼び出しで解析データソースと予報データソースを混在させることはできません。
• 変数の利用可否はデータソースによって異なります — すべてのデータソースがすべての変数を提供するわけではありません。必ず lexicon で確認してください。
• レート制限があります — CDS API はキューベースのスロットリングを使用します。GCS／S3 のデータソースは一般により高速です。

トラブルシューティング

エラー	原因	解決方法
KeyError: '<var>'	語彙に含まれていません	語彙を確認し、別のデータソースを試してください
FileNotFoundError / 404	指定した時刻のデータがありません	時間範囲のカバレッジを確認してください
CDS API timeout	キューが混雑しています	再試行するか、ERA5 には ARCO を使用してください
ModuleNotFoundError	インストールされていません	uv pip install earth2studio
空の DataArray	時刻と変数が一致していません	datetime と変数名を確認してください