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.

pygrib.get_definitions_path()

return eccodes_definitions_path currently in use.

If empty, then definitions installed with linked eccodes lib are begin used.

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