Conventions

Contents

Conventions#

Different communities and file formats have different ways of encoding the metadata for discrete global grid systems.

The built-in format (called the "xdggs" convention) is to put all metadata on the coordinate containing the cell indices. When decoding, this metadata is used to construct a in-memory xarray index and removed from the coordinate:

Registering a custom convention#

Conventions are defined as an object inheriting from Convention. It must define two methods:

decode() for decoding into the in-memory structure
encode() for encoding the in-memory format to the given convention

For example:

import xdggs
from collections.abc import Hashable
from typing import Any
from xdggs.grid import DGGSInfo


@xdggs.conventions.register_convention("my-convention")
class MyConvention(xdggs.conventions.Convention):
    def decode(
        self,
        obj: xr.Dataset,
        *,
        grid_info: dict[str, Any] | DGGSInfo | None,
        name: Hashable | None,
        index_options: dict[str, Any] | None,
    ) -> xr.Dataset:
        # decode
        pass

    def encode(
        self, obj: xr.Dataset, *, encoding: dict[str, Any] | None = None
    ) -> xr.Dataset:
        # encode
        pass