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.

Footprint:

dict(
    attr = dict(
        filename = dict(
            access = 'rxx', 
            alias = set([]), 
            default = None, 
            info = 'File name (absolute or relative) of the resource.', 
            optional = False, 
            outcast = set([]), 
            remap = dict(), 
            values = set([]),
        ), 
        fmtdelayedopen = dict(
            access = 'rxx', 
            alias = set([]), 
            default = False, 
            info = 'Opening of the resource delayed (not at time of construction).', 
            optional = True, 
            outcast = set([]), 
            remap = dict(), 
            type = bool, 
            values = set([]),
        ), 
        format = dict(
            access = 'rxx', 
            alias = set([]), 
            default = 'GRIB', 
            info = 'Format of the resource.', 
            optional = True, 
            outcast = set([]), 
            remap = dict(), 
            values = set(['GRIB']),
        ), 
        openmode = dict(
            access = 'rxx', 
            alias = set([]), 
            default = None, 
            info = 'Opening mode.', 
            optional = False, 
            outcast = set([]), 
            remap = dict(
                append = 'a', 
                read = 'r', 
                write = 'w',
            ), 
            values = set(['a', 'write', 'r', 'w', 'read', 'append']),
        ),
    ), 
    bind = [], 
    info = 'Not documented', 
    only = dict(), 
    priority = dict(
        level = footprints.priorities.PriorityLevel::DEFAULT,
    ),
)

close()

Closes a GRIB.

extract_subdomain(handgrip, geometry, vertical_coordinate=None, interpolation='linear', cheap_height=True, external_distance=None, field3d=None)

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

Args:

• 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.V1DGeometry coordinate 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.

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.

Args:

• handgrip MUST define the parameter and the type of levels
• lon is the longitude of the desired point.
• lat is the latitude of the desired point.
• geometry is the geometry on which extract data. If None, it is built from lon/lat.
• vertical_coordinate defines the requested vertical coordinate of the V1DField (cf. epygram.geometries.V1DGeometry coordinate possible values).
• 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.

Args:

• 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.V1DGeometry coordinate 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, **kwargs)

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

Args:

• 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.

iter_messages(headers_only=True)

Iterates sequentially on messages, returning messages.

listfields(onlykey=None, select=None)

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

Argument onlykey can be specified as a string or a tuple of strings, so that only specified keys of the fid will returned.

Argument select can be specified as a dict(key=value) to restrain the list of fields to those that match the key:value pairs.

messages_number

Counts the number of messages in file.

open(openmode=None)

Opens a GRIB and initializes some attributes.

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

readfield(handgrip, getdata=True, footprints_builder=False, get_info_as_json=['units'])

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).

handgrip is a dict where you can store all requested GRIB keys... E.g. {‘shortName’:’t’, ‘indicatorOfTypeOfLevel’:’pl’, ‘level’:850} will return the Temperature at 850hPa field.

If getdata == False, the data is not read, the field consist in the meta-data only.

If footprints_builder == True, uses footprints.proxy to build fields. True decreases performance.

If get_info_as_json is not None, writes the keys given in get_info_as_json as json in field.comment.

readfields(handgrip, getdata=True, footprints_builder=False, get_info_as_json=['units'])

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

handgrip is a dict where you can store all requested GRIB keys... E.g. {‘shortName’:’t’, ‘indicatorOfTypeOfLevel’:’pl’} will return all the Temperature fields on Pressure levels.

If getdata == False, the data is not read, the field(s) consist in the meta-data only.

If footprints_builder == True, uses footprints.proxy to build fields. True decreases performance.

If get_info_as_json is not None, writes the keys given in get_info_as_json as json in field.comment.

sortfields(sortingkey, onlykey=None)

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

Argument onlykey can be 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' at 0x7f7b0e24c150>, mode='one+list', sortfields=None, details=None, **kwargs)

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

Args:

• out: the output open file-like object (duck-typing: out.write() only is needed).
• 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.

Args:

• field: a epygram.base.Field instance
• 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={'iScansNegatively': 0, 'jPointsAreConsecutive': 0, '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.

asfield(getdata=True, footprints_builder=False, get_info_as_json=['units'])

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

• getdata: if False, only metadata are read, the field do not contain data.
• footprints_builder: if True, uses footprints.proxy to build fields. Defaults to False for performance reasons.
• 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.

Args:

• 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.

Args:

• 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. packing to be a dict.

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.