earthkit.data.encoders.grib

Classes

Combined
GribEncodedData	The object representing the encoded GRIB message.
GribEncoder	Encoder for GRIB format.
GribHandleMaker	Create a new GribCodesHandle from a template, field or metadata.

Module Contents

class earthkit.data.encoders.grib.Combined(handle, metadata)

handle

metadata

class earthkit.data.encoders.grib.GribEncodedData(handle, template_field=None)

Bases: earthkit.data.encoders.EncodedData

The object representing the encoded GRIB message.

get(key, default=None)

Get a value from the GRIB message metadata.

Parameters:

• key (str) – The key of the metadata to retrieve.

• default (any, optional) – The default value to return if the key is not found.

Return type:

The value associated with the key, or the default value if the key is not found.

handle

prefer_file_path = False

to_bytes()

Return the GRIB message as bytes.

to_field()

Convert the GRIB message to a Field object.

to_file(f)

Write the GRIB message to a file.

Parameters:

f (file-like object) – The file-like object to write the GRIB message to.

class earthkit.data.encoders.grib.GribEncoder(template=None, metadata=None, **kwargs)

Bases: earthkit.data.encoders.Encoder

Encoder for GRIB format.

This class is used to encode data to GRIB format via the encode() method.

Parameters:

• template (Field, GribCodesHandle, bytes, str, int, None) – A preset template to use for encoding when encode() is called without a template. It can be a Field, a GribCodesHandle, a GRIB message as bytes, an ecCodes GRIB sample name as string, a raw ecCodes handle as an integer, or None. See encode() for more details on how the template is used.

• metadata (dict) – A preset metadata to encode. The keys must be ecCodes GRIB keys, optionally prefixed with “metadata.”. This metadata is used as default when encode() is called without metadata. If metadata is provided in the encode() method, it is merged with this preset metadata, with the metadata provided in the encode() method taking precedence.

• kwargs (dict) – Additional keyword arguments interpreted as metadata to encode. The keys must be ecCodes GRIB keys, optionally prefixed with “metadata.”.

Examples

See the howto examples for more details and examples of encoding GRIB data with GribEncoder.

• GRIB encoder

• GRIB: modifying metadata

• GRIB: modifying values

Using with a preset template and metadata:

>>> import earthkit.data as ekd
>>> template = ekd.from_source("sample", "test.grib").to_fieldlist()[0]
>>> template.get("metadata.shortName")
'2t'
>>> encoder = GribEncoder(template=template, metadata={"shortName": "msl"})
>>> d = encoder.encode(values=template.values + 1.0, step=6)
>>> f = d.to_field()
>>> f.get("parameter.variable")
'msl'
>>> f.get("parameter.shortName")
'msl'
>>> f.get("parameter.units")
'hPa'
>>> f.get("step")
6

Using without preset template and metadata: >>> encoder = GribEncoder() >>> d = encoder.encode(values=template.values + 1.0, metadata={“shortName”: “msl”}, step=6) >>> f = d.to_field() >>> f.get(“parameter.variable”) ‘msl’ >>> f.get(“parameter.shortName”) ‘msl’ >>> f.get(“parameter.units”) ‘hPa’ >>> f.get(“step”) 6

encode(data=None, values=None, check_nans=True, metadata=None, template=None, missing_value=9999, target=None, **kwargs)

Encode new GRIB message(s).

Parameters:

• data (Field, FieldList, Numpy array, or None) – The data to encode. Can be a Field, a FieldList, a Numpy array, or None. If None, the new GRIB message(s) will be created from the values, metadata and template. Cannot be specified together with values and template. When template is also provided, it will be used as a basis for encoding, but the values will be taken from data.

• values (numpy.ndarray or None) – The values to encode. If None, the values will be taken from the data or template. Takes precedence over the values in data or template if any of them are provided. If the values contain NaNs, they will be replaced with the missing_value provided. Cannot be specified together with data and template.

• check_nans (bool) – Check for NaNs in the values and replace them with missing_value.

• metadata (dict) – Metadata to encode. The keys can be ecCodes GRIB keys, optionally prefixed with “metadata.” The format independent keys from Field metadata are also accepted. If format independent keys are provided, they are applied first to create a new handle, then if ecCodes GRIB keys are provided too, they are applied on top of the handle.

• template (Field, GribCodesHandle, bytes, str, int, None) – A template to use for encoding. It can be a Field, a GribCodesHandle, a GRIB message as bytes, an ecCodes GRIB sample name as string, a raw ecCodes handle as an integer, or None. If None, a the GribEncoder.template will be used if provided. Otherwise a new handle will be created from the data, values and metadata. Takes precedence over the data in forming the new GRIB message, but values are taken from the data if no provided directly. Cannot be specified together with data and values.

• missing_value (float) – The value to use for NaNs. Default is 9999, which is the default missing value used by ecCode when encoding with a template that does not have a valid “bitsPerValue” key.

• kwargs (dict) – Additional metadata to encode.

Returns:

The object representing the encoded GRIB message(s). When a single GRIB message is encoded, a GribEncodedData object is returned. When multiple GRIB messages are encoded, a generator of GribEncodedData objects is returned that can be processed in a loop.

Return type:

GribEncodedData or generator of GribEncodedData

Notes

data, values and template cannot be specified together. If more than one of them are provided, the following rules applied:

• data, value: The values will be taken from the values argument.

• data, template: The template will be used as a basis for encoding, but

  the values will be taken from the data argument.

• values, template: The template will be used as a basis for encoding, but

  the values will be taken from the values argument.

When no data and template are provided, a new GRIB message will be created from the values and metadata. This is an experimental feature and only works for certain metadata keys and the grid has to be either global lat-lon or reduced Gaussian grid. The geography is inferred from the shape of the specified values.

Examples

See the howto examples for more details and examples of encoding GRIB data with GribEncoder.

• GRIB encoder

metadata

template

class earthkit.data.encoders.grib.GribHandleMaker(template=None)

Create a new GribCodesHandle from a template, field or metadata.

static handle_from_field(field, values_shape=None)

handle_from_metadata(values_shape, metadata, compulsory)

static handle_from_template(template, values_shape=None, field_metadata=None, clone=True)

make(values_shape=None, metadata=None, template=None, field_metadata=None)

Create a new GribCodesHandle from a template, field or metadata.

May modify existing metadata

Parameters:

• values_shape (tuple, optional) – The shape of the values to encode

• metadata (dict, optional) – Metadata to encode

• template (GribCoder, optional) – A template to use for encoding

• field_metadata (dict, optional) – Metadata to be set on the field before encoding.

template

update_metadata_from_template(metadata, template, handle)