The GrADS data descriptor file defines a grid structure into which the data will fit -- it gives "shape" to the data by identifying its spatial dimensions, the number of time steps, and the number of variables.
If the data is in binary format, its structure has already been
prescribed. If the data is in GRIB format, no consistent
relationship exists between the data and the grid structure defined in the data
descriptor file. Hence, the need for the gribmap utility which "maps"
between the GRIB data and the GrADS data description.
As gribmap reads each field in the GRIB data file, the
parameters for that field (e.g. variable name, vertical level, time)
are compared to the information in the data descriptor file until
a match is found. The process continues until all the GRIB elements have been
"mapped" to their location within the GrADS grid structure. Please read the documentation on Handling GRIB in GrADS for more details.
Command line |
|
-0 |
Ignores the forecast time when setting up a match, so that the base time is the valid time. |
-b |
Valid time for averages is set to be the beginning of the period rather than
the end. Default valid time is the end of the averaging period. |
-big |
(GrADS version 2.0.a8+) Required option if the GRIB1 or GRIB2 files are > 2 Gb. This option creates a bigger index file, which cannot be read by earlier versions of GrADS. |
-e |
Ignores extra bytes (that are not part of the GRIB1 msg) at end of file. Some ECMWF GRIB files require this option because
of blocking.
Using the -E option ignores extra bytes in middle and/or end of GRIB file. |
-f hr |
Matches only those grib records whose forecast time is hr hours. This is used to isolate a sequence of forecasts. For example, if you
wanted to sample all the 120-hour forecasts from the MRF ensemble runs, you
would use gribmap -f120. |
-h num |
Skips over num bytes before starting the scan process. |
-help |
Prints out the list of options |
-i fname |
fname is the name of the data descriptor file. If
not specified, gribmap will prompt the user. |
-m |
Use base time from descriptor file instead of GRIB header. This option only works with GRIB1. |
-min0 |
Ignores the minutes code. |
-N |
Does NOT write out the index file. |
-new |
(GrADS version 2.1.a2+) Creates a new version of an existing index file |
-old |
(GrADS version 2.1.a2+) Creates an old version of an existing index file |
-q |
Quiet mode -- suppresses all messages except for errors. Default is off. |
-s num |
Skips over no more than num bytes between records. The
default is 1000. |
-t0 |
Matches only those grib records whose base time is the same as the initial time in the data descriptor file. This is used to pull out a forecast sequence (0, 12, 24, ... , 72 hours) starting a specific time. |
-u |
Updates existing index file when expanding the size of the T or E dimensions in a templated data set. Only one dimension may be expanded at a time. This option was temporarily disabled in GrADS version 2.0.*, but is back in version 2.1.a2. (See Usage Notes and Examples below.) |
-v |
Verbose mode -- detailed output makes it easier to verify what is being mapped. Default is off. |
Over the many years of GrADS development, the contents of the index file created by gribmap have changed only a few times. Although it is not present in the user interface, there is a version number associated with the index file. When the contents of the index are different and the version has been upgraded, you will get an error message when trying to read that file with an older version of GrADS. Index files created with gribmap version 2.1.a2+ have a new version number and therefore they can only be read by GrADS version 2.1.a2+. If you need to use an older version of GrADS to open a dataset with an index file created by gribmap version 2.1.a2+, you must first reformat the metadata in the index file by running gribmap again with the -old option.
The -old option (introduced with GrADS version 2.1.a2) allows you to downgrade the version of an index file so that it may be read by any version of GrADS. The -old option does not re-scan the GRIB files, it merely alters the metadata in the index file's header to match the old version. There are some cases when the -old option cannot be used: an index file that was created with the -big option cannot be downgraded with -old because that would require a change to the format of the data in the index file, not just the metadata in the index file's header.
The -u option was disabled in version 2.0* because of the introduction of the E dimension, but has been restored in version 2.1.a2, so that now both the T and E dimensions can be updated. The EDEF and TDEF entries must be updated separately -- only one dimension can be expanded at a time. Reviving the update feature necessitated a change to the metadata in the index file's header, so the index version has changed with GrADS 2.1.a2.
If you have an old index file that you would like to update, first use the -new option to rewrite the index file with the additional metadata. The -new option does not re-scan the GRIB files, it merely upgrades the metadata in the index file's header.
Suppose you have an existing GRIB dataset (a reanalysis) that needs to have its time axis extended. To use the update feature without having to re-scan all files, follow these steps:
1. Do not alter the descriptor file (yet). Run gribmap -new to upgrade the metadata in the index file and change the index version.
2. Edit the descriptor file to expand the TDEF size. Do not change the name of the file in the INDEX entry.
3. Run gribmap -u with the edited descriptor file.
4. Run gribmap -old to downgrade the metadata in the new index file.
Step #4 is optional, but it allows older versions of GrADS to read the updated data file. Without step #4, only the newest version of GrADS (2.1.a2+) will be able to open the updated descriptor file.