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: epygram.extra.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’, ‘r’, ‘read’, ‘w’, ‘a’, ‘write’])

  • Remap: dict(append = ‘a’, read = ‘r’, write = ‘w’,)

Constructor. See its footprint for arguments.

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, global_shift_center=None)

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.

• global_shift_center – for global lon/lat grids, shift the center by the requested angle (in degrees). Enables a [0,360] grid to be shifted to a [-180,180] grid, for instance (with -180 argument).

filename

File name (absolute or relative) of the resource (see the documentation above for more details).

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

Opening of the resource delayed (not at time of construction) (see the documentation above for more details).

format

Format of the resource (see the documentation above for more details).

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

property 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

Opening mode (see the documentation above for more details).

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', 'uvRelativeToGrid'])

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', 'uvRelativeToGrid'])

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.