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

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:

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

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