data.readers.grib.metadata

Classes

`GribFieldMetadata`	Represent the metadata of a GRIB field.
`GribMetadata`	GRIB metadata.
`RestrictedGribMetadata`	Hide internal keys and namespaces in GRIB metadata.
`StandAloneGribMetadata`	Represent standalone GRIB metadata owning an ecCodes GRIB handle.

Module Contents

class data.readers.grib.metadata.GribFieldMetadata(field, **kwargs)

Bases: GribMetadata

Represent the metadata of a GRIB field.

GribFieldMetadata is created internally by a GribField. It does not own the ecCodes GRIB handle but can access it through the GribField. Calling metadata() without arguments on a GribField returns this object.

as_namespace(namespace=None)

Return all the keys/values from a namespace.

Parameters:: namespace (str, None) – The ecCodes namespace. earthkit-data also defines the “default” namespace, which contains all the GRIB keys that ecCodes can access without specifying a namespace. When namespace is None or an empty str all the available keys/values are returned.
Returns:: All the keys/values from the namespace.
Return type:: dict

base_datetime()

data_format()

Return the underlying data format.

Return type:: str

datetime()

Return the date and time of the field.

Returns:: Dict with items “base_time” and “valid_time”.
Return type:: dict of datatime.datetime

Examples

>>> import earthkit.data
>>> ds = earthkit.data.from_source("file", "tests/data/t_time_series.grib")
>>> ds[4].datetime()
{'base_time': datetime.datetime(2020, 12, 21, 12, 0),
'valid_time': datetime.datetime(2020, 12, 21, 18, 0)}

describe_keys(): Return the keys to be used with the describe() method.

dump(namespace=all, **kwargs)

Generate dump with all the metadata keys belonging to namespace.

In a Jupyter notebook it is represented as a tabbed interface.

Parameters:

namespace (str, list, tuple, None or all) –
The namespace to dump. Any ecCodes namespace can be used here. earthkit-data also defines the “default” namespace, which contains all the GRIB keys that ecCodes can access without specifying a namespace. The following namespace values have a special meaning:
- all: all the available namespaces will be used (including “default”).
- None or empty str: the “default” namespace will be used.
**kwargs (dict, optional) – Other keyword arguments used for testing only

Returns:

Dict-like object with one item per namespace. In a Jupyter notebook represented as a tabbed interface to browse the dump contents.

Return type:

NamespaceDump

Examples

GRIB: inspecting contents

geography()

Geography: Get geography description.

If it is not available None is returned.

get(key, default=None, *, astype=None, raise_on_missing=False)

Return the value for key.

Parameters:

key (str) – Metadata key
default (value) – Specify the default value for key. Returned when key is not found or its value is a missing value and raise_on_missing is False.
astype (type as str, int or float) – Return/access type for key. When it is supported astype is passed to the underlying metadata accessor as an option. Otherwise the value is cast to astype after it is taken from the accessor.
raise_on_missing (bool) – When it is True raises an exception if key is not found or it has a missing value.

Returns:

Returns the key value. Returns default if key is not found or it has a missing value and raise_on_missing is False.

Return type:

value

Raises:

KeyError – If raise_on_missing is True and key is not found or it has a missing value.

property grid_spec

property gridspec

index_keys(): Return the keys to be used with the indices() method.

indexing_datetime()

items()

Return the metadata items.

Return type:: Iterable of (key,value) pairs

keys()

Return the metadata keys.

Return type:: Iterable of str

ls_keys(): Return the keys to be used with the ls() method.

namespaces()

Return the available namespaces.

Return type:: list of str

override(*args, headers_only_clone=True, **kwargs)

Create a new metadata object by cloning a new GRIB handle and setting the keys in it.

Parameters:

*args (tuple) – Positional arguments. When present must be a dict with the GRIB keys to set in the new GRIB handle.
headers_only_clone (bool, optional) – If True, the new GRIB handle will be created with headers_only=True to reduce the data section. With this the GRIB handle size will be significantly smaller, but the data section becomes unusable. Default is True.
**kwargs (dict, optional) – Other keyword arguments specifying the GRIB keys to set.

Returns:

The new metadata object. There is always a StandAloneGribMetadata object created containing the new GRIB handle updated with the specified keys. It is then wrapped in a WrappedMetadata object storing "bitsPerValue" as an extra key.

Return type:

WrappedMetadata

Notes

When "bitsPerValue" is a key to set it is not written to the new handle. Instead, it is stored as an extra key in the resulting WrappedMetadata object.

param_level()

reference_datetime()

step_timedelta()

valid_datetime()

class data.readers.grib.metadata.GribMetadata(cache=None, **kwargs)

Bases: earthkit.data.core.metadata.Metadata

GRIB metadata.

GribMetadata is an abstract class and should not be instantiated directly. There are two concrete implementations: GribFieldMetadata and StandAloneGribMetadata.

as_namespace(namespace=None)

Return all the keys/values from a namespace.

Parameters:: namespace (str, None) – The ecCodes namespace. earthkit-data also defines the “default” namespace, which contains all the GRIB keys that ecCodes can access without specifying a namespace. When namespace is None or an empty str all the available keys/values are returned.
Returns:: All the keys/values from the namespace.
Return type:: dict

base_datetime()

data_format()

Return the underlying data format.

Return type:: str

datetime()

Return the date and time of the field.

Returns:: Dict with items “base_time” and “valid_time”.
Return type:: dict of datatime.datetime

Examples

>>> import earthkit.data
>>> ds = earthkit.data.from_source("file", "tests/data/t_time_series.grib")
>>> ds[4].datetime()
{'base_time': datetime.datetime(2020, 12, 21, 12, 0),
'valid_time': datetime.datetime(2020, 12, 21, 18, 0)}

describe_keys(): Return the keys to be used with the describe() method.

dump(namespace=all, **kwargs)

Generate dump with all the metadata keys belonging to namespace.

In a Jupyter notebook it is represented as a tabbed interface.

Parameters:

namespace (str, list, tuple, None or all) –
The namespace to dump. Any ecCodes namespace can be used here. earthkit-data also defines the “default” namespace, which contains all the GRIB keys that ecCodes can access without specifying a namespace. The following namespace values have a special meaning:
- all: all the available namespaces will be used (including “default”).
- None or empty str: the “default” namespace will be used.
**kwargs (dict, optional) – Other keyword arguments used for testing only

Returns:

Dict-like object with one item per namespace. In a Jupyter notebook represented as a tabbed interface to browse the dump contents.

Return type:

NamespaceDump

Examples

GRIB: inspecting contents

geography()

Geography: Get geography description.

If it is not available None is returned.

get(key, default=None, *, astype=None, raise_on_missing=False)

Return the value for key.

Parameters:

key (str) – Metadata key
default (value) – Specify the default value for key. Returned when key is not found or its value is a missing value and raise_on_missing is False.
astype (type as str, int or float) – Return/access type for key. When it is supported astype is passed to the underlying metadata accessor as an option. Otherwise the value is cast to astype after it is taken from the accessor.
raise_on_missing (bool) – When it is True raises an exception if key is not found or it has a missing value.

Returns:

Returns the key value. Returns default if key is not found or it has a missing value and raise_on_missing is False.

Return type:

value

Raises:

KeyError – If raise_on_missing is True and key is not found or it has a missing value.

property grid_spec

property gridspec

index_keys(): Return the keys to be used with the indices() method.

indexing_datetime()

items()

Return the metadata items.

Return type:: Iterable of (key,value) pairs

keys()

Return the metadata keys.

Return type:: Iterable of str

ls_keys(): Return the keys to be used with the ls() method.

namespaces()

Return the available namespaces.

Return type:: list of str

override(*args, headers_only_clone=True, **kwargs)

Create a new metadata object by cloning a new GRIB handle and setting the keys in it.

Parameters:

*args (tuple) – Positional arguments. When present must be a dict with the GRIB keys to set in the new GRIB handle.
headers_only_clone (bool, optional) – If True, the new GRIB handle will be created with headers_only=True to reduce the data section. With this the GRIB handle size will be significantly smaller, but the data section becomes unusable. Default is True.
**kwargs (dict, optional) – Other keyword arguments specifying the GRIB keys to set.

Returns:

The new metadata object. There is always a StandAloneGribMetadata object created containing the new GRIB handle updated with the specified keys. It is then wrapped in a WrappedMetadata object storing "bitsPerValue" as an extra key.

Return type:

WrappedMetadata

Notes

When "bitsPerValue" is a key to set it is not written to the new handle. Instead, it is stored as an extra key in the resulting WrappedMetadata object.

param_level()

reference_datetime()

step_timedelta()

valid_datetime()

class data.readers.grib.metadata.RestrictedGribMetadata(metadata)

Bases: earthkit.data.core.metadata.WrappedMetadata

Hide internal keys and namespaces in GRIB metadata.

Examples

GRIB: using the metadata object

as_namespace(namespace)

dump(namespace=all, **kwargs)

get(key, default=None, *, astype=None, raise_on_missing=False, **kwargs)

items()

Return the metadata items.

Return type:: Iterable of (key,value) pairs

keys()

Return the metadata keys.

Return type:: Iterable of str

static merge_list(v1, v2)

namespaces()

override(*args, **kwargs)

class data.readers.grib.metadata.StandAloneGribMetadata(handle, **kwargs)

Bases: GribMetadata

Represent standalone GRIB metadata owning an ecCodes GRIB handle.

StandAloneGribMetadata possesses its own ecCodes handle. Calling override() on GribMetadata always returns a StandAloneGribMetadata object.

>>> ds = earthkit.data.from_source("file", "docs/examples/test4.grib")
>>> md = ds[0].metadata()
>>> md["shortName"]
't'
>>> md.get("shortName")
't'
>>> md.get("nonExistentKey")
>>> md.get("nonExistentKey", 12)
12

Examples

GRIB: using the metadata object

as_namespace(namespace=None)

Return all the keys/values from a namespace.

Parameters:: namespace (str, None) – The ecCodes namespace. earthkit-data also defines the “default” namespace, which contains all the GRIB keys that ecCodes can access without specifying a namespace. When namespace is None or an empty str all the available keys/values are returned.
Returns:: All the keys/values from the namespace.
Return type:: dict

base_datetime()

data_format()

Return the underlying data format.

Return type:: str

datetime()

Return the date and time of the field.

Returns:: Dict with items “base_time” and “valid_time”.
Return type:: dict of datatime.datetime

Examples

>>> import earthkit.data
>>> ds = earthkit.data.from_source("file", "tests/data/t_time_series.grib")
>>> ds[4].datetime()
{'base_time': datetime.datetime(2020, 12, 21, 12, 0),
'valid_time': datetime.datetime(2020, 12, 21, 18, 0)}

describe_keys(): Return the keys to be used with the describe() method.

dump(namespace=all, **kwargs)

Generate dump with all the metadata keys belonging to namespace.

In a Jupyter notebook it is represented as a tabbed interface.

Parameters:

namespace (str, list, tuple, None or all) –
The namespace to dump. Any ecCodes namespace can be used here. earthkit-data also defines the “default” namespace, which contains all the GRIB keys that ecCodes can access without specifying a namespace. The following namespace values have a special meaning:
- all: all the available namespaces will be used (including “default”).
- None or empty str: the “default” namespace will be used.
**kwargs (dict, optional) – Other keyword arguments used for testing only

Returns:

Dict-like object with one item per namespace. In a Jupyter notebook represented as a tabbed interface to browse the dump contents.

Return type:

NamespaceDump

Examples

GRIB: inspecting contents

geography()

Geography: Get geography description.

If it is not available None is returned.

get(key, default=None, *, astype=None, raise_on_missing=False)

Return the value for key.

Parameters:

key (str) – Metadata key
default (value) – Specify the default value for key. Returned when key is not found or its value is a missing value and raise_on_missing is False.
astype (type as str, int or float) – Return/access type for key. When it is supported astype is passed to the underlying metadata accessor as an option. Otherwise the value is cast to astype after it is taken from the accessor.
raise_on_missing (bool) – When it is True raises an exception if key is not found or it has a missing value.

Returns:

Returns the key value. Returns default if key is not found or it has a missing value and raise_on_missing is False.

Return type:

value

Raises:

KeyError – If raise_on_missing is True and key is not found or it has a missing value.

property grid_spec

property gridspec

index_keys(): Return the keys to be used with the indices() method.

indexing_datetime()

items()

Return the metadata items.

Return type:: Iterable of (key,value) pairs

keys()

Return the metadata keys.

Return type:: Iterable of str

ls_keys(): Return the keys to be used with the ls() method.

namespaces()

Return the available namespaces.

Return type:: list of str

override(*args, headers_only_clone=True, **kwargs)

Create a new metadata object by cloning a new GRIB handle and setting the keys in it.

Parameters:

*args (tuple) – Positional arguments. When present must be a dict with the GRIB keys to set in the new GRIB handle.
headers_only_clone (bool, optional) – If True, the new GRIB handle will be created with headers_only=True to reduce the data section. With this the GRIB handle size will be significantly smaller, but the data section becomes unusable. Default is True.
**kwargs (dict, optional) – Other keyword arguments specifying the GRIB keys to set.

Returns:

The new metadata object. There is always a StandAloneGribMetadata object created containing the new GRIB handle updated with the specified keys. It is then wrapped in a WrappedMetadata object storing "bitsPerValue" as an extra key.

Return type:

WrappedMetadata

Notes

When "bitsPerValue" is a key to set it is not written to the new handle. Instead, it is stored as an extra key in the resulting WrappedMetadata object.

param_level()

reference_datetime()

step_timedelta()

valid_datetime()