v1.1.0

What's New

• As of this release (v1.1.0), grib2io no longer includes the NCEP g2c library. grib2io now builds with an external installation of g2c, starting with g2c v1.7.0 and later. NOTE: g2c needs be built with shared-object libraries turned on.
• Functions to convert IEEE floating-point values to integers and vice-versa have been rewritten in pure Python. Previously, grib2io was using functions within g2c, which are still present but have become private to g2c. (#32)
• Added NDFD supplemental production definition tables.
• EXPERIMENTAL: Added GRIB2 backend to support lazily opening/reading GRIB2 files with xarray by @AdamSchnapp in #38

What's Changed

• Fix for seek() and Grib2Message attributes. by @eengl in #31
• Updates to IEEE int to float (and vice-versa) conversion utilities by @eengl in #32
• Updates to IEEE int to float (and vice-versa) conversion utilities by @eengl in #33
• External g2c by @eengl in #34
• Fix decoding of thresholds when set to missing. (#35)
• Fix decoding scaledValueOfSecondFixedSurface when missing. (#36)
• Clean up of Wx string decoding. MDL/NBM and NDFD use the same code to encode Wx strings in the GRIB2 Local Use Section (Section 2). grib2io.utils functions, decode_mdl_wx_strings() and decode_ndfd_wx_strings() have been replaced with new function, decode_wx_strings().

New Contributors

• @AdamSchnapp made their first contribution in #38

About xarray backend support

• grib2io's xarray backend is very experimental and only works in limited situations with GRIB2 files containing messages with a consistent vertical coordinate structure (i.e. files with variables specified on the same Isobaric surfaces).

Full Changelog: v1.0.3...v1.1.0

grib2io v1.0.3

grib2io Version v1.0.3 Release Notes

Updates:

• Updated NCEP GRIB2 tables

Big Fixes:

• Fixed issue with Grib2Message.addfield() method where kwargs was still being used instead of packing_opts. (#27)
• Fixed issue decoding MDL/NBM Wx strings stored in the GRIB2 Local Use Section. (#29)

grib2io v1.0.2

grib2io Version v1.0.2 Release Notes

• Reverted change from v1.0.1. Now checking for the potentially bad value in the grid definition template for regular and Gaussian lat/lon grids in the grib2io module. In v1.0.1, the check was occurring in g2clib Cython extension module.

grib2io v1.0.1

grib2io Version v1.0.1 Release Notes

Bug Fixes:

• Fixed bug in g2clib Cython extension module that was causing bad latitude and longitude values when generated. The bad values were limited to Regular and Gaussian Lat/Lon grids.

grib2io v1.0.0

grib2io Version v1.0.0 Release Notes

Introduction:

grib2io is a Python package that provides an interface to the NCEP GRIB2 C library (g2c) and is the successor to ncepgrib2. The grib2io module interfaces with an internal g2clib Cython module which is a wrapper to the internal v1.6.4 of the g2c library.

The following are quick descripion of features. Please see the official documentation for more detailed information.

Features:

• Support for reading and writing GRIB2 messages.

• When reading a file containing GRIB2 messages, the messages are automatically indexed for faster selection of fields by certain metadata.

• GRIB2 messages can be selected by message number, range of numbers, or by variable shortName using index notation. Messages can also be selected using the grib2io.open.select() method.

• GRIB2 message sections are unpacked by g2c library functions. The unpacked integer code values can further be decoded into plain language metadata by looking up values against NCEP GRIB2 code tables.

• NCEP GRIB2 tables are provided by grib2io as dictionaries.

• Support for the creation of new GRIB2 messages from scratch. No existing GRIB2 message is needed.

• Data compression is performed by g2clib library functions and has native support for GRIB2 Simple, Complex, and Complex with Spatial Differencing compression schemes. JPEG and PNG compression schemes are supported, but are optional and dependent upon how grib2io is built and availablility of those libraries.

• Integer data values that represent a categorical value can be mapped to the categorical defintion.

• Support for decoding NWS NDFD and MDL Wx strings.

Known Issues:

• Using decimal scaling with JPEG compression can lead to bad values packed. At this time, I cannot determine the cause.

grib2io v0.9.3

grib2io Version 0.9.3 Release Notes

New Features:

• Implementation of a wgrib2-formatted probability threshold string generated by new function, grib2io.utils.get_wgrib2_prob_string(). The string is stored in grib2io.open._index['probString']and in instances of Grib2Message as the threshold attribute. The logic for generation of the probability threshold string originates from wgrib2 source, Prob.c. (#16)

• The grib2io.open.select() method now accepts keyword arguments threshold= that accepts a wgrib2-formatted probability threshold string and percentile= that accepts a integer representing the percentile value. (#16 and #17)

• The grib2.open class __init__ method now accepts a boolean keyword argument decode= (default is True) to provide user control of whether or not to decode GRIB2 integer code values from the GRIB2 definition sections to 'plain language" metadata. (#18)

Bug Fixes:

• Fixed issue decoding probability threshold values from GRIB2 message witih product definition template numbers 4.5 and 4.9. (#15)

grib2io v0.9.2

grib2io Version 0.9.2 Release Notes

• In setup.py, added support to automatically find JPEG and PNG library and include paths when the setup.cfg and/or library-specific environment variables are not used. This will allow for JPEG and PNG compression support out-of-the-box when installed by package systems like pip. This has been tested on macOS 12 (Monterey) and Linux (Fedora, openSUSE, and Ubuntu).

• New module function, show_config(), to print information about compression support and external compression library information.

• Implementation of a wgrib2-formatted level/layer string generated by new function, grib2io.tables.get_wgrib2_level_string(). The string is stored in grib2io.open._index['levelString']and in instances of Grib2Message as the level attribute. This allows for level and layer matching. (#13)

• New table dictionary , wgrib2_level_string, containing level code values as keys. Values are a list containing formatting string given a level or layer. The contents of this table dictionary are replicated from wgrib2 source file, Level.c.

• Added new attribute, levels, to the grib2io.open class that holds a tuple of unique wgrib2-formatted level/layer strings.

grib2io v0.9.1

grib2io Version 0.9.1 Release Notes

New Features:

• Added JPEG compression support with the OpenJPEG Library. grib2io now supports building the bundled g2c library using either Jasper or OpenJPEG libs.
• Added support to select GRIB2 fields at the ground/surface level. (#12)

Bug Fixes

• Added missing Grib2Message attribute, scaledValueOfSecondFixedSurface (#11)

grib2io v0.9.0

grib2io Version 0.9.0 Release Notes

This is a minor pre-release. Alot of the code amd documentation has been cleaned up. At this release, the Python package classifier Development Status has been bumped to level 4 - Beta.

New Features:

• Added ability to write a GRIB2 Local Use Section (Section 2) to new Grib2Message objects using new Grib2Message method, addlocal(). The GRIB2 Local Use Section can contain anything you wish to put into the GRIB2 Message. (#9)

• All Grib2Message class attributes that originate from a GRIB2 metadata and link to a GRIB2 code table are now a Grib2Metadata object. This gives users the choice to work with metadata as the coded value (Grib2Metadata.value) or the definition (Grib2Metadata.definition).

• Added ability to select GRIB2 messages from grib2io.open file object via the shortName

import grib2io
g = grib2io.open('test.grib2')
msgs = g['APCP'] # Returns all GRIB2 message with shortName = 'APCP'

Class Updates:

grib2io.Grib2Message

• new method, to_bytes(), that returns the GRIB2 Message as a bytes object.

• new method, addlocal(), to add a Local Use Section (Section 2) to the new Grib2Message object. In order for this to work, a few function, grib2_addlocal() in g2clib.pyx was created to interface to the g2c function, g2_addlocal().

• updated __getitem__() to allow for key of type str.

Changes / Updates:

• Python 3.10 support

• GitPod support

• Added NCEP GRIB2 Table 4.228

grib2io release 0.8.0

Release Notes

New Features:

• Grib2Message creation from "scratch" (i.e. not read from an existing file). The logic to create a GRIB2 message remains largely the same from grib2io's predecessor, ncepgrib2. However, with grib2io, the creation of a new GRIB2 message is done through instantiation of the grib2io.Grib2Message class. When the class is instantiated with appropriate values to the keyword arguments discipline and idsect, an empty instance of Grib2Message is created. Then you call Grib2Message methods: addgrid() to add the grid definition section; addfield() to add the production definition, data representation, bitmap, and data sections; and finally end() to formally end the GRIB2 message.

• Write GRIB2 message to file. Class grib2io.open now contains a write() method that accepts a Grib2Message object.

• Decode GRIB2 messages that contain MDL (Gridded MOS) and NDFD Weather Strings. The gridded data are integer values that represent an index of a lookup table that contain weather strings. The lookup table is unique for each GRIB2 message and is stored in section 2 (Local Use Section) of each message. New functions, utils.decode_mdl_wx_strings() and utils.decode_ndfd_wx_strings() have been created to perform the decoding of the lookup tables. Different functions are required because the decoding is slightly different between MDL and NDFD. To decode weather strings while unpacking data, provide Grib2Message.data() method with the map_keys=True keyword argument.

• GRIB2 metadata attributes of the Grib2Message can now hold their coded integer value and the plain language defintion for that value. Where necessary, Grib2Message object attributes will be of type Grib2Metadata which stores the code value in value and the plain language definition in definition. See the following example using the Grib2Message.discipline:

>>> import grib2io
>>> g = grib2io.open('test.grib2')
>>> msg = g[50][0] # Get the 50th GRIB2 message
>>> type(msg.discipline)
<class 'grib2io._grib2io.Grib2Metadata'>
>>> msg.discipline.value
0
>>> msg.discipline.definition
'Meteorological Products'
>>> msg.discipline == 0
True
>>> 'Met' in msg.discipline.definition
True
>>> print(msg.discipline)
0 - Meteorological Products
>>> msg.discipline()
0

Class Updates:

grib2io.Grib2Message

• new method, unpack(). This method handles the unpacking of the binary data from the GRIB2 message and creates the GRIB2 section values.

• new method, decode(). This method performs the decoding of packed GRIB2 values from each section into metadata variables (i.e. instance variables of Grib2Message). Where available, the code values are futher deciphered into their plain language defintions. Both the code value its definition are stored as an instance of class Grib2Metadata.

• new method, addgrid(). Adds Grid Definition Section information.

• new method, addfield(). Adds the Production Definition, Data Representation, Bitmap, and Data Sections.

• new method, end(). Add the End Section. This formally terminates the packed GRIB2 message.

• updated __init__ to accommodate discipline and idsect keyword arguments (both have the default value of None). When both of these are specified and are not None, an empty Grib2Message object is created. NOTE: all other keyword arguments are ignored.

• updated data() to add map_keys keyword for decoding data values to MDL or NDFD Wx Strings.

grib2io.Grib2Metadata (NEW)

• New class to store decoded GRIB2 metadata as the coded value in instance vairable value and its plain language definition in instance variable definition.
• Class comparison methods use the value attribute. For __contains__, the definition atrribute is used. For __call__, value is returned.

Changes:

• Renamed utils.get_varname_from_table() to utils.get_varinfo_from_table().
• utils.get_table() now returns an empty dictionary when the specified table is not found.
• utils.get_value_from_table() now returns ['Unknown','Unknown','Unknown'] when a value from a table is not found.
• Updates to docstrings
• NCEP GRIB2 tables updated to latest as of 8/31/2021. Logic added to table generation scripts to remove "(See Note *)" strings.
• Included NCEP G2C Library updated to verison 1.6.2.

Bug Fixes:

• Set ONE_MB to the correct value representing 1 MB in units of bytes.
• Fixed issues with decoding metadata for GRIB2 messages with production definition template number = 9.