ecmwf/cfgrib

A Python interface to map GRIB files to the NetCDF Common Data Model following the CF Convention using ecCodes

Structural Verdict

How Data Flows Through the System

GRIB files are parsed into messages, indexed by coordinates, transformed to CF-compliant fields, and exposed as xarray datasets

1. File Reading — FileStream opens GRIB file and provides sequential access to messages using ecCodes
2. Message Parsing — Message objects wrap ecCodes handles with lazy data access and metadata extraction
3. Indexing — FieldsetIndex groups messages by coordinate keys to identify coherent datasets
4. CF Transformation — CfField computes CF-compliant coordinates and metadata from GRIB keys
5. Dataset Building — Dataset assembles fields into structured arrays with proper dimensions and attributes
6. Coordinate Translation — cf2cdm translates coordinate names and units according to specified data models (config: channels, dependencies)
7. xarray Integration — CfGribDataStore exposes the dataset through xarray's backend interface

System Behavior

How the system actually operates at runtime — where data accumulates, what loops, what waits, and what controls what.

Data Pools

Delays & Async Processing

• Lazy Data Loading (async-processing) — GRIB message data arrays are not loaded until explicitly accessed
• Index Cache TTL (cache-ttl) — Index files are cached to disk to avoid re-parsing large GRIB files

Control Points

• backend_kwargs (runtime-toggle) — Controls: GRIB reading behavior including indexing and filtering options
• filter_by_keys (runtime-toggle) — Controls: Which GRIB messages to include based on key-value filters
• data_model (feature-flag) — Controls: Whether to use CDS, ECMWF, or default coordinate naming conventions

Technology Stack

Key Components

• open_dataset (function) — Main entry point for opening GRIB files as xarray datasets cfgrib/xarray_store.py
• Dataset (class) — Core class that builds structured datasets from GRIB fieldsets with proper metadata cfgrib/dataset.py
• CfGribDataStore (class) — xarray backend store implementation for reading GRIB files cfgrib/xarray_plugin.py
• FieldsetIndex (class) — Indexes GRIB messages by coordinate keys for efficient access cfgrib/messages.py
• Message (class) — Wrapper around ecCodes GRIB message with lazy data loading cfgrib/messages.py
• CfField (class) — Converts GRIB messages to CF-compliant field objects with computed coordinates cfgrib/cfmessage.py
• translate_coords (function) — Transforms coordinate names and metadata according to specified data models cf2cdm/cfcoords.py
• CDS (config) — Coordinate mapping configuration for Copernicus Climate Data Store format cf2cdm/datamodels.py
• ECMWF (config) — Coordinate mapping configuration for ECMWF data format cf2cdm/datamodels.py
• FileStream (class) — Provides sequential access to GRIB messages in a file with caching cfgrib/messages.py

Sub-Modules

Configuration

appveyor.yml (yaml)

• environment.matrix (array, unknown) — default: [object Object]
• install (array, unknown) — default: powershell ./ci/install_python.ps1
• build (boolean, unknown) — default: false
• test_script (array, unknown) — default: echo Pass

environment-minimal.in.yml (yaml)

• channels (array, unknown) — default: defaults,conda-forge
• dependencies (array, unknown) — default: attrs>=19.2,click,nomkl,numpy,pytest-cov,python-eccodes,tomli

environment-minver.in.yml (yaml)

• channels (array, unknown) — default: defaults,conda-forge
• dependencies (array, unknown) — default: attrs=19.2.0,click=7.0.0,eccodes=2.16.0,numpy=1.15.0,pandas=0.25.0,pytest-cov,python-eccodes=1.4.0,tomli,xarray=0.15.0

environment.in.yml (yaml)

• channels (array, unknown) — default: defaults,conda-forge
• dependencies (array, unknown) — default: attrs>=19.2,click,eccodes>=2.20.0,mypy=0.812,nomkl,numpy,pytest-cov,python-eccodes,scipy,tomli,xarray>=0.20.2

Science Pipeline

1. Parse GRIB Messages — eccodes.codes_new_from_file then extract metadata keys cfgrib/messages.py
2. Group by Coordinates — Build index mapping coordinate tuples to message lists [(n_messages,) → (n_coordinate_groups,)] cfgrib/messages.py
3. Compute CF Coordinates — Transform GRIB coordinate metadata to CF-compliant format cfgrib/cfmessage.py
4. Build Dataset Arrays — Stack message data into multi-dimensional arrays with proper coordinate alignment [(n_messages, lat, lon) → (time, level, lat, lon)] cfgrib/dataset.py
5. Apply Coordinate Translation — Rename coordinates and convert units according to data model specifications cf2cdm/cfcoords.py

Assumptions & Constraints

• [warning] Assumes GRIB time encoding follows standard conventions but no validation ensures time units are correctly interpreted (format)
• [warning] Assumes coordinate dimensions can be inferred from GRIB message groupings but irregular grids may cause issues (shape)
• [info] Returns numpy arrays with dtypes determined by ecCodes but no explicit type validation (dtype)
• [info] Unit conversion assumes standard atmospheric pressure ranges without bounds checking (value-range)

Related Weather Climate Repositories

Frequently Asked Questions

Analyzed on March 31, 2026 by CodeSea. Written by Karolina Sarna.