TCL Interface to GrADS

From OpenGrads Wiki

Tclgrads is a library of procedures for executing commands in GrADS from a Tcl script. It uses Expect to send commands to GrADS and parse its output, making available the extensive processing capabilities of Tcl to manipulate the results of the commands. In this sense, this Tcl interface to GrADS is analaogous to the Python and Perl interface to GrADS.

Tclgrads requires Expect, Tcllib, and GrADS (Version 1.9.0 or later) or any OpenGRADS release.

[edit] Downloading the software

The source tclgrads-<version>.tgz of the Tclgrads library can be downloaded from the OpenGrADS download area at SourceForge. The distribution comes with an INSTALL file that contains the installation instructions, a set of examples to illustrate the basic functionality, and with a README file that list the available procedures and their usage.

In addition there are binary packages for FreeBSD and CentOS, in tbz and rpm formats respectively, that can be installed with the native package management tools (e.g., rpm, pkg_add).

[edit] Installation

[edit] Requirements

The following are required and must be installed:

   Expect
   Tcllib
   GrADS (Version 1.9.0 or later) or any OpenGRADS release.

[edit] Installing from Packages

Binary packages exist for FreeBSD (tbz) and CentOS (rpm). Since tclgrads is written entirely in Tcl and no compilation is involved, the rpm packages should work anywhere rpm is the package management tool.

The packages, available from the SourceForge download area or the software section at noaaport.net, can be installed with the native package management tools (e.g., rpm, pkg_add):

       rpm -i tclgrads-<version>.rpm
       pkg_add tclgrads-<version>.tbz

[edit] Installation using the Makefile

This boils down to executing

       ./configure.sh
       make install-dirs
       make install

inside the tclgrads distribution directory.

[edit] Manual installation

Tclgrads is written entirely in Tcl, so there is no compilation involved. The package consists of a single file grads.tcl and the accompanying index file pkgIndex.tcl.

Perhaps the best option is to create a directory tclgrads at the same level as the tcllib directory, and put both of the above files in that directory.

The files can be saved anywhere, for example

       /usr/local/lib/tcl_site

Any script that will use the package can then add the line

       lappend auto_path "/usr/local/lib/tcl_site"

before the "package require grads" statement, and in that way the grads.tcl file will be found.

[edit] Usage

A script will typically be of the form

       #!/usr/local/bin/tclsh8.4

       package require grads;

       ::grads::init;
       ::grads::open filename;

       tcl commands

       ::grads::end;

where filename stands for a data file that GrADS knows how to read, and tcl commands for the set of Tcl commands that form the core of the script.

The tclgrads package contains two sets of procedures, in different namespaces ::grads:: and ::gradsu::, which have similar functionality but slightly different calling conventions. The complete set of procedures are listed and described in the README file mentioned above. Here we mention a few, taken from the examples that are provided with the distribution and the packages.

[edit] Examples

[edit] Example 1

Printing a contour plot of tmpprs

 grads::exec d tmpprs;
 grads::exec printim "tmpprs.png";

or a color filled plot instead

 grads::exec set gxout shaded;
 grads::exec d tmpprs;
 grads::exec printim "tmpprs.png";

[edit] Example 2

Transforming variables

 set lon -125;
 set lat 37;

 grads::transform w2gr $lon $lat gx gy;
 puts "$gx $gy";

 grads::transform gr2xy $gx $gy x y;
 puts "$x $y";

 grads::transform xy2w $x $y lon lat;
 puts "$lon $lat";

[edit] Example 3

Getting the list of variable names

 grads::get_vars vars;
 foreach v $vars {
   puts $v;
 }

[edit] Example 4

Get and output all the levels

 grads::get_levels levels;
 foreach l $levels {
   puts $l;
 }

Only the currently set level

 grads::get_levels levels -r;
 foreach l $levels {
   puts $l;
 }

Set a range and output the levels in that range

 grads::exec set z 1 10;
 grads::get_levels levels -r;
 foreach l $levels {
   puts $l;
 }

[edit] Example 5

This function can set various variables in one call

 gradsu::mset x 10 y 10 z 1 t "1 3";

The function eval_expr1 returns the list (in T) of values of tmpprs for the above range. The list of values starts with the index 0.

 grads::eval_expr1 tmpprs t T;
 foreach r $T {
   puts $r;
 }

This function is similar, but the first element of $T is the number of items while the first value of tmpprs starts at the index 1.

 gradsu::getval1 tmpprs t T;
 foreach r $T {
   puts $r;
 }

[edit] Example 6

Set the range in the xy plane

 grads::exec set x 10 14;
 grads::exec set y 11 15;

Evaluate the "tmpprs" variable at each point and print the matrix. The first commented line will store in the matrix the lon/lat coordinates along with the value of the variable at each point. The second commented line will store in the matrix the xy wind components along with the tmpprs at each point.

 grads::eval_expr_xy "tmpprs" m -r;
 # grads::eval_expr_xy "lon|lat|tmpprs" m -r;
 # grads::eval_expr_xy "tmpprs|ugrdprs|vgrdprs" m -r;

$m is now a matrix object that can be manipulated with the functions from the struct::matrix package of the tcllib.

 puts "columns = [$m columns]";
 puts "rows = [$m rows]";

 set i 0;
 while {$i < [$m rows]} {
   set row [$m get row $i];
   puts [join $row];
   incr i;
 }