http://www.renci.org/~bblanton/files/ReadGrib/read_grib.html

read_grib r4 (16 April 2012)

A WMO GRiB file reader for MATLAB

CONTACT:brian_blanton@renci.org
LAST MODIFIED: 16 Apr 2012

 

read_grib is a World Meteorological Organization (WMO) GRiB file reader.

READ_GRIB is now being used by numerous people at a wide variety of places. Alerts users at the following locations have found bugs that I've created, suggested improvements, and provided testing of READ_GRIB. Many thanks.

NOAA	Universita di Genova e della Basilicata
Uni. of Miami	Nanjing Institute of Meteorology, China
Uni. of Wisconsin Space Science and Engineering	Universidad de Concepcion
Uni. of Virginia ENVI-SCI	Universities of Innsbruck
Boeing Aircraft	GKSS Forschungszentrum Institute for Coastal Research
Colorado State	University of Kiel Leibniz Institute of Marine Sciences
C-CORE Consulting	energy & meteo systems GmbH
Weather Services International (WSI), Inc.	School of Environmental Sciences University of East Anglia
M.I.T.	RPS Kirk McClure Morton
University of Southampton, UK	Maurice Lamontagne Institute Peches et Oceans Canada
University of Quebec	School of Engineering University of Edinburgh

READ_GRIB reads WMO international exchange GRiB formatted data files into MATLAB. It has various input modes, including extraction of individial GRiB records by record number, extraction by parameter name (which is not unique), and generating an inventory of the GRiB file contents. It has been tested on the following standard model output files: AVN, ETA, RUC, ECMWF, and WAM. The default GRiB parameter table used is the NCEP Operational table.

Version 1.4.0 is a bug fix for Version 1.3.1 It repairs a memory leak in the code that unpacks the Binary Data Segment. This bug was hidden in V1.3.1 and prior under MATLAB R13 and less. But it became fatal in R14. The memory needed for BDS_unpack is now handled according to R14 requirements.

Version 1.3.1 was a bug fix a problem in handling the HeaderFlag varargin. Version 1.3 adds flexible user-defined parameter tables, with NCEP operational and reanalysis and ECMWF 128 and 160 tables built in. Varargins have been added to the READ_GRIB interface to simplify calls. The functionality is more complete than V1.2.

Calls to READ_GRIB now look like:

  >> grib_struct=read_grib(gribname,irec,'HeaderFlag',0,'ParamTable','ECMWF128');

DOWNLOAD the read_grib.m V1.4.0 tar file.

INSTALLATION: The tar file contents untar into the directory read_grib1.4.0. The files can be left here and the path to read_grib be included in the startup.m file. It might be a good idea to make a soft link from read_grib1.4.0 to read_grib, and put the directory "read_grib" in the MATLABPATH.

COMPILATION: The decoding of the binary sections of the GRiB records uses c-code written by Wesley Ebisuzaki . Click here for GRiB format documentation. There is now only 1 mex file, written in c, that needs to be compiled. Fire up MATLAB in the read_grib directory and type the following: >> mex BDS_unpack_mex5.c All should go well. This code is known to work on Linux, DEC-alpha, IBM, SGI, and MACs!!!. The code is standard, and should work on most other platforms. Binaries for MAC OS X and GLX are shipped with the distribution.

TUTORIAL

The calling syntax for READ_GRIB is:

   grib_struct=read_grib(gribname,irec,p1,v1,p2,v2,...)

The first 2 arguments are required:

• gribname - filename containing GRiB records.
• irec - specifies which GRiB records to read. If irec is a vector, it specifies which GRiB records to return. If irec is a scalar, is specifies how far to read into the GRiB file. If irec==-1, READ_GRIB reads all records(default). Irec can be a cell array of parameter names to extract. Type read_grib('paramtable') for a list of parameter names. Irec can also be the string 'inv{entory}', so that READ_GRIB prints a GRiB contents list.

READ_GRIB accepts the following property/value pairs:

• HeaderFlag - (0|1) report only headers if==1 (default=1).
  no data structures are returned unless DataFlag==1.
• DataFlag - (0|1) return decoded BDS if==1 (default=1).
  The data for the parameter is stored in the .fltarray field of the structure.
• ScreenDiag - (0|1) control diagnostics to screen (default=1)
• ParamTable - ('NCEPOPER'|'NCEPREAN'|'ECMWF128'|'ECMWF160') selects the parameter
  table to use for matching kpds6 number to the correct parameter
  name. (default='NCEPOPER')

Additional help comments can be obtained by passing one argument to READ_GRIB.
Try: 'mainhelp','paramtableshort','paramtablelong','output_struct'.

READ_GRIB outputs a MATLAB structure containing the GRiB contents for the requested records. Call read_grib('output_struct') for a better description.

Examples: Assume the existence of a GRiB file that contains a few records from the NCEP operational ETA model. This file is called eta.grb.

• To get an inventory of the grib,

  >> grib_struct=read_grib('eta.grb','inv');
  

  
  
• To extract (decode) the first and third records in the grib,

  >> grib_struct=read_grib('eta.grb',[1 3])               
  Searching for first GRIB marker...
  GRiB Record marker "GRIB" found at chars 1-4
  GRiB header = 
  GRIB
  GRec=   1 : FPos1=       4 : GLen=   29412 : FPos2=   29412 : EOGRiB=7777 ***
  GRec=   2 : FPos1=   29412 : GLen=   20388 : FPos2=   49800 : EOGRiB=7777
  GRec=   3 : FPos1=   49800 : GLen=   20388 : FPos2=   70188 : EOGRiB=7777 ***
  GRec=   4 : FPos1=   70188 : GLen=   36180 : FPos2=  106368 : EOGRiB=7777
  
  grib_struct = 
  
  1x2 struct array with fields:
      sec1_1
      lengrib
      edition
      file
      record
      description
      parameter
      units
      level
      gridtype
      pds
      gds
      bms
      bds
      fltarray
  

  The decoded records are in the .fltarray fields of the 1x2 grib_struct structure. The parameter names are in the .parameter fields of the grib_struct:

  >> {grib_struct(1:2).parameter}
  
      'PRES [SFC]'    'VGRD []'
  
  

  The times of the parameters in the GRiB are in the .pds fields of the grib_struct:

  >> grib_struct(1).pds          
  
  ans = 
  
                  len: 28
                  PTV: 2
                   IC: 'NCEP (WMC)'
            GenProcID: 80
               GridID: 255
               HASGDS: 1
               HASBMS: 0
            parameter: 'PRES'
                units: 'Pa'
          description: 'Pressure '
                layer: '1 - Surface [SFC]'
              h_p_etc: [2x1 double]
                 year: 92
                month: 12
                  day: 13
                 hour: 0
                  min: 0
      fcast_time_unit: 'hour'
                   P1: 0
                   P2: 6
                  TRI: 'N/A'
                TRI_N: 0
         TRI_Nmissing: 0
              century: 20
               SubCID: 1
                DecSF: -1
              pdsvals: [28x1 double]
  

  
  
• To extract all records in the grib,

  >> grib_struct=read_grib('eta.grb',-1);