/earth2studio-data-fetch

name: earth2studio-data-fetch
version: 0.16.0
license: Apache-2.0
metadata:
  author: NVIDIA Earth-2 Team
  tags:
    - earth2studio
    - earth2
    - python
    - data-fetch
    - weather-data
    - xarray
description: >
  Fetch weather/climate data via Earth2Studio data sources for specific variables
  and times. Do NOT use for inference pipelines, model discovery, or installation.

Earth2Studio Data Fetch Skill

Purpose

Guide a user through downloading weather/climate data via Earth2Studio data source APIs. Identifies compatible sources by checking the lexicon, verifies variable support, and produces a working fetch script outputting an xarray DataArray.

Prerequisites

• Earth2Studio installed (`uv pip install earth2studio` or equivalent)
• Network access to remote data stores (GCS, S3, CDS API, etc.)
• For CDS-based sources: valid CDS API key configured (`~/.cdsapirc`)
• Python 3.10+

Instructions

You are helping a user download specific weather/climate data using Earth2Studio's data source APIs. Your job is to identify which data source(s) can provide the requested variables, verify compatibility via the lexicon system, and produce a working fetch script.

Core principle: live docs and lexicon are the source of truth

Data source APIs, available variables, and the lexicon evolve between releases. Before recommending a data source or writing a fetch script:

1. **Fetch the relevant data source doc page** to confirm the API signature and constructor arguments. 2. **Check the lexicon** to verify the requested variable is supported by that data source.

Live doc references (fetch only what the user's request requires):

• **Analysis data sources:**

<https://nvidia.github.io/earth2studio/modules/datasources_analysis.html>

• **Forecast data sources:**

<https://nvidia.github.io/earth2studio/modules/datasources_forecast.html>

• **DataFrame data sources:**

<https://nvidia.github.io/earth2studio/modules/datasources_dataframe.html>

• **Lexicon base:**

<https://github.com/NVIDIA/earth2studio/blob/main/earth2studio/lexicon/base.py>

• **Lexicon per-source:**

<https://github.com/NVIDIA/earth2studio/tree/main/earth2studio/lexicon>

Interaction protocol

Step 1. Understand the user's request

Extract from what the user has said (ask follow-ups if needed, cap at 3 questions):

• **Variables** — what do they want? Use Earth2Studio variable names

(e.g. `t2m`, `u500`, `z850`, `tp`, `msl`). If the user uses plain language ("500 hPa geopotential height"), map it to the E2Studio name by checking the live `base.py` E2STUDIO_VOCAB.

• **Time** — what date/time range? A single timestamp, a range, or multiple

discrete times?

• **Data type** — analysis/reanalysis (historical state) or forecast (lead-time based)?
• **Lead time** (forecast only) — how far ahead? Which initialization time?
• **Region** — global or regional (e.g. North America for HRRR)?
• **Output format** — xarray DataArray (default), save to file (NetCDF/Zarr)?

Step 2. Identify candidate data sources

Based on the request type, narrow candidates:

**Analysis/reanalysis** (historical state at a specific time):

• Use analysis data source page to identify options
• Common choices: GFS (operational, recent), HRRR (NA, hourly),

IFS/IFS_ENS (ECMWF), ARCO/CDS/WB2ERA5/NCAR_ERA5 (ERA5 reanalysis), GOES/MRMS/JPSS (observational)

**Forecast** (predictions from an initialization time with lead times):

• Use forecast data source page to identify options
• Common choices: GFS_FX, GEFS_FX, HRRR_FX, IFS_FX, IFS_ENS_FX,

AIFS_FX, CFS_FX

Key differentiators to surface:

• **Temporal coverage** — operational sources (GFS, HRRR) have limited

history; reanalysis (ERA5 via ARCO/CDS/WB2) goes back decades

• **Spatial resolution** — HRRR is 3km NA-only; GFS is 0.25° global;

WB2ERA5_32x64 is 5.625° global

• **Update frequency** — some are real-time, some have multi-day lag

Step 3. Verify variable support via lexicon

This is critical. Each data source has a lexicon file that defines which E2Studio variables it can provide.

To verify:

1. Fetch the source's lexicon file from `https://github.com/NVIDIA/earth2studio/blob/main/earth2studio/lexicon/<source>.py` (e.g. `gfs.py`, `hrrr.py`, `cds.py`, `arco.py`, `wb2.py`) 2. Check that the user's requested variable(s) appear as keys in the source's `VOCAB` dict 3. If a variable is NOT in a source's lexicon, that source cannot provide it — try another

The lexicon VOCAB maps Earth2Studio variable names → source-specific identifiers. If a variable key exists in the VOCAB, the source supports it.

Present the results clearly: *"GFS supports `t2m`, `u500`, `z850`. HRRR also supports these but is limited to North America. ARCO (ERA5) supports all three and has data back to 1959."*

Step 4. Confirm data source selection with user

Present the viable options with tradeoffs:

| Source | Variables | Coverage | Resolution | Time Range | |--------|-----------|----------|------------|------------| | ... | ... | ... | ... | ... |

Let the user pick. If there's one obvious choice, recommend it and ask for confirmation.

Step 5. Generate fetch script

Write a Python script that uses the selected data source to fetch the requested data. The script structure depends on whether it's an analysis or forecast source.

**Analysis source pattern:**

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)

**Forecast source pattern:**

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)]  # initi