Grads::Gerl implements a procedural interface to the Grid Analysis and Display System (GrADS) by means of bi-directonal pipes. It starts GrADS, sends commands to it, parses its output and return codes, and provides high level interfaces to query GrADS properties and dimension environment.

In the remainder of this document we will use Grads and Grads::Gerl to denote the Perl modules of same name, and GrADS to refer to the GrADS application that these modules interface to.

This module is based on Grads, an object oriented interface to GrADS: http://opengrads.org/doc/perl/Grads/Grads.html simply instantiates a single Grads object, and provides several functions that attempt to emulate the look and feel of the traditional GrADS application. Here is a simple example comparing the two approaches. Consider a simple script that starts GrADS, opens a file and displays a variable using Gerl:

   use Grads::Gerl;
   grads { Bin=>"gradsnc", Window=>1 };
   Open "model.nc";
   display "ua;va";
   quit;

Using the OO interface implemented in Grads this example would look like:

   use Grads;
   $ga = new Grads { Bin=>"gradsnc", Window=>1 };
   $ga->Open "model.nc";
   $ga->cmd "display "ua;va";
   $ga = undef;

These are not that different, but as the TUTORIAL secion will illustrate, Gerl's syntax is closer to the traditional GrADS command line, and provides a nice facility to evaluate a batch of GrADS commands with a convenient way of catching exceptions.

The wrapper script gadl goes a step further: it customizes the Perl Data Language (PDL) shell (perldl), automatically loading Gerl and providing a command line interface to GrADS. This combination provides a powerful and convenient environment for advanced geophysical data analysis and visualization. PDL complements GrADS quite nicely with a wealth of numerical methods and visualization tools. Here is how one would write the example above using gadl. From your OS command line you start gadl:

   % gadl -nc

Then at the gadl-> command line prompt enter

   o model.nc
   d ua;va
   q

No semi-collons, no double quotes, and even additional shortcuts such as o for ``Open''. See the COMMAND LINE FILTER FOR PDL section below for a description of all the shorthands provided by Gerl when running under perldl.

REQUIREMENTS

You must have Perl 5 and GrADS installed on your system. This module requires a version of GrADS supporting inter-process communication through the ``-u'' command line argument. This is available with GrADS Version 1.9.0 and later, not including the 1.9 beta versions. Any of the OpenGrADS variants also meet this requirement. Functions Imp and Exp, which allows GrADS to exchange data with the Perl Data Language (http://pdl.perl.org), obviously requires packages PDL and PDL::IO::FlexRaw, in addition to the GrADS user defined extension libipc. No need to install these modules if you do not intent to use these methods.

TUTORIAL

Getting started

Since Gerl is based on the Grads module you are strongly encouraged to read the documentation for that module first, in particular the tutorial.

For running this tutorial you will need a sample GrADS dataset. Please download model.nc from http://opengrads.org/sample_data. If you are new to GrADS you may want to read the Tutorial on http://grads.iges.org/grads/gadoc/tutorial.html. This document is not a GrADS tutorial but rather a tutorial of the Perl interface to GrADS.

In this example we will use the the Data::Dumper manpage module to examine the contents of hashes returned by some of the methods. So, we start by using these 2 modules:

   use  Grads::Gerl;
   use  Data::Dumper;

To start the GrADS process we use the grads function:

   $rc = grads { Bin=>"gradsnc", Window=>1 };

For this and subsequent function calls, the return code variable $rc will be zero if the command completed sucessfully and non-zero if an error occurred. Usually you would follow the command above with something like this:

   die "cannot start grads" if ( $rc );

The function ga_() is used to send generic commands to GrADS, e.g.,

   $rc = $ga "q config";

Opening files

The Open() function opens a GrADS dataset in any of the supported formats:

  $fh = Open "wrong_file.nc" or
        warn ">>> Cannot open wrong_file.nc as expected, proceeding.\n";

In this particular case we fed it a bogus file name to force an error condition. Let's try again, this time with the model.nc file that you just downloaded:

  $fh = Open "model.nc" or
    die "cannot open model.nc but it is needed for testing, aborting ";

Open() returns a file handle $fh with useful metadata about the file just read. You can use Dumper for examining the contents of $fh:

  print "\n>>> File opened: " . Dumper($fh) . "\n";

A slightly reformatted output follows:

   $fh = {
          'fid'      => '1',
          'bin'      => 'model.nc',
          'desc'     => 'model.nc',
          'title'    => '',
          'type'     => 'Gridded'
          'nvars'    => 8,
          'vars'     => [ 'ps','ts','pr','ua','va','zg','ta','hus' ],
          'var_levs' => [ '0',  '0', '0', '7', '7','7', '7', '7'   ],
          'nx'       => '72',
          'ny'       => '46',
          'nz'       => '7',
          'nt'       => '5',
        };

Basic syntax

Next we show examples of some simple grads commands. Notice how the word print is always escaped to avoid conflict with Perl's print command:

   enable 'print gerl-test.gx';
   set lev, 500;
   set x, 1;
   set gxout, shaded;

The use of commas in the previous block will come naturally to perl programmers, but may be confusing for someone coming from the classic Grads command line with no exposure to Perl. One of Perl's mottos is There is more than one way to do it (TIMTOWTDI, usually pronounced Tim Toady), and the first set command above could be written in a number of equivalent ways:

   set("lev","500');
   set(lev,500);     # this will not work is lev is defined somewhere
                     # a function name
   set("lev 500");
   set lev, 500;
   set "lev 500";
   ga_ "set lev 500";

However, the syntax

   set lev 500

does not work because the arguments of set must be specified as a list. The gadl front-end to perldl removes this restriction as it provides a command line filter to special handle GrADS commands.

Like any Perl script, flow control and variable interpolation works as usual:

   foreach $var ( ps, ta ) {
       foreach $t (1..5) {
           set t, $t;
           define tz, "ave($var,lon=0,lon=360)";
           display tz;
           draw title, "Zonal Means: $var at t=$t";
           printim "gerl-$var-$t.png";
           gaprint;  # print is already taken, so use gaprint instead
           clear;
       }
   }

Executing native GrADS commands in a here document

A unique feature of Gerl compared to its sibiling Grads is that one can enter a batch of GrADS commands in the form of a here document as in this code fragment:

   $rc = ga_ <<"EOF";
      set lev 700
      set lon 0 360
      set t 2
      d ua;va;sqrt(ua*ua+va*va)
      draw title Winds at 700 hPa
      printim gerl-winds.png
   EOF

Querying the GrADS state

These commands are sent to GrADS, one at time, and in case of a non-zero error return ga_() stops execution and returns the first non-zero error code it encounters. This feature is particularly useful to embed existing GrADS code without the need to convert to Perl syntax. (A really useful feature would be a function that evaluates code fragments from the GrADS built in scripting language.)

Like the Open() function, Query() returns a query handle with information about the particular GrADS property. Here are a few examples:

   $qh = Query "time";
   print "\n>>> Time handle: ";   print Dumper($qh);

   $qh = Query "file";
   print "\n>>> Time handle: ";   print Dumper($qh);

   $dh = Query "dims";
   print "\n>>> Dim handle: ";    print Dumper($dh);

As of this writing only a handfull of GrADS query properties are implemented by Query(), but this list is growing with each release. Be sure to contribute any extension you add. In the meantime, you can use the rword and rline functions to parse the output of native query command. Read on.

Parsing GrADS output, the traditional way

Traditionally, the built in GrADS scripting language (gs) includes functions sublin and subwrd to parse the lines and words within line of each GrADS command issued. To aid the conversion of gs scripts to Perl, we have included functions rword and rline which give access to words and lines in the GrADS output stream. The rword(i,j) function returns the j-th word in the i-th line of the GrADS command just issued, viz.

  ga_ "q config");
  for $i ( 1...$Grads::Gerl::Ga->{nLines} ) {
      printf("RWORD %3d: ", $i);
      $j=1;  # starts from 1
      while ( $word=rword($i,$j) ) {
          print $word . " ";
          $j++;
      }
      print "\n";
      $i++;
  }

To obtain a given output line, use the rline function:

  print "RLINE  *3: " . rline(3) . "\n\n";

The Set command

The Set() function is used to issue a batch of GrADS set commands, stored in an array. This is particularly useful to define a graphics context that can be reused prior to issuing each display command. Here is an example:

  my @gc;
  $Grads::Gerl::Ga->{Echo} = 1;
  push @gc, "grads off";
  push @gc, "gxout shaded";
  $rc = Set \@gc;

Interfacing to the Perl Data Language (PDL)

Function Exp allows you to export a GrAS variable into a Perl Data Language (PDL) object, commonly refered to as piddles:

   $ps = Exp ps;
   print "ps = $ps";

The output piddle ps is sometimes refered to as a GrADS field as it register a grid,

   $grid = $ps->gethdr()

which contains information about the coordinate variables (longitude, latitude, vertical level and time), in addition to low level metadata for exchanging data with GrADS. (This is the same concept of field introduced by Earth-system Modeling Framework, ESMF). Alternatively, you can explicitly grab the $grid during export,

   ($ps,$grid) = Exp ps;

You can also import a piddle with the Imp function, provided one specifies the necessary grid metadata:

   $logps = log($ps); 
   Imp logps, $logps, $grid; 
   display logps;

Of course, there is more than one way of doing this. Having a $grid you can use the piddle's sethdr() function to regsiter it:

   $logps->sethdr($grid);

and then there is no need to explicitly pass $grid to function Imp:

   $Imp logps, $logps;
   Display logps;

Given the appropriate metadata, one can also display a piddle in GrADS. If all one wants to do is to display a variable there is no need to import it first as we did above. In the previous example, you could display $logps directly:

   Display $logps;

The current implementation requires that both x and y dimensions be varying. In addition, both z and t dimensions can be varying, individually or at the same time. Just like GrADS itself, Display cannot handle both z and t varying at the same time. Here is an example exporting a 4D variable:

  ga_ "set t 1 5";
  ga_ "set z 1 7";
  $ua = Exp ua;
  print $ua->dims;

Terminating your GrADS session

To terminate your GrADS session just enter:

  quit;

This will cause a quit to be sent to GrADS which in turn will end the connection.

MAIN FUNCTIONS

Unless otherwise stated all functions returning the error code $rc behave much in the same way as a shell command. A zero $rc value means that the function completed sucessfully, while a non-zero value indicates an error condition. When a function states that it returns a reference or a list, failure will be returned as undef or an empty list.

$rc = grads ( [OPTIONS] )

This function starts the GrADS application with a bi-directional pipe so that it can send commands to the GrADS stdin and read the output from the GrADS stdout. The OPTIONS are passed in a hash like fashion, using key and value pairs. Possible options are:

Bin: The name of the GrADS binary to execute; the default is gradshdf. Enter the full path name if you need to.
Verb: Whether or not to print the return code for each GrADS command issued. Set Verb=1 to only print commands with non-zero return codes. Set Verb=2 to print the return for all commands. The default is really quiet: it does not print any return code. Along with Echo, this feature is very useful when debugging your scripts.
Echo: Whether or not to echo the GrADS stdout.
Window: Set to 1 to enable the GrADS graphics window; the default is to run GrADS in batch mode.
Port: Set to 1 to start GrADS in portrait mode; the default is to start GrADS in landscape mode.
Opts: Other options you would like to pass to the GrADS application on the command line, e.g., <Opts='-g 800x600'>>.

$rc = ga_ ( COMMAND )

Executes a generic GrADS command as one would enter on the command line. Use the rword and rline functions to parse the stdout generated by this command. Example:

   $rc = $ga_ "enable print example.gm";
   die "cannot enable print" if ( $rc );

You can also add a batch of commands in a here document:

   $rc = ga_ <<EOF
      set lev 700
      set lon 0 360
      set t 2
      d ua;va;sqrt(ua*ua+va*va)
      draw title Winds at 700 hPa
      printim gerl-winds.png
   EOF

Each command will be executed one at a time, and the return code of each examined. In case of a non-zero error condition the ofending $rc is returned and subsequent commands are not executed.

$rc = define ( VARNAME, EXPR )

This function issues a GrADS define command. These two commands are equivalent:

   define speed, 'sqrt(u*v+v*v)';
   ga_   'speed = sqrt(u*v+v*v)';

where speed is the variable name to be defined, and sqrt(u*v+v*v) is the expression defining it.

$rc = Display ( GA_EXPR | $PERL_EXPR[, GRID )

This function displays either a regular GrADS expression or a piddle expression.

For GrADS expressions, it detects such cases with varying time dimension and adds an additional carriage return in response to the anticipated user input at the end of an animation sequence.

For piddle expressions, one can specify additional metadata; see Exp below for more more information on this metadata. In fact, Display of piddle expressions is simply syntatic sugar for Imp(<display>,EXPR,GRID). These 2 statements are equivalent:

   Display $ts;
   Imp '<display>', $ts;

$x = Exp ( EXPR )

($x,$grid) = Exp ( EXPR )

This is the Export function which evaluates the GrADS expression EXPR and return an array of floating numbers $x as a Perl Data Language (http://pdl.perl.org) piddle object. This function requires the PDL::IO::FlexRaw package. In list context, the optional metadata $grid is also returned. You will need this metadata to import back into GrADS derived piddles which does not have this information stored inside. In scalar context one can retrieve $grid with the PDL gethdr function:

   $grid = $x->gethdr()

$grid contains information about the coordinate variables, as well as relevant metadada needed to exchange data with GrADS. Consult the documentation for the module Grads.pm at http://opengrads.org/doc/perl/Grads/Grads.html for addtional information on $grid.

The current implementation requires that both <x> and <y> dimensions be varying. In addition both <z> and <t> can vary as well, resulting in piddles that are 2D, 3D or 4D. For consistency with current PDL practice, the dimensions of the 3D/4D arrays are kind of strange: (nt,nz,nx,ny) instead of (nt,nz,ny,nx). This is done so that each of the horizontal (nx,ny) slices can be easily displayed in PDL with functions such as imag.

Consult the documentation for the method Exp in module Grads.pm at http://opengrads.org/doc/perl/Grads/ for addtional information on this function.

$rc = Imp ( GA_VAR, PERL_VAR, [GRID] )

This is the Import function which takes an array of floating numbers PERL_VAR, implemented as a Perl Data Language (http://pdl.perl.org) piddle object, sends it to GrADS, defining it as a GrADS variable GA_VAR. This function requires the PDL::IO::FlexRaw package.

In the current implementation, the input piddle is required to have registered a specific header with the piddle function sethdr, or you have to provide the same information through the optional parameter GRID. See function Exp above of a descriptions of the contents of GRID. This information is returned when a variable is exported from GrADS with function Exp, and this metadata can be reused during an import operation. See Exp.

$rc = gaprint ( [FILENAME] )

Issues a GrADS print command. To avoid conflict with Perl's print command we have renamed this function gaprint.

$fh = Open ( FILENAME [, FILETYPE] )

Opens a GrADS dataset in one of the supported formats, issuing a GrADS open, sdfopen or xdfopen command depending on the file type. By default, an heuristic methodxs based on the file name is used to determine the file type. Files with extension hdf and nc, or starting with http:// are assumed to be opened with sdfopen; files with extension ddf are assumed to be opened with xdfopen; all else is opened with the GrADS command open. The file name extension matching is case insensitive. The optional parameter FILETYPE, which can take the values sdf, xdf or ctl, can be used for those cases when the heuristic method fails.

This function returns $fh, a reference to hash containing the file metadata. This is the same information as returned by Query(``file''); see below for description of this hash.

$qh = Query ( PROPERTY )

This function issues the GrADS command query PROPERTY, and returns the output of this command in a reference to a hash. Consult the documentation for the module Grads.pm at http://opengrads.org/doc/perl/Grads/Grads.html for details of the properties that are currently implemented.

$rc = Set ( PROPERTIES )

This functions takes a series of arguments for the GrADS set command and execute them in sequence. On input, PROPERTIES is an array reference containing the properties to be set. Example:

  push @gc, "grads off";
  push @gc, "gxout shaded";
  $rc = $ga->Set(\@gc);

$line = rline(i)

This function returns the i-th line of the stdout generated by the last GrADS command. The number of lines available can be retrieved from the object with key nLines, e.g., $ga-{nLines}>.

$word = rword(i,j)

This function returns the j-th word within the i-th line of the stdout generated by the last GrADS command. The number of lines available can be retrieved from the object with key nLines, e.g., $ga->{nLines}.

AUTOLOADED FUNCTIONS

Perl Autoload facility allows one to define proxy functions when one is not explicitly provided; you can find more information in here http://perl.active-venture.com/pod/perltoot-autoload.html. This is very useful to make intrinsic GrADS commands appear as Perl functions. The following GrADS functions are defined by this device.

Startup functions:

These functions are all variants of the function grads, the only difference is that the default GrADS executable is the same as the name of the function.

$rc = gradsc ( [OPTIONS] )

$rc = gradsnc ( [OPTIONS] )

$rc = gradsnc4 ( [OPTIONS] )

$rc = gradshdf ( [OPTIONS] )

$rc = gradsdap ( [OPTIONS] )

$rc = gradsdods ( [OPTIONS] )

GrADS commands:

The following GrADS commands are exported by Gerl. Consult the GrADS documentation at http://grads.iges.org/grads/gadoc/index.html for a detailed description of what these commands do.

$rc = c

Same as clear.

$rc = clear

Clears the screen.

$rc = d ( [EXPR] )

Same as display.

$rc = display ( [EXPR] )

Display a GrADS expression.

$rc = disable ( [ARGUMENTS] )

Disables GrADS features such as metafile printing.

$rc = draw ( [ARGUMENTS] )

Draw titles, buttons and other graphic objects.

$rc = enable ( [ARGUMENTS] )

Enables GrADS features such as metafile printing.

$rc = printim ( [ARGUMENTS] )

Prints images.

$rc = run ( [ARGUMENTS] )

Runs a native GrADS script.

$rc = set ( [ARGUMENTS] )

Sets all kinds of GrADS parameters.

$rc = sdfopen ( [ARGUMENTS] )

Opens a self-describing file (SDF); these are usually NetCDF or HDF files.

$rc = query ( [ARGUMENTS] )

Queries the GrADS internal state.

$rc = q ( [ARGUMENTS] )

Same as query.

$rc = quit

Terminates GrADS, closing files, graphical window, etc.

$rc = xdfopen ( [ARGUMENTS] )

Alternative version of sdfopen where a data descriptor file is used supplement or overwrite metadata in a self-describing file.

COMMAND LINE FILTER FOR PDL SHELL

The program perldl is a simple shell (written in Perl) for interactive use of the Perl Data Language (PDL). Perl/PDL commands can simply be typed in, and it can support command line editing with a history mechanism. The perldl shell also allows user defined command line filters where user input can be pre-processed and properly escaped as needed. We explore this feature to give GrADS users familiar with the classic ga-> command line a familiar look-and-feel when using perldl.

When used under perldl this module automatically defines a command line filter that enables the following shortcuts:

: o - replaced with Open
: pi - replaced with printim
: pr - replaced with gaprint
: r - replaced with run
: s - replaced with ga_ set
: . - replaced with ga_

In addition, it detects GrADS commands and properly escape then so that you can type

   gadl> s lev 500

without the need for commas and double quotes. The wrapper script gadl starts perldl, automatically loading Gerl and this command line filter.

Example:

   gadl-> o model
   gadl-> s gxout shaded
   gadl-> d ua;va
   gadl-> draw title Hello, World!
   gadl-> printim

Notice that the default prompt perldl >> has been changed to gadl- >>.

TO DO

: Complete implementation of the Query function.
: Implement in Perl a native GrADS script (gs) interpreter, or perhaps a just a translator.

BUGS

: On some systems it hangs when the name of an invalid GrADS executable is provided.
: Under PerlDL, any attempt to read from stdin from within GrADS will fail, including the pull function in gs scripts and the request for CR after an animation sequence is displayed.

AUTHOR

Arlindo da Silva <dasilva@opengrads.org>

COPYRIGHT

Grads::Gerl - Procedural Interface to the GrADS Client Class