earth2studio-data-fetch

Files (8)

• BENCHMARK.md
• SKILL.md
• evals.json · evals/
• eval_1_target.py · evals/targets/
• eval_4_target.py · evals/targets/
• eval_7_target.py · evals/targets/
• skill-card.md
• skill.oms.sig

SKILL.md (first lines)

# 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

From NVIDIA/skills, Apache-2.0.

More from NVIDIA/skills