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

close()

Closes a GRIB.

extract_subdomain(handgrip, geometry, vertical_coordinate=None, interpolation=u'linear', cheap_height=True, 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.
• 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. # TODO: not implemented yet

extractprofile(handgrip, lon=None, lat=None, geometry=None, vertical_coordinate=None, interpolation=u'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=u'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.

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.

get_message_at_position(position)

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(headers_only=True)

Iterates sequentially on messages, returning messages.

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

listfields(onlykey=None, select=None, complete=False)

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.

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.

readfield(handgrip, getdata=True, footprints_proxy_as_builder=True, get_info_as_json=None)

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’, ‘indicatorOfTypeOfLevel’:’pl’, ‘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.
• get_info_as_json – if not None, writes the keys given in get_info_as_json as json in field.comment.

readfields(handgrip, getdata=True, footprints_proxy_as_builder=True, get_info_as_json=None)

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’, ‘indicatorOfTypeOfLevel’:’pl’} 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.
• get_info_as_json – if not None, writes the keys given in get_info_as_json as json in field.comment.

handgrip is a dict where you can store all requested GRIB keys...

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=<open file '<stdout>', mode 'w'>, mode=u'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)

---

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

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:

• ordering – flattening of 2D data
• packing – options of packing and compression in GRIB (dict).
• 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)

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

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.

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)

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.

set_2Dvalues(values)

Wrapper to set values as a 2D array, in coherence with ordering parameters already set beforehand.

set_packing(packing)

Specific method to set packing because the order of the elements is important.

Parameters:packing (dict) – GRIB keys from packing.

set_values(values)

Wrapper to set values as a 2D array if gridpoint or 1D if spectral.

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.

---

epygram.formats.GRIB.parse_GRIBstr_todict(strfid)

Parse and return a dict GRIB fid from a string.