1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
|
<!--Copyright (C) 1988-2005 by the Institute of Global Environment and Society (IGES). See file COPYRIGHT for more information.-->
<style type="text/css">
<!--
.style1 {color: #009900}
.style3 {color: #006666}
.style4 {color: #CC6633}
.style5 {color: #9900FF}
.style6 {color: #FF0000}
.style9 {color: #FF6666}
.style10 {color: #FF9900}
.style13 {color: #3300FF}
.style15 {color: #993300}
body {
background-color: #e0f0ff;
}
-->
</style>
<h2>Handling GRIB in GrADS</h2>
<h4>
<a href="#what">What is GRIB?</a><br>
<a href="#handling">How to read GRIB data with GrADS</a><br>
<a href="#example">An Example</a><br>
<a href="#grib2">Comments on GRIB2</a><br />
<a href="#summary">Summary</a><br>
</h4>
<hr>
<h3><br>
</h3>
<h3>Introduction</h3>
One of the most powerful features of GrADS is its ability to work
directly with GRIB data, versions 1 and 2. Grads version 2.0 is required to handle GRIB2. The interfaces for GRIB and GRIB2 are similar, but not identical -- they are treated as separate data types. This documentation page will attempt to provide the required understanding to use
GRIB data in GrADS.
</ul>
<p>
<a name="what">
<h3>What is GRIB?</h3>
</a>
<p>GRIB (General Regularly-distributed Information in Binary form) is an international, public, binary format
for the efficient storage of meteorological/oceanographic
variables and the metadata that describe them. GRIB2 is similar to GRIB, but has a more complex set of header fields for the metadata, and also offers data compression that can significantly reduce file size. A GRIB data file typically consists of a collection of records. Each GRIB record contains a 2-D
(lon,lat) grid of data at a particular time and vertical level. A 4-D GRIB data set is a collection of 2-D records that span a range of times and vertical levels. GRIB2 records may also contain ensemble information, creating a 5-D data set. A GRIB record is a self-describing data object -- each record contains not only the data, but also the metadata to describe the spatial grid, the valid time, the vertical level, and any ensemble metadata (for GRIB2 only). GRIB records may be concatenated together to form a single data set, but because each record is self-describing, the order in which they may be merged is arbitrary.</p>
<p>
<a name="handling">
<h3>How to read GRIB data with GrADS </h3>
</a>
<p>In order to display GRIB data in GrADS, the collection of records must be sorted and placed into the internal 4- or 5-D gridded data model. This is accomplished by the use of a GrADS data descriptor file and a separate index file, which maps the position of the GRIB records in the data file into their proper place in the 4- or 5-D grid environment. The general idea is to scan through the metadata in all the records, collecting information about the lat/lon grid, the list of vertical levels at which the records are defined, the list of times at which the records are valid, and (if GRIB2) any ensemble information. The next step is to create a descriptor file which describes the complete grid and the list of variables. The final step is to create the index file by running gribmap, which takes the name of your descriptor file as an argument. The name of the index file that gribmap creates is included in the descriptor file in the INDEX entry. Once you have created a descriptor file and run gribmap, you are ready to open the descriptor file with GrADS and begin displaying the data. </p>
<p>The scanning of the metadata in each record is done by the several external utilities: <a href="gradutilgribscan.html">gribscan</a> and <a href="gradutilgrib2scan.html">grib2scan</a> (which are supported by COLA, as part of GrADS) and <a href="http://www.cpc.ncep.noaa.gov/products/wesley/wgrib.html" target="_parent">wgrib</a> and <a href="http://www.cpc.ncep.noaa.gov/products/wesley/wgrib2/" target="_parent">wgrib2</a> (which are supported by Wesley Ebisuzaki at NOAA). The scanning utilities will give you the information you need to describe the 4- or 5-D grid in your descriptor file, so you can manually create the XDEF, YDEF, ZDEF, TDEF, and EDEF (if ensembles are present) entries, plus the list of variable declarations, with the appropriate codes in the levels and units fields to describe each variable uniquely. If you don't feel up to doing all that work manually, there are two user-friendly routines that do all the scanning and create a descriptor file for you: <a href="http://www.cpc.ncep.noaa.gov/products/wesley/grib2ctl.html" target="_parent">grib2ctl</a> and <a href="http://www.cpc.ncep.noaa.gov/products/wesley/g2ctl.html" target="_parent">g2ctl</a> (also supported by Wesley Ebisuzaki at NOAA). </p>
<p><a name="example" id="example"></a></p>
<h3>An Example (for GRIB1)</h3>
<code>
# wgrib <a href="sample.grib">sample.grib</a> <br />
1:0:d=<span class="style5">04040200</span>:<span class="style1">UGRD</span>:kpds5=<span class="style1">33</span>:kpds6=<span class="style13">100</span>:kpds7=<span class="style4">1000</span>:TR=10:P1=0:P2=0:TimeU=1:1000 mb:<span class="style6">anl</span>:NAve=0<br />
2:81534:d=<span class="style5">04040200</span>:<span class="style3">VGRD</span>:kpds5=<span class="style3">34</span>:kpds6=<span class="style13">100</span>:kpds7=<span class="style4">1000</span>:TR=10:P1=0:P2=0:TimeU=1:1000 mb:<span class="style6">anl</span>:NAve=0<br />
3:154922:d=<span class="style5">04040200</span>:<span class="style1">UGRD</span>:kpds5=<span class="style1">33</span>:kpds6=<span class="style13">100</span>:kpds7=<span class="style4">850</span>:TR=10:P1=0:P2=0:TimeU=1:850 mb:<span class="style6">anl</span>:NAve=0<br />
4:236456:d=<span class="style5">04040200</span>:<span class="style3">VGRD</span>:kpds5=<span class="style3">34</span>:kpds6=<span class="style13">100</span>:kpds7=<span class="style4">850</span>:TR=10:P1=0:P2=0:TimeU=1:850 mb:<span class="style6">anl</span>:NAve=0<br />
5:317990:d=<span class="style5">04040200</span>:<span class="style1">UGRD</span>:kpds5=<span class="style1">33</span>:kpds6=<span class="style13">100</span>:kpds7=<span class="style4">500</span>:TR=10:P1=0:P2=0:TimeU=1:500 mb:<span class="style6">anl</span>:NAve=0<br />
6:399524:d=<span class="style5">04040200</span>:<span class="style3">VGRD</span>:kpds5=<span class="style3">34</span>:kpds6=<span class="style13">100</span>:kpds7=<span class="style4">500</span>:TR=10:P1=0:P2=0:TimeU=1:500 mb:<span class="style6">anl</span>:NAve=0<br />
7:489202:d=<span class="style5">04040200</span>:<span class="style1">UGRD</span>:kpds5=<span class="style1">33</span>:kpds6=<span class="style13">100</span>:kpds7=<span class="style4">200</span>:TR=10:P1=0:P2=0:TimeU=1:200 mb:<span class="style6">anl</span>:NAve=0<br />
8:578880:d=<span class="style5">04040200</span>:<span class="style3">VGRD</span>:kpds5=<span class="style3">34</span>:kpds6=<span class="style13">100</span>:kpds7=<span class="style4">200</span>:TR=10:P1=0:P2=0:TimeU=1:200 mb:<span class="style6">anl</span>:NAve=0<br />
9:660414:d=<span class="style5">04040200</span>:<span class="style1">UGRD</span>:kpds5=<span class="style1">33</span>:kpds6=<span class="style13">100</span>:kpds7=<span class="style4">1000</span>:TR=10:P1=0:P2=6:TimeU=1:1000 mb:<span class="style9">6hr fcst</span>:NAve=0<br />
10:741948:d=<span class="style5">04040200</span>:<span class="style3">VGRD</span>:kpds5=<span class="style3">34</span>:kpds6=<span class="style13">100</span>:kpds7=<span class="style4">1000</span>:TR=10:P1=0:P2=6:TimeU=1:1000 mb:<span class="style9">6hr fcst</span>:NAve=0<br />
11:815336:d=<span class="style5">04040200</span>:<span class="style1">UGRD</span>:kpds5=<span class="style1">33</span>:kpds6=<span class="style13">100</span>:kpds7=<span class="style4">850</span>:TR=10:P1=0:P2=6:TimeU=1:850 mb:<span class="style9">6hr fcst</span>:NAve=0<br />
12:896870:d=<span class="style5">04040200</span>:<span class="style3">VGRD</span>:kpds5=<span class="style3">34</span>:kpds6=<span class="style13">100</span>:kpds7=<span class="style4">850</span>:TR=10:P1=0:P2=6:TimeU=1:850 mb:<span class="style9">6hr fcst</span>:NAve=0<br />
13:978404:d=<span class="style5">04040200</span>:<span class="style1">UGRD</span>:kpds5=<span class="style1">33</span>:kpds6=<span class="style13">100</span>:kpds7=<span class="style4">500</span>:TR=10:P1=0:P2=6:TimeU=1:500 mb:<span class="style9">6hr fcst</span>:NAve=0<br />
14:1059938:d=<span class="style5">04040200</span>:<span class="style3">VGRD</span>:kpds5=<span class="style3">34</span>:kpds6=<span class="style13">100</span>:kpds7=<span class="style4">500</span>:TR=10:P1=0:P2=6:TimeU=1:500 mb:<span class="style9">6hr fcst</span>:NAve=0<br />
15:1141472:d=<span class="style5">04040200</span>:<span class="style1">UGRD</span>:kpds5=<span class="style1">33</span>:kpds6=<span class="style13">100</span>:kpds7=<span class="style4">200</span>:TR=10:P1=0:P2=6:TimeU=1:200 mb:<span class="style9">6hr fcst</span>:NAve=0<br />
16:1231150:d=<span class="style5">04040200</span>:<span class="style3">VGRD</span>:kpds5=<span class="style3">34</span>:kpds6=<span class="style13">100</span>:kpds7=<span class="style4">200</span>:TR=10:P1=0:P2=6:TimeU=1:200 mb:<span class="style9">6hr fcst</span>:NAve=0<br />
17:1312684:d=<span class="style5">04040200</span>:<span class="style1">UGRD</span>:kpds5=<span class="style1">33</span>:kpds6=<span class="style13">100</span>:kpds7=<span class="style4">1000</span>:TR=10:P1=0:P2=12:TimeU=1:1000 mb:<span class="style10">12hr fcst</span>:NAve=0<br />
18:1394218:d=<span class="style5">04040200</span>:<span class="style3">VGRD</span>:kpds5=<span class="style3">34</span>:kpds6=<span class="style13">100</span>:kpds7=<span class="style4">1000</span>:TR=10:P1=0:P2=12:TimeU=1:1000 mb:<span class="style10">12hr fcst</span>:NAve=0<br />
19:1467606:d=<span class="style5">04040200</span>:<span class="style1">UGRD</span>:kpds5=<span class="style1">33</span>:kpds6=<span class="style13">100</span>:kpds7=<span class="style4">850</span>:TR=10:P1=0:P2=12:TimeU=1:850 mb:<span class="style10">12hr fcst</span>:NAve=0<br />
20:1549140:d=<span class="style5">04040200</span>:<span class="style3">VGRD</span>:kpds5=<span class="style3">34</span>:kpds6=<span class="style13">100</span>:kpds7=<span class="style4">850</span>:TR=10:P1=0:P2=12:TimeU=1:850 mb:<span class="style10">12hr fcst</span>:NAve=0<br />
21:1630674:d=<span class="style5">04040200</span>:<span class="style1">UGRD</span>:kpds5=<span class="style1">33</span>:kpds6=<span class="style13">100</span>:kpds7=<span class="style4">500</span>:TR=10:P1=0:P2=12:TimeU=1:500 mb:<span class="style10">12hr fcst</span>:NAve=0<br />
22:1712208:d=<span class="style5">04040200</span>:<span class="style3">VGRD</span>:kpds5=<span class="style3">34</span>:kpds6=<span class="style13">100</span>:kpds7=<span class="style4">500</span>:TR=10:P1=0:P2=12:TimeU=1:500 mb:<span class="style10">12hr fcst</span>:NAve=0<br />
23:1793742:d=<span class="style5">04040200</span>:<span class="style1">UGRD</span>:kpds5=<span class="style1">33</span>:kpds6=<span class="style13">100</span>:kpds7=<span class="style4">200</span>:TR=10:P1=0:P2=12:TimeU=1:200 mb:<span class="style10">12hr fcst</span>:NAve=0<br />
24:1883420:d=<span class="style5">04040200</span>:<span class="style3">VGRD</span>:kpds5=<span class="style3">34</span>:kpds6=<span class="style13">100</span>:kpds7=<span class="style4">200</span>:TR=10:P1=0:P2=12:TimeU=1:200 mb:<span class="style10">12hr fcst</span>:NAve=0
</code>
<p>The wgrib output reveals that the sample.grib file contains 24 records. There are two variables: <span class="style1">UGRD</span> and <span class="style3">VGRD</span>; there are four pressure levels: <span class="style4">1000</span>, <span class="style4">850</span>, <span class="style4">500</span>, and <span class="style4">200</span>; there are three times: <span class="style6">00hr analysis</span>, <span class="style9">6hr forecast</span>, and <span class="style10">12hr forecast</span>, with the initial reference time of 00z 2 April 2004 ("<span class="style5">04040200</span>"). We still need to know about the lon/lat grid, so we use wgrib again, this time with the verbose option (-V) and just for the first record (-d 1). We are assuming that all the records in the file share the same lon/lat grid, but this may not necessarily be the case.
<p>
<code>
# wgrib -V -d 1 sample.grib<br />
rec 1:0:date 2004040200 UGRD kpds5=33 kpds6=100 kpds7=1000 levels=(3,232) grid=3 1000 mb anl:<br />
UGRD=u wind [m/s]<br />
timerange 10 P1 0 P2 0 TimeU 1 nx 360 ny 181 GDS grid 0 num_in_ave 0 missing 0<br />
center 7 subcenter 0 process 81 Table 2<br />
latlon: lat 90.000000 to -90.000000 by 1.000000 nxny 65160<br />
long 0.000000 to -1.000000 by 1.000000, (<span class="style15">360</span> x <span class="style15">181</span>) scan 0 mode 128 bdsgrid 1<br />
min/max data -24.8 29.3 num bits 10 BDS_Ref -248 DecScale 1 BinScale 0
</code>
<p>Now we can use this information to put together the descriptor file (<a href="sample.ctl">sample.ctl</a>):
<p> <code>
dset ^sample.grib<br />
index ^sample.idx<br />
title sample grib file<br />
dtype grib <br />
options yrev<br />undef 9.999E+20<br />
XDEF <span class="style15">360</span> linear 0.0 1.0<br />
YDEF <span class="style15">181</span> linear -90.0 1<br />
ZDEF 4 levels 1000 850 500 200<br />
TDEF 3 linear 00Z02apr2004 6hr<br />
VARS 2<br />
u 4 <span class="style1">33</span>,<span class="style13">100</span> u wind [m/s]<br />v 4 <span class="style3">34</span>,<span class="style13">100</span> v wind [m/s]<br />
ENDVARS
</code>
<p>Notes: <br />
The name of the index file name can be anything at all, here we choose a filename similar to the data file, but with a .idx extension. The options yrev is needed because the grid is written from north to south (90 to -90), but the GrADS default is the opposite, so we need to tell GrADS to turn the grid upside down. For GRIB, the undef value is arbitrary, but required by GrADS. The XDEF and YDEF entries are based on the info from the verbose wgrib output. The ZDEF and TDEF entries are based on the level and time info from wgrib: 4 pressure levels, and 3 time steps with a 6-hour increment. In the variable declarations, the numbers in the units field (<span class="style1">33</span>,<span class="style13">100</span> and <span class="style3">34</span>,<span class="style13">100</span>) are the grib codes that appear in the kpds5 and kpds6 fields of the wgrib output. These are the codes that identify the variable and the level type; the kpds7 field give the level values, which in this case are the pressure levels. The name of the variable is arbitrary -- it is a good practice to keep is short but meaningful. </p>
<p>The final step is to run gribmap to create the index file. Gribmap looks at the metadata in each and every record in the GRIB file and compares it to the information in the descriptor file. If the record contains a variable at a vertical level at a time that fits into the grid described by the descriptor file, then it is declared a "MATCH" and a the file position of that record is recorded: </p>
<p><code>
# gribmap -v -i sample.ctl <br />
grib1map: opening GRIB file: sample.grib <br />
!!!!! MATCH: 1 81534 0 3 1 0 33 100 1000 79 0 btim: 2004040200:00 tau: 0 dtim: 2004040200:00<br/>
!!!!! MATCH: 2 154922 0 3 1 0 34 100 1000 81613 0 btim: 2004040200:00 tau: 0 dtim: 2004040200:00<br/>
!!!!! MATCH: 3 236456 0 3 1 0 33 100 850 155001 0 btim: 2004040200:00 tau: 0 dtim: 2004040200:00<br/>
!!!!! MATCH: 4 317990 0 3 1 0 34 100 850 236535 0 btim: 2004040200:00 tau: 0 dtim: 2004040200:00<br/>
!!!!! MATCH: 5 399524 0 3 1 0 33 100 500 318069 0 btim: 2004040200:00 tau: 0 dtim: 2004040200:00<br/>
!!!!! MATCH: 6 489202 0 3 1 0 34 100 500 399603 0 btim: 2004040200:00 tau: 0 dtim: 2004040200:00<br/>
!!!!! MATCH: 7 578880 0 3 1 0 33 100 200 489281 0 btim: 2004040200:00 tau: 0 dtim: 2004040200:00<br/>
!!!!! MATCH: 8 660414 0 3 1 0 34 100 200 578959 0 btim: 2004040200:00 tau: 0 dtim: 2004040200:00<br/>
!!!!! MATCH: 9 741948 0 3 1 0 33 100 1000 660493 0 btim: 2004040200:00 tau: 6 dtim: 2004040206:00<br/>
!!!!! MATCH: 10 815336 0 3 1 0 34 100 1000 742027 0 btim: 2004040200:00 tau: 6 dtim: 2004040206:00<br/>
!!!!! MATCH: 11 896870 0 3 1 0 33 100 850 815415 0 btim: 2004040200:00 tau: 6 dtim: 2004040206:00<br/>
!!!!! MATCH: 12 978404 0 3 1 0 34 100 850 896949 0 btim: 2004040200:00 tau: 6 dtim: 2004040206:00<br/>
!!!!! MATCH: 13 1059938 0 3 1 0 33 100 500 978483 0 btim: 2004040200:00 tau: 6 dtim: 2004040206:00<br/>
!!!!! MATCH: 14 1141472 0 3 1 0 34 100 500 1060017 0 btim: 2004040200:00 tau: 6 dtim: 2004040206:00<br/>
!!!!! MATCH: 15 1231150 0 3 1 0 33 100 200 1141551 0 btim: 2004040200:00 tau: 6 dtim: 2004040206:00<br/>
!!!!! MATCH: 16 1312684 0 3 1 0 34 100 200 1231229 0 btim: 2004040200:00 tau: 6 dtim: 2004040206:00<br/>
!!!!! MATCH: 17 1394218 0 3 1 0 33 100 1000 1312763 0 btim: 2004040200:00 tau: 12 dtim: 2004040212:00<br/>
!!!!! MATCH: 18 1467606 0 3 1 0 34 100 1000 1394297 0 btim: 2004040200:00 tau: 12 dtim: 2004040212:00<br/>
!!!!! MATCH: 19 1549140 0 3 1 0 33 100 850 1467685 0 btim: 2004040200:00 tau: 12 dtim: 2004040212:00<br/>
!!!!! MATCH: 20 1630674 0 3 1 0 34 100 850 1549219 0 btim: 2004040200:00 tau: 12 dtim: 2004040212:00<br/>
!!!!! MATCH: 21 1712208 0 3 1 0 33 100 500 1630753 0 btim: 2004040200:00 tau: 12 dtim: 2004040212:00<br/>
!!!!! MATCH: 22 1793742 0 3 1 0 34 100 500 1712287 0 btim: 2004040200:00 tau: 12 dtim: 2004040212:00<br/>
!!!!! MATCH: 23 1883420 0 3 1 0 33 100 200 1793821 0 btim: 2004040200:00 tau: 12 dtim: 2004040212:00<br/>
!!!!! MATCH: 24 1973098 0 3 1 0 34 100 200 1883499 0 btim: 2004040200:00 tau: 12 dtim: 2004040212:00<br/>
grib1map: reached end of files<br/>
grib1map: writing the map...
</code></p>
<p>
Success! Each record in the GRIB file has been mapped
to a variable, level, and time in the descriptor file. Note that failure to match will not lead to an error in GrADS; if a grib record at a particular time or level is missing, GrADS will return a grid
with "undefined" values on display.
<p><a name="grib2" id="grib2"></a>
<h3>Comments on GRIB2</h3>
<p>The procedure for handling GRIB2 in GrADS is essentially the same as it is for GRIB1. However, GRIB2 is treated as a separate data type, so you need to change the DTYPE entry in your descriptor file. There are some keywords for the OPTIONS entry that are only valid for GRIB2 (e.g. "pascals"), and the "yrev" option is not necessary with GRIB2, since the north-south orientation of the grid is contained in the header metadata, so GrADS can figure that one out on its own. In addition, the GRIB2 codes required in the variable declarations are much more numerous -- please see the reference page on <a href="descriptorfile.html">descriptor file elements</a> for details on variable declarations for GRIB2. The <a href="gradutilgrib2scan.html">grib2scan</a> utility may also be helpful in determining what the grib codes should be, as well as the output from gribmap (with the verbose option enabled "-v"). For GRIB2 ensemble data sets, the required ensemble codes are included in the <a href="gradutilgrib2scan.html">grib2scan</a> and gribmap output.
<p><a name="summary" id="summary"></a>
<h3>
Summary<br>
</h3>
<ol>
<li>Scan the GRIB files (with <a href="http://www.cpc.ncep.noaa.gov/products/wesley/wgrib.html" target="_parent">wgrib</a> / <a href="http://www.cpc.ncep.noaa.gov/products/wesley/wgrib2/" target="_parent">wgrib2</a> / <a href="gradutilgribscan.html">gribscan</a> / <a href="gradutilgrib2scan.html">grib2scan</a>) to see what's in them.
<li>Construct a descriptor file manually (or use <a href="http://www.cpc.ncep.noaa.gov/products/wesley/grib2ctl.html" target="_parent">grib2ctl</a> / <a href="http://www.cpc.ncep.noaa.gov/products/wesley/g2ctl.html" target="_parent">g2ctl</a>).
<li>Run <a href="gradutilgribmap.html">gribmap</a> in
verbose
mode (<code>-v</code>) to map the GRIB records to the 4- or 5-D grid
structure in the descriptor file and create the index file.
</ol>
The work required for step #2 is not necessarily easy. But the advantage of reading GRIB data directly without converting it to another format is worth the effort.
The output from grib2ctl / g2ctl may be a good first guess for your descriptor file that will need some tweaking (by examinging the wgrib output) to make sure you match every record. Of course, there's also the option to describe only those variables (or levels) that are of interest to you, in which case you are not required to match every record.
|
