Release notes: Ferret Version 4.9

New commands and qualifiers

• SHOW FUNCTIONS
• 3-argument (curvilinear) version of SHADE and FILL
• /NOAXIS qualifier added to SHADE, PLOT, CONTOUR, and VECTOR

Enhancements

• curvilinear coordinate graphics support
• gridded data sets on curvilinear coordinates
• layered (sigma) coordinate systems
• map projections
• 24-bit system support
• GIF mode - GIF output without X windows
• PostScript mode - PostScript output without X windows
• grid-changing functions
• UNRAVEL(X)
• RESHAPE(A,B)
• ZAXREPLACE(V,ZVALS,ZAX)
• new transformations
• @CDA (closest distance above)
• @CDB (closest distance below)
• @CIA (closest index above)
• @CIB (closest index below)
• new regrid transformation
• @XACT (exact coordinate match)

Minor changes

• Negative time axis values are supported
• DEFINE AXIS/unit=MONTHS will issue a warning
• variable name length increased
• In a NetCDF file any "Y" in the name of an axis caused it to be identified (mistakenly in some cases) as a Y axis

Bug fixes

• regridding with @mod no longer drops the final subscript
• NetCDF time units which lack hours are now supported: e.g. time:units="hours since 1992-10-8 0"
• definite integral @DIN in ZT plane used COS(y) correction filler transformations (e.g. @FLN) return original field when component range is insufficient (at edges of field)

---

• SHOW FUNCTIONS

The SHOW FUNCTIONS command now shows a complete list of the functions defined in Ferret including descriptions of the function arguments. SHOW FUNCTIONS will accept name templates such as

yes? SHOW FUNCTION *day*

DAYS1900(day,month,year)

days elapsed since Jan. 1, 1900

• 3-argument (curvilinear) version of SHADE and FILL

  The SHADE and FILL commands now have a 3-argument mode which allows them to create output in "curvilinear" coordinates. This allows for easy generation of output plots using sigma coorindates as well as the application of various map projections. A typical command line entry will look like:

  yes? SHADE sst, x_page, y_page
  

  where the second and third arguments, x_page(i,j) and y_page(i,j), must be (at least) 2-dimensional grids which specify the X page (horizontal) position and Y page (vertical) position for each (i,j) index pair. The page positions may be in any units; Ferret will scale the plot according to the ranges of values in the position fields. For map projections, these will typically be defined by the map projection scripts as Ferret variables as in the following section from the journal file for creating Lambert cylindrical equal-area projections:
  

  let/quiet mp_x = x
  let/quiet mp_central_meridian = (mp_x[i=@max] + mp_x[i=@min])/2
  let/quiet mp_y = y
  let/quiet mp_standard_paralell = (mp_y[j=@max] + mp_y[j=@min])/2
   
  let/quiet Pi = 3.14159265
  let/quiet deg2rad = Pi / 180.0
   
  let/quiet mp_R = 1
  let/quiet mp_lambda0 = mp_central_meridian * deg2rad
  let/quiet mp_lambda = x * deg2rad
  let/quiet mp_phi = y * deg2rad
   
  let/quiet x_page = mp_R * (mp_lambda-mp_lambda0)                    ! eqn (1)
  let/quiet y_page = mp_R * sin(mp_phi)                               ! eqn (9)
  

  Note: The default axis labeling for the 3-argument commands will be the ranges of the position fields: inappropriate when map projections are being used. The /NOAXIS qualifier is provided for this purpose.

• /NOAXIS qualifier added to SHADE, PLOT, CONTOUR, and VECTOR

The /NOAXIS qualifier causes the axes and axis labels to be omitted from the plot. (See the AXSET command in the PLOT+ Users Guide). The qualifier has been added to support the curvilinear coordinate and map projections capabilities of the 3-argument versions of SHADE, FILL, and CONTOUR in which linear axes are inappropriate.

Note that if the /SET_UP qualifier is used in conjunction with /NOAXIS a Ferret state is altered such that future plots will be drawn without axes. Ferret will warn you of this and coach you to use PPL AXSET 1, 1, 1, 1 to restore normal axis drawing.

• curvilinear coordinate graphics support
• gridded data sets on curvilinear coordinates

  If a given gridded variable is defined on a curvilinear coordinate system, then one need only provide the X and Y coordinate fields in the 3-argument SHADE or FILL command to accurately depict the field. For example, if a data set contained a variable TEMP, which was Nx x Ny in the longitude-latitude plane, and the data set also contained variables LON_POSITION and LAT_POSITION of the same size, then the command:

  yes? SHADE TEMP, LON_POSITION, LAT_POSITION

  would render the curvilinear plot.

  See 3-argument SHADE or FILL command for further details.

• layered (sigma) coordinates

  The capability to render curvilinear coordinates allows Ferret to display sigma coordinate fields without interpolating or regridding the variable to be displayed.

  In this example from the Ferret FAQ the variable flow is defined on the gg grid where the Z axis is in layers. To display the field we need only create multidemensional fields specifying the relative positions of (i,j) pairs and use the new curvilinear coordinate commands:

  let depth = h[k=@rsum]-h/2
  set variable/title="DEPTH function"/unit=meters depth
  let ygg = y[g=gg]
  set variable/title="Y"/unit=kilometers ygg
  shade flow[x=0,l=1], ygg, depth[x=0,i=1]
  

  

  For a detailed example illustrating the use of curvilinear coordinates to analyze sigma-coordinate fields see the FERRET FAQ entry, How to handle sigma coordinate output in Ferret.

• map projections

  Along with general capabilities for curvilinear coordinates, version 4.9 provides a series of scripts for many common map projections. Instructions for using the map projection scripts can be obtained by running the demo:

  yes? go mp_demo
  

  or by reading the instructions which come with each script:

  yes? GO/HELP projection_script_name
  

  Here is the list of supported map projections:
  (The techniques used are quite general and can be applied to most map projections.)

  Ferret script	Projection name
  mp_bonne.jnl	Bonne
  mp_craster_parabolic.jnl	Craster Parabolic
  mp_eckert_greifendorff.jnl	Eckert Grifendorff
  mp_eckert_iii.jnl	Eckert III
  mp_eckert_v.jnl	Eckert V
  mp_hammer.jnl	Hammer
  mp_lambert_cyl.jnl	Lambert Cylindrical Equal Area
  mp_mcbryde_fpp.jnl	McBryde Flat Polar Parabolic
  mp_orthographic.jnl	Orthographic
  mp_plate_caree.jnl	Plate Caree
  mp_polyconic.jnl	Plolyconic
  mp_sinusoidal.jnl	Sinusoidal
  mp_stereographic_eq.jnl	Stereographic Equatorial
  mp_stereographic_south.jnl	Stereographic North
  mp_vertical_perspective.jnl	Stereographic South
  mp_vertical_perspective.jnl	Vertical Perspective
  mp_wagner_vii.jnl	Wagner VII
  mp_winkel_i.jnl	Winkel I
  Here is the list of utility scripts to support curvilinear coordinates
  Ferret script	Function
  mp_demo.jnl	demonstration of various map projections.
  mp_fland.jnl	curvilinear version of fland.jnl
  mp_graticule.jnl	creates a graticule (lines of longitude and latitude) over the whole globe or any portion
  mp_label.jnl	correctly places labels using lat-lon coordinates
  mp_land.jnl	curvilinear version of land.jnl
  mp_land_stripmap.jnl	creates a land-centric interrupted map using the current projection
  mp_line.jnl	correctly plots user lat-lon data on the map
  mp_ocean_stripmap.jnl	creates an ocean-centric interrupted map using the current projection

• 24 bit system support

  Ferret now displays colors correctly on X window servers configured to use a 24 bit color display. If you use such a display, note the following:

  • You may have to click on a Ferret window to correctly display the colors in that window.
  • Other windows may change color once the Ferret window becomes active. Clicking on the windows that change color will restore their original color.
  • The X server must support multiple visuals, and at least one PseudoColor, or indexed, visual. Unfortunately, the X server available on most Linux machines only supports one visual at a time; Ferret will not work with 24 bit color displays on such machines.

• GIF mode - GIF output without X windows

  Ferret can now run in batch mode -- without an X server. Invoke batch mode by starting up Ferret with the -gif option:

  ferret -gif

  Graphical output is buffered, and can be stored in a GIF file by executing the FRAME command. For example:

  yes? frame/file=picture.gif

  sends the stored graphical output from Ferret to the GIF file picture.gif.

  Please note the following when using batch mode:

  • Window resizing only works if the window is cleared before resizing the window. For instance:

    yes? set window/clear/size=0.25

    will resize the window while

    yes? set window/size=0.25/clear

    will cause an error.
  • Avoid metafile commands when running in batch mode. In particular,

    yes? set mode meta

    may cause problems.
  • Don't create new Ferret windows when running without an X server. The following command:

    yes? set window/new

    will cause Ferret to crash.
• PostScript mode - PostScript output without X windows

  Ferret can also generate PostScript files without an X server. This is an experimental feature and not fully supported. If you wish to use this mode, start Ferret with the -batch option:

  ferret -batch <file>.ps

  where <file> is the name of the output file. Note that the filename must end with ".ps".

  Please note the following when using PostScript mode:

  • The PostScript output will not be fully written to the output file until you exit from Ferret.
  • Window sizing commands do not have any effect on PostScript output.
  • Avoid metafile commands when running in PostScript mode.
  • Don't create new Ferret windows when running without an X server. The following command:

    yes? set window/new

    will cause Ferret to crash.
• grid-changing functions
  
  Ferret version 4.9 has introducde a new class of functions which is much more flexible than functions in previous versions. The new functions are distinct in that the result of the function may be on a grid whose character is not inferred simply my merging the grids of the function arguments. Each axis of the result grid of a grid-changing function may inherit from particular arguments, may be "normal" to a particular dimension (as in averaging along an axis), or may insert a new axis (for example a time axis replaced by a frequency axis during a Fourier transformation. The functions listed below are the first in a list of functions that will be added as Ferret matures. (Grid-changing functions and user-written "external" grid-changing functions will be the primary feature added in version 5 of Ferret.)
  
• UNRAVEL(X)
  
  The result of the UNRAVEL function is the data values supplied as the function argument, unmodified in value, but expressed as a single-dimensioned list in the X axis orientation. The resultant grid will always be a single ABSTRACT X.
  
  Example:
  

yes? LIST x[x=1:3:1]+y[y=.1:.2:.1]
          X[X=1:3:1]+Y[Y=.1:.3:.1]
                 1     2     3
                 1     2     3
      0.1 / 1: 1.100 2.100 3.100
      0.2 / 2: 1.200 2.200 3.200

yes? LIST/ORDER=x UNRAVEL( x[x=1:3:1]+y[y=.1:.2:.1] )
         UNRAVEL( X[X=1:3:1]+Y[Y=.1:.2:.1] )
        1      2      3      4      5      6
        1      2      3      4      5      6
      1.100  2.100  3.100  1.200  2.200  3.200

yes? SHOW GRID
     Default grid for DEFINE VARIABLE is ABSTRACT
     Last successful data access was on grid (G002)
        GRID (G002)
     name     axis       # pts   start       end
     ABSTRACT  X       9999999 r   1        9999999
     normal    Y
     normal    Z
     normal    T    

• RESHAPE(A,B)
  
  The result of the RESHAPE function will be argument A "wrapped" on the grid of argument B. A common use of this function is to view multi-year time series data as a 2-dimensional field of 12-months vs. year.
  
  A simple 2D example:
  

yes? LET A = X[X=1:3:1]+Y[Y=0.1:0.2:0.1]
yes? LIST A
             X[X=1:3:1]+Y[Y=0.1:0.2:0.1]
               1      2      3    
               1      2      3
 0.1   / 1:  1.100  2.100  3.100
 0.2   / 2:  1.200  2.200  3.200
    
yes? LET B = X[X=100:200:100]+Y[Y=10:30:10]
yes? LIST B
             X[X=100:200:100]+Y[Y=10:30:10]
             100    200   
              1      2
 10   / 1:  110.0  210.0
 20   / 2:  120.0  220.0
 30   / 3:  130.0  230.0
  
yes? LIST RESHAPE(A,B)
             RESHAPE(A,B)
             Z: 1
             T: 1
             100    200   
              1      2
 10   / 1:  1.100  2.100
 20   / 2:  3.100  1.200
 30   / 3:  2.200  3.200

A subtlety in the use of this function arises when one or more of the axes in the grid of argument 1 are shared by the grid of argument two. In this case the ranges on those axes are preserved -- the data from argument 1 is wrapped only within the indocated sub-range of those axis. For example, suppose the variable uwnd contains monthly data from Jan 1982 to Dec 1992.

Example - reshape Z and T axes leaving X and Y intact:

yes? SET DATA monthly_navy_winds

! define a simple 12 month axis and a 3 year axis
yes? DEFINE AXIS/Z=1:12:1 Zmonth
yes? DEFINE AXIS/T=1982:1985:1 Tyear

! define a variable that shares X,Y with uwind
yes? LET out_grid = x[g=uwnd,i=1]+y[g=uwnd,j=1]+z[gz=zmonth,k=1]+t[gt=tyear,l=1]

! define the reshaped variable
yes? LET Wind_by_month = RESHAPE(uwnd[l=1:36],out_grid)

! look at the first three Januaries of winds at a single point
yes? LIST/X=180/Y=0 uwnd[l=1:36:12]
             ZONAL WIND (M/S)
             regrid: 8766 hour on T
             LATITUDE: 0
             DATA SET: monthly_navy_winds.des
                 180E  
                 65
 JAN-1982 / 1: -2.738
 JAN-1983 / 2: -1.565
 JAN-1984 / 3: -5.446

! the same information on a 2D grid of months by years
yes? LIST/X=180/Y=0 Wind_by_month[k=1:6]! Jan-June of 3 years
             RESHAPE(UWND[L=1:36],OUT_GRID)
             LONGITUDE: 180E
             LATITUDE: 0
             DATA SET: monthly_navy_winds.des
                1      2      3      4      5      6    
                1      2      3      4      5      6
 1982   / 1: -2.738 -2.331 -3.251 -3.124 -1.818 -2.007
 1983   / 2: -1.565  1.051 -0.996 -0.467 -2.952 -3.229
 1984   / 3: -5.446 -5.411 -3.861 -5.746 -3.780 -2.792

Notice that the 36 values from uwnd (argument A) were not wrapped onto the X and Y axes of the grid of argument B because both A and B shared the same X and Y axes.


• ZAXREPLACE(V,ZVALS,ZAX)
  

The ZAXREPLACE function is a tool to convert between alternative monotonic Z axes, where the mapping between the source and destination Z axes is a function of X, Y, and or T. Typical applications in the field of oceanography include converting from a Z axis of layer number to a Z axis in units of depth (e.g. for sigma coordinate fields) and converting from a Z axes of depth to one of density (for a stably stratified fluid).

The ZAXREPLACE function takes three arguments. The first argument, V, is the field of data values, say temperature or salinity. This variable is available on what we will refer to as the "source" Z-axis -- say in terms of layer number. The second argument, ZVALS, contains the values of the desired destination Z axis defined on the source Z axis -- for example, it may contain the depth values associated with each vertical layer. It should always share the Z axis from the first argument. The third argument, ZAX, is defined on the destination Z axis. Only the Z axis of this variable is relevant -- the values of the variable, itself, and its structure in X, Y, and T are ignored.

Simple example - vertical temperature section on density levels:

! a data set based on depth in decibars
SET DATA levitus_climatology
SET REGION/X=180

! define density (in kg/m^3)
LET density = RHO_UN(salt, temp, z[g=temp])

! plot the temperature on its native grid
SET VIEW upper
SHADE/Title="Temperature on pressure (with density contours)" temp[z=0:1000]
ppl conset,,,,,,,,.5           ! (to get contour labels)
CONTOUR/OVER density[z=0:1000]

! now plot temperature on a vertical axis of density
SET VIEW lower
STAT density[z=0:1000]
DEFINE AXIS/Z=1022:1032:.2/units="density units"/depth zdens
LET temp_on_dens = ZAXREPLACE(temp[z=0:1000],density[z=0:1000], z[gz=zdens])
SET VARIABLE/TITLE="Temperature on density axis" temp_on_dens
SHADE temp_on_dens



For a detailed example illustrating the use of the ZAXREPLACE function to analyze sigma-coordinate fields see the FERRET FAQ entry, How to handle sigma coordinate output in Ferret.

• new transformations
• @CDA (closest distance above)
  
  The transformation @CDA will compute at each grid point how far it is to the closest valid point above this coordinate position on the indicated axis. The distance will be reported in the units of the axis. If a given grid point is valid (not missing) then the result of @CDA for that point will be 0.0.
  
  
• @CDB (closest distance below)
  
  The transformation @CDB will compute at each grid point how far it is to the closest valid point below this coordinate position on the indicated axis. The distance will be reported in the units of the axis. If a given grid point is valid (not missing) then the result of @CDB for that point will be 0.0.
  
  
• @CIA (closest index above)
  
  The transformation @CIA will compute at each grid point how far it is to the closest valid point above this coordinate position on the indicated axis. The distance will be reported in terms of the number of points (distance in index space). If a given grid point is valid (not missing) then the result of @CIA for that point will be 0.0.
  
  
• @CIB (closest index below)
  
  The transformation @CIB will compute at each grid point how far it is to the closest valid point below this coordinate position on the indicated axis. The distance will be reported in terms of the number of points (distance in index space). If a given grid point is valid (not missing) then the result of @CIB for that point will be 0.0.
  
  
• new regrid transformation
• G=@XACT (exact coordinate match)
  
  Regridding with G=@XACT (or GX=@XACT, etc.) is a request to transfer values from asource grid to adestination grid only at those positions where there is an exact coordinate match between the source and destination axis points on the axis in question. Other destination points will be set to "missing". This transformation is especially useful for taking multiple in-situ data profiles, such as oceanographic cast data, and regridding them onto a regular (sparse) grid.
  
  Example:
  

LET xcoarse = sin(x[x=0:20:10])
LIST xcoarse
             SIN(X[X=0:20:10])
 0    / 1:  0.0000
 10   / 2: -0.5440
 20   / 3:  0.9129
 
DEFINE AXIS/X=0:20:5 xfine
LIST xcoarse[gx=xfine@XACT]
             SIN(X[X=0:20:10])
             regrid: 5 delta on X@XACT
 0    / 1:  0.0000
 5    / 2:    ....
 10   / 3: -0.5440
 15   / 4:    ....
 20   / 5:  0.9129
 

• Negative time axis values are supported
• DEFINE AXIS/unit=MONTHS will issue a warning
• variable name length increased
• In a NetCDF file any "Y" in the name of an axis caused it to be identified (mistakenly in some cases) as a Y axis

• regridding with @mod no longer drops the final subscript
• NetCDF time units which lack hours are now supported: e.g. time:units="hours since 1992-10-8 0"
• definite integral @DIN in ZT plane used COS(y) correction filler transformations (e.g. @FLN) return original field when component range is insufficient (at edges of field)