# 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 command is 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 labelling of latitude axes.
- When reading from a NetCDF file using strides, a DEFINE GRID/LIKE=var command 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, ypts yes? 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 a different 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 name that is used is undefined after the loop terminates. This syntax can be used for 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 expressions for 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 levels near 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 dots using 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