NCL at met.no

The ncl-metno shell scripts

Before you can use the ncl-metno shell script, you must install NCL on your system. Download NCL from its webite at http://www.ncl.ucar.edu and install NCL on your system. Then, when you proceed to installing the ncl-metno software, follow the instructions from the README file. Note in particular that nothing will work unless you set some paths in the executable INSTALL script file, and then execute that script.

Below is a list of shell scripts that were developed at met.no. These were written for use with netCDF files, and will generate NCL scripts that are subsequently run (and usually deleted). The documentation of the scripts are divided into two parts. First, one or more examples are presented, and then the syntax is provided and described.

The main scripts are (in alphabetical order):
• addlayers.sh: adds values for a variable from a set of adjacent levels (e.g. layer thicknesses from isopycnic models)
• c-mask.sh (contours, masked): first masks one field based on values from another field, and then draws filled contours for the result
• contour.sh: draws filled contours for x-y fields, which may be extracted from 3- or 4-dimensional fields
• Dcontour.sh: draws filled contours for differences between x-y fields, which may be extracted from 3- or 4-dimensional fields
• layersection.sh: draws filled contours for crossections of layered results (along the x- or y-direction)
• Scontour.sh: as Dcontour.sh, but adds values from two fields (e.g. useful for adding means and anomalies)
• section.sh: filled contours for crossection (e.g. useful for Hovmøller plots)
• slice.sh: draws filled contours for z-levels from layered results
• Svector.sh: draws vectors based on the sum of two vector fields (e.g. useful for adding barotropic and baroclinic vector fields; NOTE that for 4D fields, the third dimension, usually z, is omitted for the 2nd vector field)
• transport.sh: displays transports as vectors on filled contours of fluxes
• v-on-c.sh (vectors-on-contours): draws vectors on filled contours for x-y fields, which may be extracted from 3- or 4-dimensional fields
• vector.sh: draws vectors

Some multi-plot scripts are also included:
• mcontour.sh
• mc-mask.sh
• mlayersection.sh
• mvector.sh
each one of these m* scripts produces a set of ppm & gif files that are subsequently assembled to a gif animation.

Let's assume that you install the scripts above in the directory

/home/arnem/lib/ncl-metno/

and that you soft link the scripts to the directory

/home/arnem/lib/ncl-metno/

(you may consider including the latter path in your $PATH environmental variable, i.e., PATH=$PATH:/home/arnem/lib/ncl-metno/ ). The syntax is written on the screen when a script is executed without any command line arguments. More extensive information is written upon request from the user, e.g.:

contour.sh --help

With the exception of the multi-plot scripts, all scripts produce an eps file and a png file. With a little extra effort, the user may alter some aspects of the depictions, see the item below. Furthermore, all scripts may be run with an option set to a value that causes the ncl script to be retained (the ncl script will generally be deleted). This is typically done when a flag is set by changing the sign of a positive command line option, see the syntax for each script for details. A user with knowlegde of ncl may then rewrite the ncl script in order to adjust the output.

Can the shell scripts be used with no knowledge of NCL?

Yes.
But: it is a prerequisite that the fields to be depicted are retrieved from netCDF files. Further, the user may
• select a color map (type and no. of colors)
• select font
• change the title of the plot
• zoom in on a subdomain
• change the physical size of the plot (width and height)
• change the vector spesification
For depictions on geographical maps, the user must
• correctly specify the names of the longitude and latitude variables if these are two-dimensional
For depictions on geographical maps, the user may:
• change the map projection
• change the level of detail in the coast line

with no knowledge of ncl, by copying the file

/home/arnem/lib/ncl-metno/

to the working directory. The file must be copied and edited prior to execution if default settings are to be changed. Preset values and comments on userdef.ncl are meant to aid the user in this respect.

The color maps that are available by editing userdef.ncl are rainbow (default), red-white-blue (recommended for the color blind), shades of gray, tiger stripes and NRL. See example 6 in the documentation of contour.sh for more information. Two of the color maps can have up to 37 different colors, whereas the others are limited to 18 different colors. Note that tiger stripes may well be used with color repetion.

It is also relatively easy to zoom in on a subdomain (see example 2 in the documentation of vector.sh), and to change the vector specification if vectors are present (see example 3 in the documentation of vector.sh). A new feature in v.1.2 is that for depictions on geographical maps, the user may instead zoom in by limiting the range of longitudes & latitudes, see text in 'userdef.ncl' for details.

For the NCL trained user, the present shell scripts may be used to produce a preliminary ncl script for later editing (with the exception of the m*.sh multi-plot scripts), by setting a flag for retaining the ncl script (see the syntax description for each shell script).

End products

The products after execution of the presently provided shell scripts are:

• a graphical depiction of the user provided field on the screen
• a ncl script stored on a file (.contour.ncl etc.), however, this script will be deleted unless a command line flag is set (see the syntax of each script)
• an eps file and a png file, for most scripts with the variable name as the prefix (e.g. temperature.eps and temperature.png)

NCL documentation

• NCL's web site
• Introduction to NCL
• Application examples
• Reference manual
• Resources
• Built-in functions

Version history

v. 1.0 2005-04-24

first public release

v. 1.01 2005-07-09

• removed bug when using maps in addlayers.sh
• introduced option to include an additional .ncl file named usermod.ncl immediately before plotting
• introduced options for stretching the isopleth contour values by using a negative nv value in userdef.ncl

v. 1.1 2005-12-13

• added a script slice.sh for extracting horizontal slices from layered results
• added capabilities for additional animation output formats (gif and mng) when using makemovie.sh
• introduced options for using cells or computed isopleths when contouring, and added user specification for "land" color, both in userdef.ncl
• minor bugs removed

v. 1.2 2006-04-11

• added option to use 2d fields for lon's & lat's in map plots for scalars; if the longitude & latitude variable names are NOT 'lon' & 'lat', they must be either be provided on the command line or in a local copy of 'userdef.ncl'
• producing resized cropped png images using pstoppm & convert
• included option to resize the png images by creating & editing a local copy of the file 'resize'
• added option to specify font in 'userdef.ncl'
• added option to specify zooming for a longitude/latitude span in 'userdef.ncl'
• modified error testing in most scripts
• added brief pause at the end of animations (last frame repeated 4 times)
• no longer uses path to working directory for input & output files (i.e. ./ is default as usual, but relative or absolute paths may be used, so netcdf files may now reside in any directory)
  this may be a problem if these scripts are executed e.g. by a cron job, so then you should first make ncl-scripts with the ncl-metno tool, and include absolute paths in the ncl script
• the multi-frame scripts m*.sh now produce gif animations, and files with single frames are deleted (default, the files are retained by using a special syntax); makemovie.sh is obsolete, and has been discarded in v. 1.2 along with xcontour.sh

Questions?

Contact Arne Melsom (arne.melsom@met.no), Section Oceanography, Norwegian Meteorological Institute.