Référence API

Ce module expose les symboles publics suivants, importables directement depuis meteopendata2netcdf :

from meteopendata2netcdf import (
    IFSSurfaceDownloader,
    DownloadResult,
    DownloadError,
    DatasetBuildError,
)

Téléchargeur

class meteopendata2netcdf.IFSSurfaceDownloader(output_dir='./ifs_output', source='ecmwf', params=None, steps=None)

Bases : object

Download IFS surface forecasts (temperature, wind, humidity) via ecmwf-opendata.

Uses the HTTP Byte-Range mechanism provided by ecmwf-opendata: only the bytes corresponding to the requested parameters and steps are transferred per file, not the full GRIB2.

Paramètres:

• output_dir (str | Path) – Directory where GRIB2 files are saved. Created if absent.

• source (Literal['ecmwf', 'aws', 'azure', 'google']) – Data source: "ecmwf" (default), "aws", "azure", or "google".

• params (list[str] | None) – ECMWF parameter short-names to download. Defaults to SURFACE_PARAMS.

• steps (list[int] | None) – Forecast lead times in hours. Defaults to DEFAULT_STEPS (0-72 h, step 6 h).

Example:

dl = IFSSurfaceDownloader(output_dir="./ifs_output", source="aws")
result = dl.download(time=0)
result.to_netcdf("ifs_surface.nc")

get_latest_run_time(time=None)

Return the UTC datetime of the most recent available IFS run.

Paramètres:

time (int | None) – Target run hour (must be 0 or 12). When None the most recent run is detected automatically.

Type renvoyé:

datetime

Renvoie:

UTC datetime of the available run.

Lève:

• ValueError – If time is not 0 or 12.

• DownloadError – If the server cannot be reached or returns no result.

download(time=None, load_dataset=True)

Download IFS surface fields and return a DownloadResult.

Paramètres:

• time (int | None) – Target run hour (0 or 12). None → latest available.

• load_dataset (bool) – When True (default), load the GRIB2 into an xr.Dataset and attach it to the result.

Type renvoyé:

DownloadResult

Renvoie:

DownloadResult with grib_path, run_datetime, params, steps, and optionally dataset.

Lève:

• ValueError – If time is not 0 or 12.

• DownloadError – If the download fails.

class meteopendata2netcdf.DownloadResult(grib_path, run_datetime, params=<factory>, steps=<factory>, dataset=None)

Bases : object

Result of a successful IFS surface download.

Paramètres:

• grib_path (Path)

• run_datetime (datetime)

• params (list[str])

• steps (list[int])

• dataset (Dataset | None)

grib_path

Path to the consolidated GRIB2 file on disk.

run_datetime

UTC datetime of the downloaded IFS run.

params

ECMWF parameter short-names that were requested.

steps

Forecast lead times (hours) that were requested.

dataset

In-memory xr.Dataset (None when load_dataset is False).

grib_path: Path

run_datetime: datetime

params: list[str]

steps: list[int]

dataset: Dataset | None = None

to_netcdf(path, **kwargs)

Write the in-memory dataset to a NetCDF file.

Paramètres:

• path (str | Path) – Destination file path (*.nc).

• **kwargs (Any) – Extra keyword arguments forwarded to xr.Dataset.to_netcdf().

Type renvoyé:

Path

Renvoie:

Resolved Path of the written file.

Lève:

RuntimeError – If dataset is None (download was called with load_dataset=False).

Exceptions

exception meteopendata2netcdf.DownloadError

Bases : RuntimeError

Raised when the ECMWF open-data download fails.

exception meteopendata2netcdf.DatasetBuildError

Bases : RuntimeError

Raised when cfgrib cannot build a coherent xr.Dataset from the GRIB2 file.

Utilitaires internes

Les modules suivants sont internes (préfixe _) et ne font pas partie de l’API publique stable. Ils sont documentés ici pour les contributeurs.

meteopendata2netcdf._grib.load_surface_dataset(grib_path)

Load a multi-parameter IFS surface GRIB2 file into a single xr.Dataset.

IFS surface fields span two distinct heights:

• heightAboveGround = 2 m → t2m, d2m

• heightAboveGround = 10 m → u10, v10

cfgrib groups GRIB messages by their scalar coordinate values, so fields at different heights cannot be merged automatically by xr.open_dataset(); it raises a DatasetBuildError and silently drops the conflicting variables.

This function calls cfgrib.open_datasets() instead (plural), which returns one coherent xr.Dataset per height group, then:

1. Sorts each group by valid_time.

2. Stores the original height as a height_m attribute on each variable.

3. Drops the scalar heightAboveGround coordinate (source of the conflict).

4. Merges all groups with xr.merge(compat="override").

Paramètres:

grib_path (Path) – Path to the GRIB2 file produced by retrieve_grib().

Type renvoyé:

Dataset

Renvoie:

xr.Dataset containing all four surface variables (t2m, d2m, u10, v10) along the valid_time dimension, loaded into memory.

Lève:

DatasetBuildError – If cfgrib returns no datasets or the merged result is empty.

Package-wide constants for IFS surface downloads.

meteopendata2netcdf._constants.SURFACE_PARAMS: list[str] = ['2t', '2d', '10u', '10v']

Surface parameters downloaded from IFS open data. - 2t : 2-metre temperature (K) - 2d : 2-metre dewpoint temperature (K) — surface humidity proxy - 10u : 10-metre U-wind component (m s⁻¹) - 10v : 10-metre V-wind component (m s⁻¹)

meteopendata2netcdf._constants.DEFAULT_STEPS: list[int] = [0, 6, 12, 18, 24, 30, 36, 42, 48, 54, 60, 66, 72]

0-72 h every 6 h.

Type:

Default forecast steps (hours)

meteopendata2netcdf._constants.VALID_RUN_HOURS: frozenset[int] = frozenset({0, 12})

IFS HRES operational run hours available via stream=oper.

meteopendata2netcdf._constants.MODEL: str = 'ifs'

ecmwf-opendata model / stream / type strings.