# API

## Example usage

from the python interpreter prompt, import the package:

    >>> import pygrib

open a GRIB file, create a grib message iterator:

    >>> grbs = pygrib.open('sampledata/flux.grb')

pygrib open instances behave like regular python file objects, with `seek`, `tell`, `read`, `readline` and `close` methods, except that offsets are measured in grib messages instead of bytes:

    >>> grbs.seek(2)
    >>> grbs.tell()
    2
    >>> grb = grbs.read(1)[0] # read returns a list with the next N (N=1 in this case) messages.
    >>> grb # printing a grib message object displays summary info
    3:Maximum temperature:K (instant):regular_gg:heightAboveGround:level 2 m:fcst time 108-120 hrs:from 200402291200
    >>> grbs.tell()
    3

print an inventory of the file:

    >>> grbs.seek(0)
    >>> for grb in grbs:
    >>>     grb
    1:Precipitation rate:kg m**-2 s**-1 (avg):regular_gg:surface:level 0:fcst time 108-120 hrs (avg):from 200402291200
    2:Surface pressure:Pa (instant):regular_gg:surface:level 0:fcst time 120 hrs:from 200402291200
    3:Maximum temperature:K (instant):regular_gg:heightAboveGround:level 2 m:fcst time 108-120 hrs:from 200402291200
    4:Minimum temperature:K (instant):regular_gg:heightAboveGround:level 2 m:fcst time 108-120 hrs:from 200402291200

find the first grib message with a matching name:

    >>> grb = grbs.select(name='Maximum temperature')[0]

extract the data values using the `values` key (`grb.keys()` will return a list of the available keys):

    >>> maxt = grb.values # same as grb['values']
    # The data is returned as a numpy array, or if missing values or a bitmap
    # are present, a numpy masked array.  Reduced lat/lon or gaussian grid
    # data is automatically expanded to a regular grid. Details of the internal
    # representation of the grib data (such as the scanning mode) are handled
    # automatically.
    >>> maxt.shape, maxt.min(), maxt.max()
    (94, 192) 223.7 319.9

get the latitudes and longitudes of the grid:

    >>> lats, lons = grb.latlons()
    >>> lats.shape, lats.min(), lats.max(), lons.shape, lons.min(), lons.max()
    (94, 192) -88.5419501373 88.5419501373  0.0 358.125

get the second grib message:

    >>> grb = grbs.message(2) # same as grbs.seek(1); grb=grbs.readline()
    >>> grb
    2:Surface pressure:Pa (instant):regular_gg:surface:level 0:fcst time 120 hrs:from 200402291200

extract data and get lat/lon values for a subset over North America:

    >>> data, lats, lons = grb.data(lat1=20,lat2=70,lon1=220,lon2=320)
    >>> data.shape, lats.min(), lats.max(), lons.min(), lons.max()
    (26, 53) 21.904439458 69.5216630593 221.25 318.75

modify the values associated with existing keys:

    >>> grb['forecastTime'] = 240
    >>> grb.dataDate = 20100101

get the binary string associated with the coded message:

    >>> msg = grb.tostring()
    >>> grbs.close() # close the grib file.

write the modified message to a new GRIB file:

    >>> grbout = open('test.grb','wb')
    >>> grbout.write(msg)
    >>> grbout.close()
    >>> pygrib.open('test.grb').readline()
    1:Surface pressure:Pa (instant):regular_gg:surface:level 0:fcst time 240 hrs:from 201001011200

## Module docstrings

pygrib module

`pygrib.``fromstring`(string)

  Create a `gribmessage` instance from a python bytes object representing a binary grib message (the reverse of `gribmessage.tostring()`).

`pygrib.``gaulats`(nlats)

  Returns nlats gaussian latitudes, in degrees, oriented from north to south. nlats must be even.

class `pygrib.``gribmessage`

  Bases: `object`

  Grib message object.

  Each grib message has attributes corresponding to GRIB keys. Parameter names are described by the `name`, `shortName` and `paramID` keys. pygrib also defines some special attributes which are defined below

  Variables

    - messagenumber – The grib message number in the file.

    - projparams – A dictionary containing proj4 key/value pairs describing the grid. Set to `None` for unsupported grid types.

    - expand_reduced – If True (default), reduced lat/lon and gaussian grids will be expanded to regular grids when data is accessed via `values` key. If False, data is kept on unstructured reduced grid, and is returned in a 1-d array.

    - fcstimeunits – A string representing the forecast time units (an empty string if not defined).

    - analDate – A python datetime instance describing the analysis date and time for the forecast. Only set if forecastTime and julianDay keys exist.

    - validDate – A python datetime instance describing the valid date and time for the forecast. Only set if forecastTime and julianDay keys exist, and fcstimeunits is defined. If forecast time is a range, then `validDate` corresponds to the end of the range.

  `data`(lat1=None, lat2=None, lon1=None, lon2=None)

    extract data, lats and lons for a subset region defined by the keywords lat1,lat2,lon1,lon2.

    The default values of lat1,lat2,lon1,lon2 are None, which means the entire grid is returned.

    If the grid type is unprojected lat/lon and a geographic subset is requested (by using the lat1,lat2,lon1,lon2 keywords), then 2-d arrays are returned, otherwise 1-d arrays are returned.

  `expand_grid`(True or False)

    toggle expansion of 1D reduced grid data to a regular (2D) grid (on by default).

  `has_key`(key)

    tests whether a grib message object has a specified key.

  `is_missing`(key)

    returns True if key is invalid or value associated with key is equal to grib missing value flag (False otherwise)

  `keys`()

    return keys associated with a grib message in a list

  `latlons`()

    compute lats and lons (in degrees) of grid. Currently handles regular lat/lon, global gaussian, mercator, stereographic, lambert conformal, albers equal-area, space-view, azimuthal equidistant, reduced gaussian, reduced lat/lon, lambert azimuthal equal-area, rotated lat/lon and rotated gaussian grids.

    Returns

      `lats,lons` numpy arrays containing latitudes and longitudes of grid (in degrees).

  `tostring`()

    return coded grib message in a binary string.

  `valid_key`(key)

    tests whether a grib message object has a specified key, it is not missing and it has a value that can be read.

class `pygrib.``index`(filename, *args)

  Bases: `object`

  returns grib index object given GRIB filename indexed by keys given in *args. The `select` or `__call__` method can then be used to selected grib messages based on specified values of indexed keys. Unlike `open.select()`, containers or callables cannot be used to select multiple key values. However, using `index.select()` is much faster than `open.select()`.

  Warning: Searching for data within multi-field grib messages does not work using an index and is not supported by ECCODES library. NCEP often puts u and v winds together in a single multi-field grib message. You will get incorrect results if you try to use an index to find data in these messages. Use the slower, but more robust `open.select()` in this case.

  If no key are given (i.e. *args is empty), it is assumed the filename represents a previously saved index (created using the `grib_index_build` tool or `index.write()`) instead of a GRIB file.

  Example usage:

      >>> import pygrib
      >>> grbindx=pygrib.index('sampledata/gfs.grb','shortName','typeOfLevel','level')
      >>> grbindx.keys
      ['shortName', 'level']
      >>> selected_grbs=grbindx.select(shortName='gh',typeOfLevel='isobaricInhPa',level=500)
      >>> for grb in selected_grbs:
      >>>     grb
      1:Geopotential height:gpm (instant):regular_ll:isobaricInhPa:level 500 Pa:fcst time 72 hrs:from 200412091200:lo res cntl fcst
      >>> # __call__ method does same thing as select
      >>> selected_grbs=grbindx(shortName='u',typeOfLevel='isobaricInhPa',level=250)
      >>> for grb in selected_grbs:
      >>>     grb
      1:u-component of wind:m s**-1 (instant):regular_ll:isobaricInhPa:level 250 Pa:fcst time 72 hrs:from 200412091200:lo res cntl fcst
      >>> grbindx.write('gfs.grb.idx') # save index to a file
      >>> grbindx.close()
      >>> grbindx = pygrib.index('gfs.grb.idx') # re-open index (no keys specified)
      >>> grbindx.keys # not set when opening a saved index file.
      None
      >>> for grb in selected_grbs:
      >>>     grb
      1:u-component of wind:m s**-1 (instant):regular_ll:isobaricInhPa:level 250 Pa:fcst time 72 hrs:from 200412091200:lo res cntl fcst

  Variables

    - keys – list of strings containing keys used in the index. Set to `None` when opening a previously saved grib index file.

    - types – if keys are typed, this list contains the type declarations (`l`, `s` or `d`). Type declarations are specified by appending to the key name (i.e. `level:l` will search for values of `level` that are longs). Set to `None` when opening a previously saved grib index file.

  `close`()

    deallocate C structures associated with class instance

  `select`(**kwargs)

    return a list of `gribmessage` instances from grib index object corresponding to specific values of indexed keys (given by kwargs). Unlike `open.select()`, containers or callables cannot be used to select multiple key values. However, using `index.select()` is much faster than `open.select()`.

    Example usage:

        >>> import pygrib
        >>> grbindx=pygrib.index('sampledata/gfs.grb','shortName','typeOfLevel','level')
        >>> selected_grbs=grbindx.select(shortName='gh',typeOfLevel='isobaricInhPa',level=500)
        >>> for grb in selected_grbs:
        >>>     grb
        1:Geopotential height:gpm (instant):regular_ll:isobaricInhPa:level 500 Pa:fcst time 72 hrs:from 200412091200:lo res cntl fcst
        >>> # __call__ method does same thing as select
        >>> selected_grbs=grbindx(shortName='u',typeOfLevel='isobaricInhPa',level=250)
        >>> for grb in selected_grbs:
        >>>     grb
        1:u-component of wind:m s**-1 (instant):regular_ll:isobaricInhPa:level 250 Pa:fcst time 72 hrs:from 200412091200:lo res cntl fcst
        >>> grbindx.close()

  `write`(filename)

    save grib index to file

`pygrib.``julian_to_datetime`(julday)

  convert Julian day number to python datetime instance.

  Used to create `validDate` and `analDate` attributes from `julianDay` and `forecastTime` keys.

`pygrib.``multi_support_off`()

  turn off support for multi-field grib messages

`pygrib.``multi_support_on`()

  turn on support for multi-field grib messages (default)

class `pygrib.``open`(filename)

  Bases: `object`

  returns GRIB file iterator object given GRIB filename. When iterated, returns instances of the `gribmessage` class. Behaves much like a python file object, with `seek()`, `tell()`, `read()` `readline()` and `close()` methods except that offsets are measured in grib messages instead of bytes. Additional methods include `rewind()` (like `seek(0)`), `message()` (like `seek(N-1)`; followed by `readline()`), and `select()` (filters messages based on specified conditions). The `__call__` method forwards to `select()`, and instances can be sliced with `__getitem__` (returning lists of `gribmessage` instances). The position of the iterator is not altered by slicing with `__getitem__`.

  Variables

    - messages – The total number of grib messages in the file.

    - messagenumber – The grib message number that the iterator currently points to (the value returned by `tell()`).

    - name – The GRIB file which the instance represents.

  `close`()

    close GRIB file, deallocate C structures associated with class instance

  `message`(N)

    retrieve N’th message in iterator. same as `seek(N-1)` followed by `readline()`.

  `read`(N=None)

    read N messages from current position, returning grib messages instances in a list. If N=None, all the messages to the end of the file are read. `pygrib.open(f).read()` is equivalent to `list(pygrib.open(f))`, both return a list containing `gribmessage` instances for all the grib messages in the file `f`.

  `readline`()

    read one entire grib message from the file. Returns a `gribmessage` instance, or `None` if an `EOF` is encountered.

  `rewind`()

    rewind iterator (same as `seek(0)`)

  `seek`(N, from_what=0)

    advance iterator N grib messages from beginning of file (if `from_what=0`), from current position (if `from_what=1`) or from the end of file (if `from_what=2`).

  `select`(**kwargs)

    return a list of `gribmessage` instances from iterator filtered by `kwargs`. If keyword is a container object, each grib message in the iterator is searched for membership in the container. If keyword is a callable (has a `_call__` method), each grib message in the iterator is tested using the callable (which should return a boolean). If keyword is not a container object or a callable, each grib message in the iterator is tested for equality.

    Example usage:

        >>> import pygrib
        >>> grbs = pygrib.open('sampledata/gfs.grb')
        >>> selected_grbs=grbs.select(shortName='gh',typeOfLevel='isobaricInhPa',level=10)
        >>> for grb in selected_grbs: grb
        26:Geopotential height:gpm (instant):regular_ll:isobaricInhPa:level 10 Pa:fcst time 72 hrs:from 200412091200:lo res cntl fcst
        >>> # the __call__ method does the same thing
        >>> selected_grbs=grbs(shortName='gh',typeOfLevel='isobaricInhPa',level=10)
        >>> for grb in selected_grbs: grb
        26:Geopotential height:gpm (instant):regular_ll:isobaricInhPa:level 10 Pa:fcst time 72 hrs:from 200412091200:lo res cntl fcst
        >>> # to select multiple specific key values, use containers (e.g. sequences)
        >>> selected_grbs=grbs(shortName=['u','v'],typeOfLevel='isobaricInhPa',level=[10,50])
        >>> for grb in selected_grbs: grb
        193:u-component of wind:m s**-1 (instant):regular_ll:isobaricInhPa:level 50 Pa:fcst time 72 hrs:from 200412091200:lo res cntl fcst
        194:v-component of wind:m s**-1 (instant):regular_ll:isobaricInhPa:level 50 Pa:fcst time 72 hrs:from 200412091200:lo res cntl fcst
        199:u-component of wind:m s**-1 (instant):regular_ll:isobaricInhPa:level 10 Pa:fcst time 72 hrs:from 200412091200:lo res cntl fcst
        200:v-component of wind:m s**-1 (instant):regular_ll:isobaricInhPa:level 10 Pa:fcst time 72 hrs:from 200412091200:lo res cntl fcst
        >>> # to select key values based on a conditional expression, use a function
        >>> selected_grbs=grbs(shortName='gh',level=lambda l: l < 500 and l >= 300)
        >>> for grb in selected_grbs: grb
        14:Geopotential height:gpm (instant):regular_ll:isobaricInhPa:level 45000 Pa:fcst time 72 hrs:from 200412091200:lo res cntl fcst
        15:Geopotential height:gpm (instant):regular_ll:isobaricInhPa:level 40000 Pa:fcst time 72 hrs:from 200412091200:lo res cntl fcst
        16:Geopotential height:gpm (instant):regular_ll:isobaricInhPa:level 35000 Pa:fcst time 72 hrs:from 200412091200:lo res cntl fcst
        17:Geopotential height:gpm (instant):regular_ll:isobaricInhPa:level 30000 Pa:fcst time 72 hrs:from 200412091200:lo res cntl fcst

  `tell`()

    returns position of iterator (grib message number, 0 means iterator is positioned at beginning of file).

`pygrib.``reload`(grb)

  Recreate gribmessage object, updating all the keys to be consistent with each other. For example, if the `forecastTime` key is changed, recreating the `gribmessage` object with this function will cause the `analDate` and `verifDate` keys to be updated accordingly.

  Equivalent to `fromstring(grb.tostring())`

`pygrib.``set_definitions_path`()

  set_definition_path(ECCODES_DEFINITION_PATH)

  set path to eccodes definition files (grib tables).

`pygrib.``setdates`(grb)

  set `fcstimeunits`, `analDate` and `validDate` attributes using the `julianDay`, `forecastTime` and `indicatorOfUnitOfTimeRange` keys. Called automatically when `gribmessage` instance created, but can be called manually to update keys if one of them is modified after instance creation.

`pygrib.``tolerate_badgrib_off`()

  raise an exception when a missing or malformed key is encountered (default behavior).

`pygrib.``tolerate_badgrib_on`()

  don’t raise an exception when a missing or malformed key is encountered.