TclGempak
TclGempak is a library of procedures for executing Gempak programs from Tcl scripts, thus making available the extensive processing capabilities of Tcl to manipulate the input to those programs. The library currently supports
gpfront, gpmap, sfcntr, sflist, sfmap, gdcntr, gdstream, gdwind, gdplot, gdplot2, gdinfo, gdmap
This document contains installation instructions, as well as some example scripts and their corresponding output to illustrate its usage.
Requirements
In addition to Tcl, TclGempak requires Tcllib but it has no further requirements apart from Gempak itself.
Downloading the software
The source ``tclgempak-version.tgz'' of the tclgempak library can be downloaded from the software area of this site 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 lists the available procedures and their usage.
In addition there are binary packages for FreeBSD, CentOS and Debian, in tbz, rpm and deb formats respectively, that can be installed with the native package management tools (e.g., pkg_add, rpm, dpkg).
Installation
Requirements
The following are required and must be installed:
Tcl
Tcllib
Gempak
Installing from Packages
Binary packages exist for FreeBSD (tbz), CentOS (rpm) and Debian (deb). Since tclgempak 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 software section, can be installed with the native package management tools:
pkg_add tclgempak-version.tbz
rpm -i tclgempak-version.rpm
dpkg -i tclgempak-version.deb
Installation using the Makefile
This boils down to executing
./configure.sh
make install-dirs
make installinside the tclgempak distribution directory.
Manual installation
TclGempak is written entirely in Tcl, so there is no compilation involved. The package consists of single file ``gempak.tcl'' and the accompanying index file ``pkgIndex.tcl''.
Perhaps the best option is to create a directory ``tclgempak'' 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_siteAny script that will use the package can then add the lines
lappend auto_path "/usr/local/lib/tcl_site" package require gempakand it will be found.
Usage
A script will typically be of the form
#!/usr/local/bin/tclsh8.4 package require gempak; gempak::define asfil "latest.fronts"; gempak::define device "gif|fronts.gif"; gempak::define garea "us"; gempak::init gpfront; gempak::run; gempak::end;
If such scripts are executed from a terminal, the user must have sourced one of the Gemenviron files (depending on the user's shell). Alternatively, if Nbsp is installed, the following line can be added at the top of the script
source /usr/local/etc/nbsp/gempak.envto load the environment variables. The advantage of the latter approach is that the scripts can be run in the background as well. A copy of the gempak.env file is included in the documentation directory of the tclgempak package.
The complete set of procedures contained in the package are listed and described in the README file mentioned above, and here we mention a few, taken from the examples that are provided with the distribution and the packages.
NOTE
As of Nbsp-2.0, the TclGempak library is included in the Nbsp package and therefore there is no need to install it separately as instructed above. However, to use it, the scripts must set the auto_path variable properly so that the library is found. Specifically, the scripts must contain the instructions
lappend auto_path "/usr/local/libexec/nbsp" package require gempak
Examples
In the examples below, only the relevant portion of the scripts is shown. See the examples subdirectory for the corresponding output files.
Example 1
To produce a radar image from a given data file
set nidsdir "/var/noaaport/data/digatmos/nexrad/nids/jua/n0r"; set datafile [file join $nidsdir "n0rjua_20090114_2048.nids"]; gempak::define radfil $datafile; gempak::define proj "rad"; gempak::define device "gif|n0rjua.gif"; gempak::define garea "dset"; gempak::init gpmap; gempak::run; gempak::end;
Example 2
Same thing, but specifying the parts of the device and map parameters separately, and using the ``latest'' file.
set nidsdir "/var/noaaport/data/digatmos/nexrad/nids";
set site "jua";
set type "n0r";
set datafile [file join $nidsdir $site $type "latest"];
gempak::define radfil $datafile;
gempak::define proj "rad";
gempak::define garea "dset";
gempak::device_device "gif";
gempak::device_name ${type}${site}.gif;
gempak::device_size 1024 768;
gempak::set_device;
gempak::map_color 1;
gempak::map_dash 7;
gempak::set_map;
gempak::init gpmap;
gempak::run;
gempak::end;
Example 3
Adding these lines anywhere before the call to ``gempak::init gpmap'' above, will draw the color bar:
gempak::imcbar_color 5; gempak::imcbar_orientation "V"; gempak::imcbar_anchor "LL"; gempak::imcbar_xy 0.05 0.1 gempak::imcbar_lengthwidth 0.5 0.1; gempak::imcbar_frequency 1; gempak::set_imcbar;
Example 4
These lines will add a selected set of city names
gempak::stnplt_text_color 5; gempak::stnplt_text_size 1; gempak::stnplt_marker_color 3; gempak::stnplt_marker_type 12; gempak::stnplt_marker_size 1.25; gempak::stnplt_marker_width 2; gempak::stnplt_stnfile_name \ "/usr/local/etc/nbsp/defaults/gpmap/rad/radmap-cities.tbl"; gempak::set_stnplt;
Example 5
The tclgempak equivalent of the Gempak parameter settings
is the following:\$mapfil = county + cities map = = 1//2 + 2//3
gempak::mapfil "county" "cities"; # first one gempak::map_color 1; gempak::map_width 2; gempak::set_map # second one gempak::map_color 2; gempak::map_width 3; gempak::append_map
Notice in particular the absence of the ``\, $, +, /'' symbols in the parameter specification. In general the tclgempak functions have keywords in their names to help recognize their use.
Example 6
This is the classic example for drawing a stereographic projection of the Northern Hemisphere.
gempak::define map 1; gempak::define proj "str/90;-80;0"; gempak::define garea "-10;-130;-10;50"; #gempak::define latlon "2/10/1/1/10;10"; gempak::latlon_color 2; gempak::latlon_linetype 10; gempak::latlon_linewidth 1; gempak::latlon_freq 1 1; gempak::latlon_incr 10 10; gempak::set_latlon; gempak::device_device "gif"; gempak::device_name "latlon.gif"; gempak::set_device;
Example 7
This will draw the latest watch/warn areas.
gempak::define device "gif|wwa.gif"; gempak::define garea "us"; gempak::define wstm "last"; gempak::define warn "last"; gempak::define watch "last"; gempak::define wcn "last"; gempak::define wcp "last"; gempak::init gpmap; gempak::run; gempak::end;
Example 8
A more sophisticated version of the above, to draw the outlines of the latest watch/warn areas.
gempak::define device "gif|wwa.gif";
::gempak::garea_lat1 15;
::gempak::garea_lon1 -125
::gempak::garea_lat2 50
::gempak::garea_lon2 -60;
::gempak::set_garea;
::gempak::latlon_color 1;
::gempak::latlon_linetype 10;
::gempak::latlon_linewidth 1;
::gempak::latlon_freq 15 15;
::gempak::set_latlon;
::gempak::wstm_end_time {last};
::gempak::wstm_outline_flag {yes};
::gempak::wstm_outline_width_warn {1};
::gempak::wstm_outline_width_watch {1};
::gempak::wstm_outline_width_advisory {1};
::gempak::set_wstm;
gempak::init gpmap;
gempak::run;
gempak::end;
Example 9
This will draw the latest fronts, and shows how to define the ``garea'' by specifying independently the corner points.
set datafile "/var/noaaport/data/digatmos/nwx/hpc/fronts/latest.front"; gempak::define asfil $datafile; gempak::define device "gif|fronts.gif"; gempak::garea_lat1 15; gempak::garea_lon1 -125; gempak::garea_lat2 50; gempak::garea_lon2 -60; gempak::set_garea; gempak::init gpfront; gempak::run; gempak::end;
This example also shows once more the general rule that the tclgempak functions have keywords in their names that indicate what they set or do.
Example 10
Besides gpmap an gpfront, the library can be used with the sfmap and sfcntr programs. This examples uses sfmap to make a plot of the ``skyc'' and ``tmpf'' variables.
# Find the current file in the surface data directory set surfacedir [file join $env(GEMDATA) "surface"]; set now [expr [clock seconds]]; set sffile_name [clock format $now -format "%Y%m%d" -gmt true]; append sffile_name "_sao.gem"; set sffile [file join $surfacedir $sffile_name]; # main gempak::define sffile $sffile gempak::define device "gif|sfmap.gif"; gempak::define garea "15;-125;50;-60"; gempak::define area "garea"; gempak::define dattim "last"; gempak::define sfparm "skyc;tmpf" gempak::define colors "26;2"; gempak::init sfmap; gempak::run; gempak::end;
To show only the Texas area, for example, use
gempak::define garea "tx"; gempak::define area "garea";
Instead of using the last data in the above example, it is best to use the data for the last (previous) hour. This can be acomplished by adding the following in the above script:
set last_hour [clock format [expr $now - 3600] -format "%H" -gmt true]; gempak::define dattim "/$last_hour";
Instead of setting the sfparm and colors directly, the various arrtibutes can be set separately:
# first parameter gempak::sfparm_name "skyc"; gempak::sfparm_size 0.75; gempak::set_sfparm; gempak::colors 26; # second one gempak::sfparm_name "tmpf"; gempak::sfparm_size 0.75; gempak::append_sfparm; gempak::append_colors 2; # third one gempak::sfparm_name "brbk"; gempak::sfparm_size 0.75; gempak::append_sfparm; gempak::append_colors "26";
Example 11
This example uses sfcntr to make a contour plot of the the ``tmpf'' variable.
# Find the current file in the surface data directory set surfacedir [file join $env(GEMDATA) "surface"]; set now [expr [clock seconds]]; set sffile_name [clock format $now -format "%Y%m%d" -gmt true]; append sffile_name "_sao.gem"; set sffile [file join $surfacedir $sffile_name]; # main gempak::define sffile $sffile gempak::define device "gif|sfcntr.gif"; gempak::define garea "15;-125;50;-60"; gempak::define area "garea"; gempak::define dattim "last"; gempak::define sfparm "tmpf" gempak::define colors 0; gempak::define cntrprm "tmpf"; gempak::define cint 5; gempak::init sfcntr; gempak::run; gempak::end;
For the Texas area alone, a setting such as these
gempak::define garea "tx"; gempak::define area "garea"; gempak::define cint 3;can be used.
Example 12
This example plots a 10 day (script executed on 17 Jan 2009) forecast temperature at 900 mb using gdcntr.
# Choose a model and file set datadir [file join $env(GEMDATA) "model" "gfs"]; set gdfile_name "2009011718_gfs211.gem"; set gdfile [file join $datadir $gdfile_name]; # main gempak::define gdfile $gdfile gempak::define device "gif|gdcntr.gif"; gempak::define garea "tx"; gempak::define dattim "last"; gempak::define gfunc "tmpf" gempak::define glevel 900; gempak::define gvcord "pres"; # for contour only or fill only use one of these ## gempak::ctype_fill; ## gempak::ctype_contour; # we will do both gempak::ctype_fc; # Put more contours than the defaults gempak::cint_interval 3; gempak::set_cint; gempak::init gdcntr; gempak::run; gempak::end;
Example 13
This example plots several 900 mb wind streamlines forecast using gdstream.
# Choose a model and file. We will pick the latest gfs211.
#
set datadir [file join $env(GEMDATA) "model" "gfs"];
set filelist [lsort [glob -directory $datadir "*gfs211.gem"]];
set gdfile [lindex $filelist end];
# main
gempak::define gdfile $gdfile
gempak::define garea "tx";
gempak::define gvect "wnd"
gempak::define glevel 900;
gempak::define gvcord "pres";
gempak::define line "3//1";
gempak::define map "1/7";
gempak::define title "5";
gempak::define latlon "2/10/1/1/5;5";
# Do several forecast times
foreach t [list 24 36 48 72] {
gempak::define gdattim f$t;
gempak::define device "gif|gdstream_$t.gif";
gempak::init gdstream;
gempak::run;
gempak::end;
}
Example 14
Similar to the previous example but using gdwind.
# Choose a model and file. We will pick the latest gfs211.
set datadir [file join $env(GEMDATA) "model" "gfs"];
set filelist [lsort [glob -directory $datadir "*gfs211.gem"]];
set gdfile [lindex $filelist end];
# main
gempak::define gdfile $gdfile
gempak::define garea "tx";
gempak::define gvect "wnd"
gempak::define glevel 900;
gempak::define gvcord "pres";
gempak::define map "1/7";
gempak::define title "3";
gempak::define latlon "2/10/1/1/5;5";
# Set them like this or as set below
## gempak::define wind "ak4"
## gempak::define refvec "10";
## gempak::define skip "/1;1";
gempak::wind_symbol_type "a";
gempak::wind_symbol_units "k";
gempak::wind_symbol_color "4";
gempak::set_wind;
gempak::refvec_magnitude 10;
gempak::set_refvec;
gempak::skip_plot_xy 1 1;
gempak::set_skip;
# Do several forecast times
foreach t [list 24 36 48] {
gempak::define gdattim f$t;
gempak::define device "gif|gdwind_$t.gif";
gempak::init logfile gdwind;
gempak::run;
gempak::end;
}
Example 15
This example uses gdinfo to extract the list of variables from a grib file. Each record in the output is formatted like
tmpk_150_pres,000,006,012,018,024,030,036,042,048,054,060, ...The first element of the comma-separated record is a variable identifier constructed from the variable name, the level and the level coordinate, separated by an underscore. The rest of the record are the forecast hours for which the data is available for that variable identifier.
# Choose a model and file. We will pick the latest gfs211. set datadir [file join $env(GEMDATA) "model" "gfs"]; set filelist [lsort [glob -directory $datadir "*gfs211.gem"]]; set gdfile [lindex $filelist end]; gempak::gdinfo::define gdfile $gdfile; gempak::gdinfo::define lstall "yes"; gempak::gdinfo::define output "t"; gempak::gdinfo::define gdattim "all"; gempak::gdinfo::define glevel "all"; gempak::gdinfo::define gvcord "all"; gempak::gdinfo::define gfunc "all"; gempak::gdinfo::init; gempak::gdinfo::run; gempak::gdinfo::end; puts [gempak::gdinfo::output];
Example 16
This example uses sflist to extract the data from a surface file.
gempak::sflist::sffile $env(GEMDATA)/surface/20090202_sao.gem gempak::sflist::dattim "all"; gempak::sflist::sfparm tmpf relh dwpf pmsl sped drct; gempak::sflist::stations tjsj gempak::sflist::init; gempak::sflist::run; gempak::sflist::end; puts [gempak::sflist::output];
The output of the scripts looks as follows
stn,yymmdd/hhmm,tmpf,relh,dwpf,pmsl,sped,drct tjsj,090202/0000,78.80,73.95,69.80,-9999.00,4.63,70.00 tjsj,090202/0100,78.08,76.19,69.98,1017.70,4.63,60.00 tjsj,090202/0200,78.08,76.19,69.98,1017.70,4.63,70.00 tjsj,090202/0300,77.00,76.57,69.08,1017.90,4.63,90.00 ...