Skill de téléchargement de données Earth2Studio

Objectif

Guider un utilisateur dans le téléchargement de données météorologiques/climatiques via les APIs de sources de données Earth2Studio. Identifier les sources compatibles en vérifiant le lexique, vérifier la prise en charge des variables et produire un script de téléchargement fonctionnel qui génère un xarray DataArray.

Prérequis

• Earth2Studio installé (uv pip install earth2studio ou équivalent)
• Accès réseau aux magasins de données distants (GCS, S3, API CDS, etc.)
• Pour les sources basées sur CDS : clé API CDS valide configurée (~/.cdsapirc)
• Python 3.10+

Instructions

Vous aidez un utilisateur à télécharger des données météorologiques/climatiques spécifiques à l'aide des APIs de sources de données Earth2Studio. Votre rôle est d'identifier quelle(s) source(s) de données peut (peuvent) fournir les variables demandées, vérifier la compatibilité via le système de lexique et produire un script de téléchargement fonctionnel.

Principe fondamental : la documentation en direct et le lexique font autorité

Les APIs de sources de données, les variables disponibles et le lexique évoluent entre les versions. Avant de recommander une source de données ou d'écrire un script de téléchargement :

1. Récupérez la page de documentation de la source de données pertinente pour confirmer la signature de l'API et les arguments du constructeur.
2. Vérifiez le lexique pour confirmer que la variable demandée est supportée par cette source de données.

Références de documentation en direct (récupérez uniquement ce que la demande de l'utilisateur nécessite) :

• Sources de données d'analyse : https://nvidia.github.io/earth2studio/modules/datasources_analysis.html
• Sources de données de prévision : https://nvidia.github.io/earth2studio/modules/datasources_forecast.html
• Sources de données DataFrame : https://nvidia.github.io/earth2studio/modules/datasources_dataframe.html
• Base du lexique : https://github.com/NVIDIA/earth2studio/blob/main/earth2studio/lexicon/base.py
• Lexique par source : https://github.com/NVIDIA/earth2studio/tree/main/earth2studio/lexicon

Protocole d'interaction

Étape 1. Comprendre la demande de l'utilisateur

Extrayez de ce que l'utilisateur a dit (posez des questions de suivi si nécessaire, limité à 3 questions) :

• Variables — que veut-il ? Utilisez les noms de variables Earth2Studio (par ex. t2m, u500, z850, tp, msl). Si l'utilisateur utilise du langage courant (« hauteur du géopotentiel à 500 hPa »), mappez-le au nom E2Studio en vérifiant le base.py E2STUDIO_VOCAB en direct.
• Temps — quelle plage de date/heure ? Un seul horodatage, une plage ou plusieurs fois discrètes ?
• Type de données — analyse/réanalyse (état historique) ou prévision (basée sur le délai) ?
• Délai (prévision uniquement) — combien de temps à l'avance ? Quel temps d'initialisation ?
• Région — global ou régional (par ex. Amérique du Nord pour HRRR) ?
• Format de sortie — xarray DataArray (par défaut), enregistrement dans un fichier (NetCDF/Zarr) ?

Étape 2. Identifier les sources de données candidates

En fonction du type de demande, réduisez les candidates :

Analyse/réanalyse (état historique à un moment spécifique) :

• Utilisez la page de source de données d'analyse pour identifier les options
• Choix courants : GFS (opérationnel, récent), HRRR (NA, horaire), IFS/IFS_ENS (ECMWF), ARCO/CDS/WB2ERA5/NCAR_ERA5 (réanalyse ERA5), GOES/MRMS/JPSS (observations)

Prévision (prédictions d'un temps d'initialisation avec délais) :

• Utilisez la page de source de données de prévision pour identifier les options
• Choix courants : GFS_FX, GEFS_FX, HRRR_FX, IFS_FX, IFS_ENS_FX, AIFS_FX, CFS_FX

Différenciateurs clés à mettre en avant :

• Couverture temporelle — les sources opérationnelles (GFS, HRRR) ont un historique limité ; la réanalyse (ERA5 via ARCO/CDS/WB2) remonte à plusieurs décennies
• Résolution spatiale — HRRR est 3 km NA uniquement ; GFS est 0,25° global ; WB2ERA5_32x64 est 5,625° global
• Fréquence de mise à jour — certaines sont en temps réel, d'autres ont un délai de plusieurs jours

Étape 3. Vérifier la prise en charge des variables via le lexique

C'est crucial. Chaque source de données a un fichier lexique qui définit quelles variables E2Studio elle peut fournir.

Pour vérifier :

1. Récupérez le fichier lexique de la source auprès de https://github.com/NVIDIA/earth2studio/blob/main/earth2studio/lexicon/<source>.py (par ex. gfs.py, hrrr.py, cds.py, arco.py, wb2.py)
2. Vérifiez que la/les variable(s) demandée(s) par l'utilisateur apparaissent comme clés dans le dict VOCAB de la source
3. Si une variable N'est PAS dans le lexique d'une source, cette source ne peut pas la fournir — essayez une autre

Le VOCAB du lexique mappe les noms de variables Earth2Studio → identifiants spécifiques à la source. Si une clé de variable existe dans le VOCAB, la source la supporte.

Présentez les résultats clairement : « GFS supporte t2m, u500, z850. HRRR supporte aussi ceux-ci mais est limité à l'Amérique du Nord. ARCO (ERA5) supporte les trois et a des données remontant à 1959. »

Étape 4. Confirmer la sélection de la source de données avec l'utilisateur

Présentez les options viables avec compromis :

Laissez l'utilisateur choisir. S'il y a un choix évident, recommandez-le et demandez confirmation.

Étape 5. Générer le script de téléchargement

Écrivez un script Python qui utilise la source de données sélectionnée pour télécharger les données demandées. La structure du script dépend du fait qu'il s'agit d'une source d'analyse ou de prévision.

Motif de source d'analyse :

import datetime
from earth2studio.data import <SourceClass>

# Initialiser la source de données
ds = <SourceClass>()

# Télécharger les données
# Les sources d'analyse utilisent : ds(time, variable) -> xr.DataArray
time = [datetime.datetime(YYYY, M, D, H)]  # ou tableau de temps
variable = ["var1", "var2"]  # noms de variables Earth2Studio

data = ds(time, variable)

Motif de source de prévision :

import datetime
from earth2studio.data import <SourceClass>

# Initialiser la source de données
ds = <SourceClass>()

# Les sources de prévision utilisent : ds(time, lead_time, variable) -> xr.DataArray
time = [datetime.datetime(YYYY, M, D, H)]  # temps d'initialisation
lead_time = [datetime.timedelta(hours=H)]   # ou tableau de délais
variable = ["var1", "var2"]

data = ds(time, lead_time, variable)

Récupérez toujours la page de documentation spécifique de la source de données pour confirmer les arguments exacts du constructeur et la signature de l'appel avant d'écrire le script — ils peuvent varier (certains ont besoin de tokens d'authentification, de chemins de cache, de paramètres spécifiques).

Incluez dans le script :

• Les imports appropriés
• Des commentaires clairs expliquant chaque étape
• Comment inspecter le résultat (print(data), data.shape, data.coords)
• Optionnel : enregistrement dans un fichier si l'utilisateur l'a demandé

Étape 6. Proposer les prochaines étapes

Après avoir livré le script, mentionnez :

• Comment changer les variables/temps sans réécrire le tout
• S'ils pourraient vouloir alimenter cela dans un modèle, pointez-les vers la skill discover
• Comportement du cache (les données sont cachées localement après le premier téléchargement via EARTH2STUDIO_CACHE)

Responsabilité et hors du périmètre

Responsable de : identifier les sources de données pour une demande de variable/temps d'un utilisateur, vérifier la prise en charge des variables via le lexique, générer des scripts de téléchargement de données, expliquer les différences entre les sources d'analyse et de prévision.

Non responsable de : installation (earth2studio-install), sélection de modèles (earth2studio-discover), pipelines d'inférence, création de sources de données personnalisées (pointer vers des exemples d'extension), configuration de l'authentification des sources de données au-delà de ce que la documentation décrit.

Exemples

Invocation typique :

« Je besoin de la hauteur du géopotentiel à 500 hPa et de la température à 2 m d'ERA5 pour le 1er janvier 2020 à 00Z. »

La skill procéderait ainsi :

1. Mapper le langage courant → z500, t2m
2. Vérifier le support dans les lexiques ARCO/CDS/WB2ERA5
3. Recommander ARCO (gratuit, pas de clé API) ou CDS (officiel, nécessite une clé)
4. Générer un script de téléchargement utilisant la source sélectionnée

Limitations

• Réseau requis — toutes les sources de données téléchargent à partir de magasins distants (GCS, S3, API CDS)
• Pas de chargement de fichier local — pour les fichiers NetCDF/Zarr locaux, utilisez DataArrayFile/DataSetFile directement
• Un type de source par script — ne peuvent pas mélanger les sources d'analyse et de prévision dans un seul appel
• La disponibilité des variables varie — toutes les sources ne fournissent pas toutes les variables ; vérifiez toujours via le lexique
• Limites de taux — l'API CDS a une limitation basée sur la file d'attente ; les sources GCS/S3 sont généralement plus rapides

Dépannage