Encoders¶

An encoder converts data into a serialisable format that can be written to a target. Encoders are most commonly used implicitly through to_target(), but can also be created and used directly.

Note

The encoders are still under development. The most advanced encoder is the GRIB encoder, which can handle a variety of data types. Currently, the other encoders only support trivial encoding of data into a serialisable format. For example, the NetCDF encoder simply calls xarray.to_netcdf() on an xarray Dataset/DataArray.

Creating an encoder¶

Use create_encoder() to instantiate an encoder by name:

>>> from earthkit.data import create_encoder
>>> enc = create_encoder("grib")
>>> enc = create_encoder("grib", template=my_field, shortName="2t")

create_encoder(name, *args, **kwargs)¶

Create an encoder identified by name.

Parameters:

name (str) – Name of an encoder (see table below).
args – Positional arguments forwarded to the encoder constructor.
kwargs – Keyword arguments forwarded to the encoder constructor.

Return type:

Encoder

Common constructor parameters¶

All encoders accept the following keyword arguments in their constructors:

Parameter	Description
`template`	A default template object used as the basis for encoding. The exact accepted types depend on the encoder.
`metadata`	A dictionary of default metadata applied to every encoded item. Metadata supplied directly to `Encoder.encode()` is merged on top, with the per-call values taking precedence.
`**kwargs`	Any additional keyword arguments are interpreted as metadata keys and merged into `metadata`.

Encoding data¶

All encoders expose an encode() method:

>>> enc = create_encoder("grib", template=field)
>>> result = enc.encode(values=arr, shortName="2t", step=6)
>>> result.to_file(open("out.grib", "wb"))

Encoder.encode(data=None, values=None, metadata={}, template=None, check_nans=False, missing_value=9999, target=None, **kwargs)¶

Encode data and return an EncodedData object.

Parameters:

data – Earthkit data object to encode (Field, FieldList, xarray Dataset/DataArray, …).
values – Raw values array to encode.
metadata (dict) – Per-call metadata merged on top of the encoder’s default metadata.
template – Per-call template overriding the encoder’s default template.
check_nans (bool) – Replace NaN values with missing_value before encoding.
missing_value – Replacement value used when check_nans is True.
target – Target object; some encoders use this to optimise the output format.

Return type:

EncodedData

Automatic encoder selection¶

When writing to a file target without specifying an encoder explicitly, the encoder is selected automatically from the file extension:

Extension(s)	Encoder
`.grib`, `.grb`, `.grib1`, `.grib2`, `.grb1`, `.grb2`	`grib`
`.nc`, `.nc3`, `.nc4`, `.netcdf`	`netcdf`
`.tiff`, `.tif`	`geotiff`
`.bufr`	`bufr`
`.odb`	`odb`

Available encoders¶

Name	Description	Class
`grib`	Encode data as GRIB. Supports Fields, FieldLists, and NumPy arrays. Requires a template or sufficient metadata to construct a valid GRIB message.	`GribEncoder`
`netcdf`	Encode data as NetCDF via xarray. Accepts Fields, FieldLists, and xarray Datasets/DataArrays.	`NetCDFEncoder`
`geotiff`	Encode data as GeoTIFF. Requires geo-referenced raster data.	`GeoTIFFEncoder`
`csv`	Encode tabular data as comma-separated values.	`CSVEncoder`
`bufr`	Encode data as BUFR (Binary Universal Form for the Representation of meteorological data).	`BufrEncoder`
`odb`	Encode data as ODB (Observational DataBase) format.	`ODBEncoder`
`zarr`	Encode data as a Zarr array store.	`ZarrEncoder`
`covjson`	Encode data as CoverageJSON (CovJSON).	`CovJsonEncoder`
`geojson`	Encode data as GeoJSON.	`GeoJsonEncoder`
`pp`	Encode data as Met Office PP (UM binary) format.	`PPEncoder`
`text`	Encode data as plain text.	`TextEncoder`

Examples¶

GRIB encoder