Grads - GrADS Client Class

CONSTRUCTOR

new Grads ( [OPTIONS] )

METHODS

$rc = cmd ( COMMAND )
$rc = Display ( GA_EXPR | $PERL_EXPR[, GRID )
$x = Exp ( EXPR )
($x,$grid) = Exp ( EXPR )

Exchange metadata $meta

$rc = Imp ( GA_VAR, PERL_VAR, [GRID] )
$fh = Open ( FILENAME [, FILETYPE] )
$qh = Query ( PROPERTY )

$qh = Query ( file # )
$qh = Query ( dims )
$qh = Query ( time )
$qh = Query ( gr2w I J )
$qh = Query ( xy2w X Y )
$qh = Query ( pp2xy X Y )
$qh = Query ( gr2xy I J )
$qh = Query ( w2xy LON LAT )
$qh = Query ( xy2gr X Y )
$qh = Query ( w2gr LON LAT )
Note:

$rc = Set ( PROPERTIES )
$line = rline(i)
$word = rword(i,j)

TO DO
BUGS
SEE ALSO
AUTHOR
COPYRIGHT

NAME

Grads - GrADS Client Class

SYNOPSIS

: use Gerl;
: $ga = new Grads ( [OPTIONS] );
: $rc = $ga->cmd ( COMMAND );
: $rc = Display ( GA_EXPR | $PERL_EXPR[, GRID )
: $x = $ga->Exp ( EXPR );
: ($x,$grid) = $ga->Exp ( EXPR );
: $rc = $ga->Imp ( GA_VAR, PERL_VAR, [GRID] )
: $fh = $ga->Open ( FILENAME [, FILETYPE] );
: $qh = $ga->Query ( PROPERTY );
: $rc = $ga->Set ( PROPERTIES );
: $ln = $ga->rline(i);
: $wd = $ga->rword(i,j);

DESCRIPTION

Grads is a class implementing an 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. The companion module http://opengrads.org/doc/perl/Gerl/ provides a procedural interface to this module, with the look and feel of a traditional GrADS script.

In the remainder of this document we will use Grads to mean this Perl class, and GrADS to refer to the GrADS application that this class interfaces to.

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. Methods 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

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;
   use  Data::Dumper;

Let's create a Grads object by starting the gradsnc binary in landscape mode, with an active graphics window:

   $ga = new Grads { Bin=>"gradsnc", Port=>0, Window=>1, };

The cmd method is used to send generic commands to GrADS, e.g.,

   $rc = $ga->cmd("q config");

The return code $rc will be 0 if all went well, and non-zero if the particular GrADS command exited with an error.

Opening files

The Open method opens a GrADS dataset in any of the supported formats:

  $fh = $ga->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 = $ga->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',
        };

Querying the GrADS state

Similarly, the Query method returns a query handle with information about the particular GrADS property. Here are a few examples:

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

  $fh = $ga->Query("file");
  print "\n>>> File handle: ";   print Dumper($fh);

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

As of this writing only a handfull of GrADS query properties are implemented by the Query method, 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 methods 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 methods rword and rline which give access to words and lines in the GrADS output stream. The rword(i,j) method returns the j-th word in the i-th line of the GrADS command just issued, viz.

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

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

  print "RLINE  *3: " . $ga->rline(3) . "\n\n";

The Set method

The Set method 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;
  $ga->{Echo} = 1;
  push @gc, "grads off";
  push @gc, "gxout shaded";
  $rc = $ga->Set(\@gc);

Interfacing to the Perl Data Language (PDL)

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

   $ps = $ga->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) = $ga->Exp ps;

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

   $logps = log($ps); 
   $rc = $ga->Imp logps, $logps, $grid; 
   $rc = $ga->display logps;

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

   $logps->sethdr($grid);

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

   $rc = $ga->Imp logps, $logps;
   $rc = $ga->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:

   $rc = $ga->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->cmd "set t 1 5";
  $ga->cmd "set z 1 7";
  $ua = Exp ua;
  print $ua->dims;

Terminating your GrADS session

As usual in perl, the Grads destructor will be invoked when the object gets out of scope of when it is explitly undefined like this:

  $ga = undef;

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

CONSTRUCTOR

new `Grads` ( [OPTIONS] )

This is the constructor for a new Grads object. It 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'>>.

METHODS

Unless otherwise stated all methods returning the error code $rc behave much in the same way as a shell command. A zero $rc value means that the method completed sucessfully, while a non-zero value indicates an error condition. When a method states that it returns a reference or a list, failure will be returned as undef or an empty list. In describing the methods below we sometimes omit the object reference for notational simplicity.

$rc = cmd ( COMMAND )

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

   $rc = $ga->cmd "enable print example.gm";
   die "cannot enable print" if ( $rc );

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

This method 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:

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

$x = Exp ( EXPR )

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

This is the Export method 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 method 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 method:

   $grid = $x->gethdr()

$grid contains information about the coordinate variables, as well as relevant metadada needed to exchange data with GrADS. The $grid is returned as a reference to a hash defining the following keys:

name: Usually the same as the GrADS expression being evaluated
meta: Metadata used during data exchange with GrADS as described below; the dimension of this piddle is related to the dimension of the main data piddle $x.
denv: A hash with the current dimension environment as returned by Query("dims")
dims: A perl array with the name of the piddle dimensions, e.g., ['time', 'lev', 'lon', 'lat']. The size of this array is the same as the rank of $x.
time: Perl array containing time strings such as 12Z01jan1987
lev: 1D piddle with a vertical levels
lat: 1D piddle with latitudes
lon: 1D piddle with longitudes

Exchange metadata `$meta`

The size of the last dimension of the exchange metadata $meta is 20, corresponding to the following float numbers:


       1:  Undefined value for the grid
       2:  i dimension (idim).  Dimensions are:
           -1 - None
            0 - X dimension (lon)
            1 - Y dimension (lat)
            2 - Z dimension (lev)
            3 - T dimension (time)
       3:  j dimension (jdim).  Note:  if idim and
           jdim are -1, the grid is a single value.
           If jdim is -1, the grid is a 1-D grid.
       4:  number of elements in the i direction (isiz)
       5:  number of elements in the j direction (jsiz)
           Array is dimensioned (isiz,jsiz).
       6:  i direction linear flag.  If 0, the
           i dimension has non-linear scaling.
       7:  j dimension linear flag.
       8:  istrt.  This is the world coordinate value
           of the first i dimension, ONLY if the i dimension
           has linear scaling and the i dimension is not
           time.
       9:  iincr.  Increment in the i dimension of the
           world coordinate.  ONLY if the i dimension has
           linear scaling.
       10: jstrt.  World coordinate of the first j
           dimension, only if the j dimension has linear
           scaling, and the j dimension is not time.
       11: jincr.  World coordinate increment for j
           dimension.
       12: If one of the dimensions is time, values
           12 to 16 are defined as the start time
           12 is the start year.
       13: start month
       14: start day
       15: start hour
       16: start minute
       17: Values 17 and 18 contain the time increment
           for the time dimension.  17 contains the
           increment in minutes.
       18: increment in months.  (GrADS handles all
           increments in terms of minutes and months).
       19,20: reserved

Additional information about this metadata can be found on the documentation fot libipc, a library of GrADS extensions used to implement the data exchange with GrADS.

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

This is the Import method 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 method requires the PDL::IO::FlexRaw package.

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

$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 method 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 method returns $fh, a reference to a 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 method issues the GrADS command query PROPERTY, and returns the output of this command in a reference to a hash. The following properties are currently implemented:

$qh = Query ( `file #` )

Returns information about the file number #. If the file number is ommitted the default file is used. The following keys are defined in the output hash:

fid: The file Id number
title: The title of the dataset
desc: The description of the dataset
bin: The binary file name
type: File type
nx: Number of longitudinal points
ny: Number of latitudinal points
nz: Number of vertical levels
nt: Number of times on file
nvars: Number of variables on file
vars: Array with variable list
var_levs: Array with number of levels for each variable

$qh = Query ( `dims` )

Returns information about the dimension environment. The following keys are defined in the output hash:

dfile: Default file number
x_state: x-coordinate state: fixed or varying
lon: longitudinal range
x: x-index range
y_state: y-coordinate state: fixed or varying
lat: latitudinal range
y: y-index range
z_state: z-coordinate state: fixed or varying
lev: level range
z: z-index range
t_state: time-coordinate state: fixed or varying
time: time range
t: t-index range

$qh = Query ( `time` )

Returns information on the current time coordinate. The following keys are defined in the output hash:

time: time string
dd: 2 digit day, e.g., 12
day: day of the week, e.g., Tue
hh: 2 digit hour in the range 0...23
nn: 2 digit seconds
mmm: 3 letter month, e.g., Jan
mm: 2 digit month, e.g., 01
yyyy: 4 digit year, e.g., 2007

$qh = Query ( `gr2w I J` )

Converts grid to world coordinates. The following keys are defined in the output hash:

Lon: Longitude
Lat: Latitude

$qh = Query ( `xy2w X Y` )

Converts screen to world coordinates. The following keys are defined in the output hash:

Lon: Longitude
Lat: Latitude

$qh = Query ( `pp2xy X Y` )

Converts virtual page to real page coordinates. The following keys are defined in the output hash:

X: x-coordinate
Y: y-coordinate

$qh = Query ( `gr2xy I J` )

Converts grid to real page coordinates. The following keys are defined in the output hash:

X: x-coordinate
Y: y-coordinate

$qh = Query ( `w2xy LON LAT` )

Converts world to real page coordinates. The following keys are defined in the output hash:

X: x-coordinate
Y: y-coordinate

$qh = Query ( `xy2gr X Y` )

Converts real page to grid coordinates. The following keys are defined in the output hash:

I: x-coordinate in index space; noice that I is a float point number
J: y-coordinate in index space; noice that J is a float point number

$qh = Query ( `w2gr LON LAT` )

Converts world to grid coordinates. The following keys are defined in the output hash:

I: x-coordinate in index space; noice that I is a float point number
J: y-coordinate in index space; noice that J is a float point number

Note:

Eventually all the query properties will be implemented.

$rc = Set ( PROPERTIES )

This methods 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 method 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 method 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}.

TO DO

: Complete implementation of the Query method.
: Remove requirement of varying x/y dimensions during Imp/Exp.

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. For animation, the workaround is to use method Display which automatially includes an extra carriage return to avoid locking up.
: Sometimes the output buffer may get messed up, particularly when an error occurs during data exchange with PDL.

AUTHOR

Arlindo da Silva <dasilva@opengrads.org>

COPYRIGHT

Grads - GrADS Client Class

$qh = Query ( dims )

$qh = Query ( time )

$qh = Query ( `dims` )

$qh = Query ( `time` )