epygram.formats.GRIB — Interface-Class to the GRIB format

Contains classes for GRIB resource and GRIB individual message, editions 1 and 2.

---

class epygram.formats.GRIB.NamesGribDef(actual_init=True, concepts=['name', 'shortName', 'cfName', 'cfVarName'])

Bases: griberies.GribDef

Handle name and shortName GRIB definitions.

cfName(fid, grib_edition='grib2', include_comments=False, filter_non_GRIB_keys=True, exact=True)

‘name’ equivalence lookup:

• if fid is a cfName, get the associated GRIB key/value pairs
• if fid is a set of GRIB key/value pairs, get the associated cfName(s)

Cf. method _lookup() for other optional arguments.

cfVarName(fid, grib_edition='grib2', include_comments=False, filter_non_GRIB_keys=True, exact=True)

‘name’ equivalence lookup:

• if fid is a cfVarName, get the associated GRIB key/value pairs
• if fid is a set of GRIB key/value pairs, get the associated cfVarName(s)

Cf. method _lookup() for other optional arguments.

name(fid, grib_edition='grib2', include_comments=False, filter_non_GRIB_keys=True, exact=True)

‘name’ equivalence lookup:

• if fid is a name, get the associated GRIB key/value pairs
• if fid is a set of GRIB key/value pairs, get the associated name(s)

Cf. method _lookup() for other optional arguments.

shortName(fid, grib_edition='grib2', include_comments=False, filter_non_GRIB_keys=True, exact=True)

‘name’ equivalence lookup:

• if fid is a shortName, get the associated GRIB key/value pairs
• if fid is a set of GRIB key/value pairs, get the associated shortName(s)

Cf. method _lookup() for other optional arguments.

---

class epygram.formats.GRIB.GRIB(*args, **kwargs)

Bases: epygram.resources.FileResource.FileResource

Class implementing all specificities for GRIB resource format.

Note

This class is managed by footprint.

• info: Not documented
• priority: PriorityLevel::DEFAULT (rank=1)

Automatic parameters from the footprint:

• filename (builtins.str) - rxx - File name (absolute or relative) of the resource.
• fmtdelayedopen (builtins.bool) - rxx - Opening of the resource delayed (not at time of construction).
  • Optional. Default is False.
• format (builtins.str) - rxx - Format of the resource.
  • Optional. Default is ‘GRIB’.
  • Values: set([‘GRIB’])
• openmode (builtins.str) - rxx - Opening mode.
  • Values: set([‘append’, ‘write’, ‘w’, ‘read’, ‘r’, ‘a’])
  • Remap: dict(append = ‘a’, read = ‘r’, write = ‘w’,)

close()

Closes a GRIB.

extract_subdomain(handgrip, geometry, vertical_coordinate=None, interpolation='linear', external_distance=None, field3d=None, **_)

Extracts a subdomain from the GRIB resource, given its handgrip and the geometry to use.

Parameters:

• handgrip – MUST define the parameter and the type of levels
• geometry – is the geometry on which extract data. None to keep the geometry untouched.
• vertical_coordinate – defines the requested vertical coordinate of the V2DField (cf. epygram.geometries.vertical_coordinates possible values).
• interpolation –

  defines the interpolation function used to compute the profile points locations from the fields grid:

  • if ‘nearest’, each horizontal point of the section is taken as the horizontal nearest neighboring gridpoint;
  • if ‘linear’ (default), each horizontal point of the section is computed with linear spline interpolation;
  • if ‘cubic’, each horizontal point of the section is computed with linear spline interpolation.

extractprofile(handgrip, lon=None, lat=None, geometry=None, vertical_coordinate=None, interpolation='nearest', cheap_height=True, external_distance=None)

Extracts a vertical profile from the GRIB resource, given a handgrip and the geographic location (lon/lat) of the profile.

Parameters:

• handgrip – MUST define the parameter and the type of levels
• lon – the longitude of the desired point.
• lat – the latitude of the desired point.
• geometry – the geometry on which extract data. If None, it is built from lon/lat.

:param vertical_coordinate defines the requested vertical coordinate of the

V1DField (cf. epygram.geometries.vertical_coordinates possible values).

Parameters:

• interpolation –

  defines the interpolation function used to compute the profile at requested lon/lat from the fields grid:

  • if ‘nearest’ (default), extracts profile at the horizontal nearest neighboring gridpoint;
  • if ‘linear’, computes profile with horizontal linear spline interpolation;
  • if ‘cubic’, computes profile with horizontal cubic spline interpolation.
• cheap_height – if True and vertical_coordinate among (‘altitude’, ‘height’), the computation of heights is done without taking hydrometeors into account (in R computation) nor NH Pressure departure (Non-Hydrostatic data). Computation therefore faster.
• external_distance – can be a dict containing the target point value and an external field on the same grid as self, to which the distance is computed within the 4 horizontally nearest points; e.g. {‘target_value’:4810, ‘external_field’:an_H2DField_with_same_geometry}. If so, the nearest point is selected with distance = |target_value - external_field.data|

extractsection(handgrip, end1=None, end2=None, geometry=None, points_number=None, resolution=None, vertical_coordinate=None, interpolation='linear', cheap_height=True)

Extracts a vertical section from the GRIB resource, given its handgrip and the geographic (lon/lat) coordinates of its ends. The section is returned as a V2DField.

Parameters:

• handgrip – MUST define the parameter and the type of levels
• end1 – must be a tuple (lon, lat).
• end2 – must be a tuple (lon, lat).
• geometry – is the geometry on which extract data. If None, defaults to linearily spaced positions computed from points_number.
• points_number – defines the total number of horizontal points of the section (including ends). If None, defaults to a number computed from the ends and the resolution.
• resolution – defines the horizontal resolution to be given to the field. If None, defaults to the horizontal resolution of the field.
• vertical_coordinate – defines the requested vertical coordinate of the V2DField (cf. epygram.geometries.vertical_coordinates possible values).
• interpolation –

  defines the interpolation function used to compute the profile points locations from the fields grid:

  • if ‘nearest’, each horizontal point of the section is taken as the horizontal nearest neighboring gridpoint;
  • if ‘linear’ (default), each horizontal point of the section is computed with linear spline interpolation;
  • if ‘cubic’, each horizontal point of the section is computed with linear spline interpolation.
• cheap_height – if True and vertical_coordinate among (‘altitude’, ‘height’), the computation of heights is done without taking hydrometeors into account (in R computation) nor NH Pressure departure (Non-Hydrostatic data). Computation therefore faster.

filename

Undocumented footprint attribute

find_fields_in_resource(seed=None, generic=False, **_)

Returns a list of the fields from resource whose name match the given seed.

Parameters:

• seed –

  might be:

  • a ‘handgrip’, i.e. a dict where you can store all requested GRIB keys, e.g. {‘shortName’:’t’, ‘indicatorOfTypeOfLevel’:’pl’,

    ’level’:850},

  • a list of handgrips
  • a string like “{‘shortName’:’t’, ‘level’:850}”, that would be converted to a dict handgrip
  • None. If None (default), returns the list of all fields in resource.
• generic – if True, returns complete fid’s, union of {‘FORMATname’:fieldname} and the according generic fid of the fields.

fmtdelayedopen

Undocumented footprint attribute

format

Undocumented footprint attribute

get_message_at_position(*args, **kwargs)

Returns the message at position position, from 0 (first message) to messages_number-1 (last message). Negative position starts from the end: -1 is last message.

Should not be used sequentially, probably very inefficient.

iter_fields(getdata=True, **kwargs)

Iterates sequentially on messages, returning fields.

Parameters:getdata – if False, do not read data from the messages.

iter_messages(*args, **kwargs)

Iterates sequentially on messages, returning messages.

Parameters:headers_only – if False, read data from messages.

listfields(onlykey=None, select=None, complete=False, additional_keys=[])

Returns a list containing the GRIB identifiers of all the fields of the resource.

Parameters:

• onlykey – can be specified as a string or a tuple of strings, so that only specified keys of the fid will returned.
• select – can be specified as a dict(key=value) to restrain the list of fields to those that match the key:value pairs.
• complete – list fields with their natural fid + generic one.
• additional_keys – add given keys in fids

messages_number

Counts the number of messages in file.

open(openmode=None)

Opens a GRIB and initializes some attributes.

Parameters:openmode – optional, to open with a specific openmode, eventually different from the one specified at initialization.

openmode

Undocumented footprint attribute

readfield(handgrip, getdata=True, footprints_proxy_as_builder=False, get_info_as_json=None, read_misc_metadata=['typeOfGeneratingProcess', 'productionStatusOfProcessedData', 'typeOfProcessedData', 'generatingProcessIdentifier', 'typeOfTimeIncrement', 'indicatorOfUnitOfTimeRange', 'indicatorOfUnitForTimeRange', 'indicatorOfUnitForTimeIncrement', 'hoursAfterDataCutoff', 'minutesAfterDataCutoff', 'timeIncrement', 'bitsPerValue', 'dataRepresentationTemplateNumber'])

Finds in GRIB the message that correspond to the handgrip, and returns it as a epygram.base.Field. If several messages meet the requirements, raises error (use readfields() method instead).

Parameters:

• handgrip (dict) – a dict where you can store all requested GRIB keys for discrimination… E.g. {‘shortName’:’t’, ‘typeOfFirstFixedSurface’:100, ‘level’:850} will return the Temperature at 850hPa field.
• getdata – if False, the data is not read, the field consist in the meta-data only.
• footprints_proxy_as_builder – if True, uses footprints.proxy to build fields. True decreases performance. .. deprecated:: 1.3.9
• get_info_as_json – if not None, writes the keys given in get_info_as_json as json in field.comment. .. deprecated:: 1.3.9
• read_misc_metadata – read the specified keys, and store it in field.misc_metadata

readfields(*args, **kwargs)

Finds in GRIB the message(s) that correspond to the handgrip, and returns it as a epygram.base.FieldSet of epygram.base.Field.

Parameters:

• handgrip (dict) – a dict where you can store all requested GRIB keys for discrimination… E.g. {‘shortName’:’t’, ‘typeOfFirstFixedSurface’:100} will return all the Temperature fields on Pressure levels.
• getdata – if False, the data is not read, the field consist in the meta-data only.
• footprints_proxy_as_builder – if True, uses footprints.proxy to build fields. True decreases performance. .. deprecated:: 1.3.9
• get_info_as_json – if not None, writes the keys given in get_info_as_json as json in field.comment. .. deprecated:: 1.3.9
• read_misc_metadata – read the specified keys, and store it in field.misc_metadata

sortfields(sortingkey, onlykey=None)

Returns a sorted list of fields with regards to the given sortingkey of their fid, as a dict of lists.

Parameters:

• sortingkey – key on which to sort out fields
• onlykey – specified as a string or a tuple of strings, so that only specified keys of the fid will returned.

split_UV(fieldseed)

Return two lists of fids corresponding respectively to U and V components of wind, given a fieldseed. Syntax example: ‘shortName’:’u+v’, or ‘indicatorOfParameter’:‘33+34’

what(out=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>, mode='one+list', sortfields=None, details=None, **_)

Writes in file a summary of the contents of the GRIB.

Parameters:

• out – the output open file-like object
• mode –

  among (‘one+list’, ‘fid_list’, ‘what’, ‘ls’, ‘mars’),

  • ’one+list’ = gives the validity/geometry of the first field in GRIB, plus the list of fid.
  • ’fid_list’ = gives only the fid of each field in GRIB.
  • ’what’ = gives the values of the keys from each GRIB message that are used to generate an epygram field from the message (slower).
  • ’ls’ = gives the values of the ‘ls’ keys from each GRIB message.
  • ’mars’ = gives the values of the ‘mars’ keys from each GRIB message.
• sortfields – name of the fid key used to sort fields; e.g. ‘typeOfLevel’; only for mode = ‘one+list’ or ‘fid_list’.
• details – if ‘compression’, gives the ‘packingType’ and ‘bitsPerValue’ parameters of field packing. Only with ‘what’ mode.

writefield(*args, **kwargs)

Writes a Field as a GRIBmessage into the GRIB resource.

Parameters:

• field – a epygram.base.Field instance
• ordering – way of ordering data in GRIB, dict of GRIB keys.
• packing – options of packing and compression in GRIB (dict).
• sample – to use a specific sample GRIB
• grib_edition – to force a GRIB edition number (1, 2).
• other_GRIB_options – other options to be specified in GRIB, as a dict(GRIBkey=value). From v1.3.9, any GRIB2 key should be given through this rather than packing/ordering.
• interpret_comment – set additional key/values taken from field.comment (interpreted as json)

---

class epygram.formats.GRIB.GRIBmessage(source, ordering={'iScansNegatively': 0, 'jPointsAreConsecutive': 0, 'jScansPositively': 0}, packing=None, sample=None, grib_edition=None, other_GRIB_options={}, interpret_comment=False, set_misc_metadata=True)

Bases: epygram.util.RecursiveObject, dict

Class implementing a GRIB message as an object.

Initialize a GRIBmessage from either sources.

Parameters:source –

being a tuple of either form:

• (‘file’, ‘filename’ [, offset_position]) filename being a relative or absolute path to the file it is read in. n = offset_position, if given, enables to read the n+1’th GRIB message in file. Defaults to 0. Negative value counts from the end.
• (‘field’, epygram.fields.H2DField)
• (‘gribid’, gribid) gribid being an integer, refering to the gribid of a GRIB_API message in memory.
• (‘sample’, ‘samplename’) samplename being the name of the sample from which to be generated.

In case source is a field, some options can be forced:

Parameters:

• sample – to use a specific sample GRIB. Specific syntax ‘file:$filename$’ takes the first message in $filename$ as sample.
• grib_edition – to force a GRIB edition number (1, 2).
• other_GRIB_options – other options to be specified in GRIB, as a dict(GRIBkey=value). From v1.3.9, any GRIB2 key should be given through this rather than packing/ordering.

GRIB1

Parameters:

• ordering – flattening of 2D data
• packing – options of packing and compression in GRIB (dict).

GRIB2 (new way)

Parameters:

• interpret_comment – set additional key/values taken from field.comment (interpreted as json)
• set_misc_metadata – set additional key/values taken from field.misc_metadata

actual_fid_keys()

Adjust fid keys to specific grib edition and templates.

as_field(getdata=True, read_misc_metadata=['typeOfGeneratingProcess', 'productionStatusOfProcessedData', 'typeOfProcessedData', 'generatingProcessIdentifier', 'typeOfTimeIncrement', 'indicatorOfUnitOfTimeRange', 'indicatorOfUnitForTimeRange', 'indicatorOfUnitForTimeIncrement', 'hoursAfterDataCutoff', 'minutesAfterDataCutoff', 'timeIncrement', 'bitsPerValue', 'dataRepresentationTemplateNumber'])

Make an epygram H2DField from message.

Parameters:

• getdata – if False, only metadata are read, the field do not contain data.
• read_misc_metadata – read the specified keys, and store it in field.misc_metadata

asfield(getdata=True, footprints_proxy_as_builder=False, get_info_as_json=None)

Deprecated since version 1.3.9.

Returns an epygram.base.Field made out from the GRIB message.

Parameters:

• getdata – if False, only metadata are read, the field do not contain data.
• footprints_proxy_as_builder – if True, uses footprints.proxy to build fields.
• get_info_as_json – if not None, writes the keys given in get_info_as_json as json in field.comment.

classmethod fid_keys_for(editionNumber, productDefinitionTemplateNumber=0, scaleFactorOfFirstFixedSurface=0, scaleFactorOfSecondFixedSurface=0)

Get fid keys according to editionNumber and productDefinitionTemplateNumber, scaleFactorOfFirstFixedSurface and scaleFactorOfSecondFixedSurface.

genfid()

Generates and returns a GRIB-type epygram fid from the message.

get(key, default=None)

Same as dict.get(), but try to read attribute first.

readkeys(namespace=None)

Reads and returns the available keys of the message.

Parameters:namespace –

the namespace of keys to be read, among:

• None: to get all keys present in message,
• ’ls’: to get the same default keys as the grib_ls,
• ’mars’: to get the keys used by MARS.

readmessage(namespace=None, fatal=True)

Reads the meta-data of the message.

Parameters:

• namespace –

  the namespace of keys to be read, among:

  • None: to get all keys present in message,
  • [‘myKey1’, ‘myKey2’, …] for any custom namespace,
  • ’ls’: to get the same default keys as the grib_ls,
  • ’mars’: to get the keys used by MARS.
• fatal – raise errors or ignore failed keys

set_from(k, series_of_dicts, fatal=True)

Set key k from its value first found in one of series_of_dicts.

set_values(values)

Wrapper to set values as a 1D if spectral, or 2D array if gridpoint, with consistency with ordering parameters already set beforehand.

classmethod specific_fid_keys_for(productDefinitionTemplateNumber=0, scaleFactorOfFirstFixedSurface=0, scaleFactorOfSecondFixedSurface=0)

Get specific fid keys according to productDefinitionTemplateNumber and scaleFactorOfFirstFixedSurface and scaleFactorOfSecondFixedSurface.

(GRIB2 only).

update([E, ]**F) → None. Update D from dict/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

write_to_file(ofile)

ofile being an open file-like object designing the physical GRIB file to be written to.