Ferret v5.6 release notes

Ferret Version 5.6 Release Notes

April 9, 2004

New Features and Enhancements in Version 5.6

New options for REPEAT introduce a "FOREACH" functionality with REPEAT/RANGE=[/NAME=]
New qualifiers to draw graticule lines, that is, guide lines across plots at the tic marks of the axes.
New palette files

Bug fixes

Make the definition of an axis with /UNITS=year the same as with/UNITS=yr; and have the axis take on the length of the year according to the calendar specified. The default year length is 365.2425 days.
Plot polygons correctly when the 1-D form of the POLYGON commandis used, e.g. (POLY/FILL/LINE {2,2,4,4,,8,10,6,}, {10,15,15,10,,6,4,4,,} )
Can do an ASCII LIST of string and numeric data together; previously this crashed Ferret.
For longitude axes, do not label 0 degrees with E. This is now consistent with the labeling of latitude axes.
When reading from a NetCDF file using strides, a DEFINE GRID/LIKE=varcommand had caused Ferret to use regridding rather than a strided read.
Set the LEVELS symbols on POLYGON commands, as they are for CONTOUR, SHADE, and FILL, previously these were not defined after a call to POLYGON
yes? POLY xpts, yptsyes? SHOW SYMBOL lev*
Fixes for cellarray plots (used for SHADE commands in -gif mode)so that they work correctly if we are using /HLIMITS or /VLIMITS to use adifferent range on the plotting axes than the range of the data that has been loaded.
Let region names have longer string lengths, up to 24 characters. Previously could define regions with long names but not retrieve them correctly.
Warning message restored if we have specified a range of coordinates outside the bounds of an axis.
PLOT/SYM/SIZE= now changes the size of the symbols correctly.
Improvements to the labels on shade keys: the 5th argument to PPL SHAKEY, klab_dig, sets the actual number of decimal places (klab_dig < 0) in the key; previously it had set a maximum number of decimal places.

New Features and Enhancements in Version 5.6

New options REPEAT/RANGE=[/NAME=]
The new /RANGE qualifier lets us use REPEAT looping which is independent of any grid or axis. You may define a range to loop over, and optionally name the repeat counter. The namethat is used is undefined after the loop terminates. This syntax can be usedfor nested loops, and can be used together with standard REPEAT loops which use I=,J=,X=,and so on.

A word of caution is in order about REPEAT/RANGE. If you find yourself doing some operation to every element of a variable along an axis, or using REPEAT to do regridding, integrals or averages, you will want to rethink whether you are unnecessarily complicating your scripts and probably slowing your calculations. Do not use REPEAT to duplicate Ferret's capability of operating on entire grids or axes in a single command. Using Ferret's commands for regridding, transformations, and so on will be more efficient and foolproof than "programming" with REPEAT loops. New Ferret users should study Chapter 1-4 of the Ferret Users Guide for guidance on using Ferret expressionsfor computation.

Examples of REPEAT/RANGE=[/NAME=]:
- Simplest case
```
 yes? LET a = 12
 yes? REPEAT/RANGE=1:3 (LET a = `a+2`; LIST a) !-> REPEAT: REPCOUNT:1 !-> DEFINE VARIABLE a = 14 VARIABLE : 14 14.00 !-> REPEAT: REPCOUNT:2 !-> DEFINE VARIABLE a = 16 VARIABLE : 16 16.00 !-> REPEAT: REPCOUNT:3 !-> DEFINE VARIABLE a = 18 VARIABLE : 18 18.00
```
- With a named loop counter
```
 yes? REPEAT/RANGE=1:7:3/NAME=s (LIST/NOHEAD s) !-> REPEAT: S:1 1.000 !-> REPEAT: S:4 4.000 !-> REPEAT: S:7 7.000
```
- To loop over a list (FOREACH functionality) where the loop is independent of any region that may be set
```
 yes? SET REGION/x=300:360/y=40:60/z=0:100/t="1-jan-2000:1-jan-2004"

 yes? LET file_list = {"month_2.nc", "month_5.nc", "month_8.nc"}

 yes? REPEAT/RANGE=1:3/NAME=m (LET name = file_list[i=`m`]; \
 USE `name`; \
 GO myscript}
```
- Another example, using the loop counter variable within the loop
```
 yes? USE levitus_climatology 
 yes? SET REGION/X=100:300/Y=0/Z=10
 yes? PLOT temp

 yes? LET r1 = INT( temp[X=@MIN]) + 1
 yes? LET r2 = INT( temp[X=@MAX]) - 1

 yes? REP/RANGE=`r1`:`r2`:3/NAME=tt (PLOT/OVER MAX(temp,`tt`) ) !-> REP/RANGE=23:29:3/NAME=tt (PLOT/OVER MAX(temp,`tt`) ) !-> REPEAT: TT:23 !-> PLOT/OVER MAX(temp,23) !-> REPEAT: TT:26 !-> PLOT/OVER MAX(temp,26) !-> REPEAT: TT:29 !-> PLOT/OVER MAX(temp,29)
```
Qualifiers /GRATICULE, /HGRATICULE and /VGRATICULE
set graticule lines across plots at the tic marks. They are available on the PLOT, CONTOUR, FILL, SHADE, and VECTOR commands.

PLOT/GRATICULE[=linetype]
is a single command to turn the graticules for both the horizontal and the vertical axes on. By default the graticules are drawn as thin black lines at each large tic mark. The colors and the thickness settings have the same options as the settings for PLOT lines. The syntax is

PLOT/GRAT[=(dash or line, COLOR=colorname, THICKNESS[=value]]) var
```
 yes? PLOT/GRAT=(dash,COLOR=red) var

 yes? SHADE/GRAT=(COLOR=white) rose

 yes? PLOT/GRAT=(THICK=3)/t=1-jan-1990:1-jan-2002 my_data
```
PLOT/HGRATICULE[=linetype] /VGRATICULE[=linetype]
These two qualifiers give the user separate control of horizontal and vertical tics. Each takes the same optional arguments as /GRATICULE.

Any of the three qualifiers /GRAT /HGRAT /VGRAT can take arguments to also turn on graticule drawing at small tic marks and set the line type for the small-tic graticules, using the same arguments.
```
 PLOT/GRAT="LARGE(arguments),SMALL(arguments)" var
```
Examples:
```
 yes? PLOT/GRAT=dash/i=1:40 sin(i/6), sin(i/8)
```


yes? USE etopo20; set reg w
 yes? SHADE/GRAT=(COLOR=white) rose

 yes? DEF AXIS/Z/DEPTH dlog=exp(k[k=1:10])
 yes? LET fcn = k[gz=dlog]
 yes? PLOT/VLOG/VLIMITS=1:10000/HGRAT="LARGE(COLOR=red),SMALL(COLOR=lightblue)"/VGRAT fcn

 yes? USE monthly_navy_winds
 yes? SET REGION/X=180/Y=0/T=1-may-1989:1-may-1992
 yes? PLOT/HGRAT/VGRAT="LARGE(COLOR=blue),SMALL(COLOR=lightblue)" uwnd

New palette files

topo.spk, a palette defined by_value for use with topography/bathymetry data sets.Because the colors are defined by value, each color corresponds to the same value of elevation regardless of the range of elevation on the plot.The palette looks best when the levels are selected to have more levelsnear zero meters elevation and fewer levels at high altitudes and deep depths.
For an area with a wide range of depths and altitudes:
```
 yes? USE "http://www.ferret.noaa.gov/cgi-bin/nph-dods/data/PMEL/smith_sandwell_topo_v8_2.nc" yes? SET REGION/X=110:160/Y=-40:0 yes? SHADE/PAL=topo/LEV=(-9000,-1000,1000)(-1000,-100,100)\ (-100,100,10)(100,1000,100)(1000,6000,1000) rose
```
For a smaller area and new levels specified, the same colors are used at each elevation:
```
 yes? USE use "http://www.ferret.noaa.gov/cgi-bin/nph-dods/data/PMEL/smith_sandwell_topo_v8_2.nc" yes? SET REGION/X=134:144/Y=-18:-8 yes? SHADE/PAL=topo/LEV=(-2600,-100,50)(-100,100,5)(100,500,50) rose
```

Additional single-color palettes, useful for plotting individual dotsusing the POLYGON command, e.g.

 yes? SHADE/pal=land_sea/lev=(-1000,1000,100) rose yes? LET xpts = {135,136.6,142} yes? LET ypts = {-12.5,-12.0,-11.7} yes? GO polymark POLY/OVER/NOKEY/NOLAB/LINE/PAL=magenta xpts, ypts, , square yes? LET xpts = {138,139,140,141} yes? let ypts = {-15, -15, -15.5, -14.} yes? GO polymark POLY/OVER/NOKEY/NOLAB/LINE/PAL=orange_dark xpts, ypts, , square

See also the color palettes FAQ for more uses of these palettes, Ferret Color Palettes

The entire list of single-color palettes is:

black white	orange orange_dark orange_light
blue blue_dark blue_light	pink pink_dark pink_light
brown brown_dark brown_light	purple purple_dark purple_light
cyan cyan_dark cyan_light	red red_dark red_light
gray gray_dark gray_light	tan tan_dark tan_light
green green_dark green_light	violet violet_dark violet_light
grey grey_dark grey_light	yellow yellow_dark yellow_light
magenta magenta_dark magenta_light