GrADS Utilities: gribmap

## gribmap

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.

### Syntax

`gribmap [options]` Command line `options` are:
`-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 -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.

### Usage Notes

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.

### Example

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.