An example of using the GRIB helper routines

Earlier I posted some higher-level routines, built on IDL’s GRIB API, for accessing data in a GRIB edition 1 or 2 file. I’d like to show an example of using them. In this example, I downloaded NCEP HiResWindow model data from the NOAA Operational Model Archive and Distribution System (NOMADS). The files I selected are the 18 UTC 2011-11-01 run for Alaska and contain 6-hour ensemble mean forecast data valid at 00 UTC 2011-11-02. I extracted 250 mb u- and v-wind component records from the data file using my GRIB_GET_RECORD routine and visualized the wind speeds as an image using the native map projection of the data. Here’s a screenshot of the result from my Linux box: Grab the example code and data from here and after the break I’ll explain how I read the records from the GRIB file and used them to make this visualization. Here’s a listing of the downloaded files on my machine:

[mpiper@asimov: data]$ ll ak.t18z.pgrb.mean.f06.grib2*
-rw-r--r-- 1 2.6M 2011-11-02 10:47 ak.t18z.pgrb.mean.f06.grib2
-rw-r--r-- 1 1.3K 2011-11-02 10:46 ak.t18z.pgrb.mean.f06.grib2.idx

The .idx file is particularly helpful because it contains an overview of the contents of the GRIB file:

[mpiper@asimov: data]$ cat ak.t18z.pgrb.mean.f06.grib2.idx
1:0:d=2011110118:UGRD:10 m above ground:6 hour fcst:wt ens-mean
2:159298:d=2011110118:VGRD:10 m above ground:6 hour fcst:wt ens-mean
3:322845:d=2011110118:UGRD:850 mb:6 hour fcst:wt ens-mean
4:472128:d=2011110118:UGRD:250 mb:6 hour fcst:wt ens-mean
5:583822:d=2011110118:VGRD:850 mb:6 hour fcst:wt ens-mean
6:737490:d=2011110118:VGRD:250 mb:6 hour fcst:wt ens-mean
7:850175:d=2011110118:MSLET:mean sea level:6 hour fcst:wt ens-mean
8:1053159:d=2011110118:HGT:500 mb:6 hour fcst:wt ens-mean
9:1202189:d=2011110118:RH:850 mb:6 hour fcst:wt ens-mean
10:1327929:d=2011110118:RH:2 m above ground:6 hour fcst:wt ens-mean
11:1452894:d=2011110118:TMP:850 mb:6 hour fcst:wt ens-mean
12:1573011:d=2011110118:TMP:500 mb:6 hour fcst:wt ens-mean
13:1665046:d=2011110118:TMP:250 mb:6 hour fcst:wt ens-mean
14:1753998:d=2011110118:TMP:2 m above ground:6 hour fcst:wt ens-mean
15:1918370:d=2011110118:CAPE:surface:6 hour fcst:wt ens-mean
16:2028476:d=2011110118:CIN:surface:6 hour fcst:wt ens-mean
17:2059862:d=2011110118:APCP:surface:0-6 hour acc fcst:wt ens-mean
18:2147351:d=2011110118:APCP:surface:3-6 hour acc fcst:wt ens-mean
19:2222796:d=2011110118:WIND:10 m above ground:6 hour fcst:wt ens-mean
20:2388294:d=2011110118:WIND:850 mb:6 hour fcst:wt ens-mean
21:2542921:d=2011110118:WIND:250 mb:6 hour fcst:wt ens-mean

This index file is the output from the invaluable wgrib2 utility with the "-s" option set. (If I didn't have this index file, my first step would be to make an equivalent with wgrib2.) Each line corresponds to a record in the GRIB file, with the index of the record listed first. I can use my helper routine GRIB_GET_PARAMETERNAMES to get the names of the parameters used the file:

IDL> f = '/home/mpiper/projects/GRIB/data/ak.t18z.pgrb.mean.f06.grib2'
IDL> p = grib_get_parameternames(f)
IDL> print, p
u-component of wind  v-component of wind  u-component of wind  u-component of wind
v-component of wind  v-component of wind  192 Geopotential height  Relative humidity
Relative humidity  Temperature  Temperature  Temperature  Temperature
Convective available potential energy  Convective inhibition  Total precipitation
Total precipitation  Wind speed  Wind speed  Wind speed

Some of the parameter names are repeated (e.g., Temperature is listed four times); by comparing with the index file, these correspond to data at different heights in the atmosphere. In this example, I'd like to use the modeled u- and v-component winds at 250 mb. From the index file and the output from GRIB_GET_PARAMETERNAMES, I see that these are stored in records 4 and 6. I can use GRIB_GET_RECORD to extract these data from the file:

IDL> r_u250 = grib_get_record(f, 4, /structure)
IDL> r_v250 = grib_get_record(f, 6, /structure)

GRIB_GET_RECORD returns a structure variable holding the contents of the specified record from the file (the keys in the record are mapped to the fields of the structure). For example, the name of the record, its units, the pressure level of the data and the number of data values can be accessed with these statements:

IDL> print, r_u250.parametername
u-component of wind
IDL> print, r_u250.parameterunits
m s-1
IDL> print, r_u250.level, r_u250.pressureunits
         250hPa
IDL> print, r_u250.numberofvalues
      497475

The record's data are always included in the VALUES field of the structure returned by GRIB_GET_RECORD:

IDL> help, r_u250.values
    DOUBLE    = Array[825, 603]

These data (along with 'r_v250') are used in the program NG_ALASKA_WINDS included in the example. Look over the code in this program to see how I used the information in the GRIB file to set up a map projection in IDL and visualize the data. If you have any questions, let me know in the comments!