grib2.gex - GrADS v1.9 Extensions for Reading Grib-2 Files

- NAME
- SYNOPSIS

- GrADS Commands:
- GrADS Function:

- DESCRIPTION

- GFS Example
- Using Lats4d to Convert Grib-2 to NetCDF, HDF, Grib-1 and Binary

- COMMANDS PROVIDED

- % CMD
- g2_exec CMD
- g2_open FILENAME
- g2_repl STRING
- g2_verb [ON|OFF]

- FUNCTION PROVIDED

- display g2 ( VAR )

- REQUIREMENTS
- USAGE UNDER MICROSOFT WINDOWS
- IMPLEMENTATION
- BUGS
- SEE ALSO
- AUTHOR
- COPYRIGHT

# NAME

grib2.gex - GrADS v1.9 Extensions for Reading Grib-2 Files

# SYNOPSIS

### GrADS Commands:

  g2_exec CMD - Replaces var with `g2(var)` and runs CMD

  g2_open FILENAME - Opens a Grib-2 file

  g2_repl STRING - Replaces var with `g2(var)`

  g2_verb [ON|OFF] - Toggles verbose

### GrADS Function:

  display g2(var) - Returns a Grib-2 variable

  define `var` = g2(var)

# DESCRIPTION

This library of GrADS extensions implements functions to enable GrADS v1.9.0-rc1 and later to read Grib-2 files. This is not a native implementation of Grib-2 in GrADS v1.9 but rather an extension function that allows you to read in Grib-2.

Because this is not a native implementation of Grib-2 in GrADS v1.9, you need to use function `g2` to access variables. However, the user defined command `g2_exec` (by default aliased to simply `%`) automatically replaces `var` with `g2(var)` before executing the command.

## GFS Example

Let's say you download a Grib-2 file called `gfs.t00z.pgrb2bf00` which has been produced by NCEP's Global Forecasting System (GFS). Your first step is to create a Grib-2 Descriptor File, similar to the usual GrADS ctl file. This is accomplished with utility `g2gdf.pl` which is provided with this extension:

       % g2gdf.pl -v gfs.t00z.pgrb2bf00

This command will create 2 new files:

- Descriptor file:

  gfs.t00z.pgrb2bf00.gdf

- Inventory file:

  gfs.t00z.pgrb2bf00.inv

These are the only ancillary files that you need; the usual index file produced by utility `gribmap` is not necessary. (You can also use templates in `g2gdf`.) So, you just fire up GrADS and do some plotting:

     % gradsc -l
     ga-> g2_open gfs.t00z.pgrb2bf00.gdf
     ga-> set lev 525
     ga-> d g2(HGTprs)
     Contouring: 4500 to 5500 interval 100

Notice the use of command `g2_open` and function `g2()`. This is essential, if you try to display the variable directly you will get all undefined values:

     ga-> d HGTprs
     Cannot contour grid - all undefined values

As a short hand, you can use the user defined command `g2_exec` (or its short-hand `%`) to replace `var` with `g2(var)` begore executing the

     ga-> % d HGTprs
     d g2(HGTprs)

Notice that you can use the regular `query` command to list the contents of a file opened with `g2_open`:

     ga-> q file
     File 1 : gfs.t00z.pgrb2bf00
      Descriptor: gfs.t00z.pgrb2bf00.gdf
      Binary: gfs.t00z.pgrb2bf00___
      Type = Gridded
      Xsize = 720  Ysize = 361  Zsize = 37  Tsize = 1
      Number of Variables = 95
        cnwatsfc 0 2 ** surface none Plant Canopy Surface Water [kg/m^2]
        duvbsfc 0 0 ** surface ave UV-B downward solar flux [W/m^2]
        hgt0pv 0 0 ** PV=5e-07 (Km^2/kg/s) surface none Geopotential Height [gpm]
        hgt1pv 0 0 ** PV=1e-06 (Km^2/kg/s) surface none Geopotential Height [gpm]
        hgt2pv 0 0 ** PV=1.5e-06 (Km^2/kg/s) surface none Geopotential Height [gpm]
        ...

You can also use the regular `close` command when you no longer need this file.

## Using Lats4d to Convert Grib-2 to NetCDF, HDF, Grib-1 and Binary

This extention can be used together with `lats4d.gs` to slice, dice and convert your Grib-2 file to any of the support output formats in GrADS v1.9. For example, a NetCDF file with just a few variables on selected levels can be produced with the following command:

     % lats4d.sh -nc -i gfs.t00z.pgrb2bf00.gdf -o gfs.t00z.pgrb2bf00    -vars ugrdprs vgrdprs tmpprs hgtprs    -levs 875 825 775 725 675 625 575 525 475 425 375 325 275 225 175 125    -func "g2(@)" -v

See the Lats4d documentation for additional details.

# COMMANDS PROVIDED

## % CMD

Same as g2_exec.

## g2_exec CMD

This command replaces each occurence of any `variable` (from the DEFAULT file) in CMD with `g2(variable)` and then executes the command. Example:

       ga-> g2_exec display sqrt(ugrdprs*ugrdprs+vgrdprs*vgridprs)
       display sqrt(g2(ugrdprs)*g2(ugrdprs)+g2(vgrdprs)*g2(vgrdprs))

## g2_open FILENAME

This command opens a Grib-2 Descriptor File created with the `g2gdf.pl` utility.

## g2_repl STRING

This command replaces each occurence of any `variable` (from the DEFAULT file) in STRING with `g2(variable)` and prints the result to the screen. Example:

       ga-> g2_repl sqrt(ugrdprs*ugrdprs+vgrdprs*vgridprs)
       sqrt(g2(ugrdprs)*g2(ugrdprs)+g2(vgrdprs)*g2(vgrdprs))

## g2_verb [ON|OFF]

This command toggles verbose ON/OFF.If no argument is provided it will toggle the verbose mode ON or OFF.

# FUNCTION PROVIDED

## display g2 ( VAR )

This function returns the variable VAR from the Grib-2 file, according to the current dimension environment. As of this writing, you cannot specify dimension information as part of the file name. For example,

     ga-> display g2(HGTprs(z=4))

will NOT work.

# REQUIREMENTS

You must have GrADS v1.9.0-rc1 or later, and the `g2ctl.pl` and `wgrib2` installed and available on your PATH.

# USAGE UNDER MICROSOFT WINDOWS

This extension requires two Perl scripts: `g2gdf.pl` and `g2ctl.pl`. The Win32 Superpack ships with compiled versions of these scripts (`g2gdf.exe` and `g2ctl.exe`), so you do not need to have `perl` installed on your system. (These executables were prepared with module `PAR::Packer` build on Cygwin from modules on CPAN). If you would like to work with the Perl version of the scripts (say you need to modify them), then you are strongly advised to use `perl` that comes with Cygwin. Using native Win32 builds such as Active State Perl can be made to work, but the resulting `.gdf` and `.inv` text files may need to be converted with utility `dos2unix`.

There are two versions of `wgrib2` for MS Windows on the OpenGrADS download area at SourceForge: a win32 and a cygwin version. You want to use the Cygwin version with this extension. The Win32 Superpack ships with the correct version of `wgrib2`.

# IMPLEMENTATION

This is a relatively simple minded implementation. All the heavy lifting is done by Wes Ebisuzaki's `wgrib2` utility through a regular pipe (using the `popen()` function in C). If you would like to see the actual `wgrib2` command being executed just turn on verbosity

     ga-> g2_verb on

# BUGS

It would be nice to override the dimension with additional arguments to function `g2()`.

# SEE ALSO

- http://opengrads.org/ - OpenGrADS Home Page

- http://www.iges.org/grads/ - Official GrADS Home Page

- http://opengrads.org/doc/udxt/grib2/g2gdf.html - The Grib-2 Descriptor File utility

- http://www.cpc.ncep.noaa.gov/products/wesley/wgrib2/ - Wes Ebisuzaki's (and many co-authors) excellent `wgrib2` utility

- http://www.cpc.ncep.noaa.gov/products/wesley/g2ctl.html - Wes Ebisuzaki's (and many co-authors) excellent `g2ctl` utility for creating GrADS descriptor files for Grib-2 files.

# AUTHOR

Arlindo da Silva (dasilva@opengrads.org)

# COPYRIGHT

Copyright (C) 2008 Arlindo da Silva; All Rights Reserved.

This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

grib2.gex - GrADS v1.9 Extensions for Reading Grib-2 Files