Grid Data Formats

1.1.0 · active · verified Thu Apr 16

griddataformats is a Python library for reading and writing data on regular grids. It provides a standardized way to handle gridded data, often used in scientific computing, meteorology, and other fields. The current version is 1.1.0, and it offers robust support for common formats like NetCDF and GRIB2 through optional dependencies.

Common errors

```
ModuleNotFoundError: No module named 'netCDF4'
```
cause Attempted to use `griddataformats.file.NetCDFFile` without installing the `netcdf4` package, which is an optional dependency.

fix Install `griddataformats` with the NetCDF optional dependency: `pip install griddataformats[netcdf]`
```
ModuleNotFoundError: No module named 'eccodes'
```
cause Attempted to use `griddataformats.file.GRIB2File` without installing the `eccodes` package, which is an optional dependency.

fix Install `griddataformats` with the GRIB2 optional dependency: `pip install griddataformats[grib2]`
```
ValueError: Field data shape mismatch with dimensions
```
cause The shape of the `numpy.ndarray` provided to `Field.data` does not match the total number of dimensions or the sizes specified in the `dimensions` list.

fix Ensure `data.shape` aligns precisely with `(dim1.size, dim2.size, ...)`. For example, if `data.shape` is `(10, 20)`, you need two `Dimension` objects with `size=10` and `size=20` respectively.

Warnings

gotcha Using `GRIB2File` or `NetCDFFile` requires additional optional dependencies (`eccodes` or `netcdf4` respectively). A `ModuleNotFoundError` will occur if these are not installed.
Fix: Install `griddataformats` with optional dependencies: `pip install griddataformats[grib2]` or `pip install griddataformats[netcdf]` (or both for full functionality).
gotcha The `Grid` and `Field` objects expect `numpy.ndarray` for field data. Providing raw Python lists directly to `Field.data` might lead to unexpected behavior or require explicit conversion, impacting performance or causing errors in data manipulation.
Fix: Ensure `Field.data` is a `numpy.ndarray`. Convert lists using `numpy.array(your_list)` before passing them to `Field`.
gotcha The dimensions provided for a `Field` must exactly match the shape of the `data` array. A mismatch in `Dimension.size` attributes versus `data.shape` will raise a `ValueError`.
Fix: Carefully align the `dimensions` list and their `size` attributes with the actual `data.shape` of the `numpy.ndarray` provided to `Field`.

Install

pip install griddataformats Base installation
pip install griddataformats[netcdf] With NetCDF support
pip install griddataformats[grib2] With GRIB2 support
pip install griddataformats[netcdf,grib2] With both NetCDF and GRIB2 support

Imports

Grid
```
from griddataformats.grid import Grid
```

NetCDFFile

from griddataformats.file import NetCDFFile

GRIB2File

from griddataformats.file import GRIB2File

Dimension

from griddataformats.common import Dimension

Field

from griddataformats.common import Field

Unit
```
from griddataformats.common import Unit
```

Quickstart

This quickstart demonstrates how to create a `Grid` object with a `Field` representing temperature data, save it to a NetCDF file, and then read it back. Note that using `NetCDFFile` requires the optional `netcdf4` dependency (install with `pip install griddataformats[netcdf]`).

import tempfile
import os
import numpy as np

from griddataformats.grid import Grid
from griddataformats.common import Dimension, Field, Unit, Origin, GridType
from griddataformats.file import NetCDFFile # Requires 'netcdf4' optional dependency

# Create a simple 2D grid with dummy data
latitude = np.linspace(40, 50, 10)
longitude = np.linspace(-100, -90, 15)
temperature_data = np.random.rand(len(latitude), len(longitude)) * 30 + 273.15 # Kelvin

lat_dim = Dimension("latitude", latitude.shape[0], Unit.degree_north, data=latitude)
lon_dim = Dimension("longitude", longitude.shape[0], Unit.degree_east, data=longitude)

temp_field = Field(
    name="temperature",
    dimensions=[lat_dim, lon_dim],
    units=Unit.kelvin,
    data=temperature_data,
    description="Surface Temperature"
)

grid = Grid(fields=[temp_field], grid_type=GridType.regular_latitude_longitude)

# Save to a temporary NetCDF file
with tempfile.TemporaryDirectory() as tmpdir:
    filepath = os.path.join(tmpdir, "my_grid.nc")
    NetCDFFile.from_grid(grid, filepath)
    print(f"Grid saved to {filepath}")

    # Now read it back
    read_grid = NetCDFFile(filepath).to_grid()
    print(f"Read back grid with {len(read_grid.fields)} field(s).")
    read_field = read_grid.fields[0]
    print(f"Field name: {read_field.name}, Units: {read_field.units}")
    print(f"Data shape: {read_field.data.shape}")
    print(f"First data point: {read_field.data[0,0]:.2f} K")

view raw JSON →