National Oceanic and
Atmospheric Administration
United States Department of Commerce

Version 4.9 Release Notes

Last modified: Thu, 10/20/2011 - 07:35

Ferret Version 4.9 release notes

Release notes: Ferret Version 4.9

ferret@pmel.noaa.gov
New commands and qualifiers
Enhancements
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 itto 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="hourssince 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)
New commands and qualifiers
  • SHOW FUNCTIONS

    • The SHOW FUNCTIONS command now shows a complete list of thefunctions 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 a3-argument mode which allows them to create output in "curvilinear"coordinates. This allows for easy generation ofoutput plotsusing sigma coorindates as well as the application of variousmap 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) positionfor each (i,j) index pair. The page positions may be in any units; Ferret will scalethe plot according to the ranges of values in the position fields. For map projections, thesewill typically be defined by the map projection scripts as Ferret variablesas in the following section from the journal file for creatingLambert 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 forthe 3-argument commands will be the ranges of the position fields: inappropriate when map projections are being used. The /NOAXIS qualifier isprovided for this purpose.

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

    • The /NOAXIS qualifier causes the axes and axis labels to be omittedfrom the plot. (See the AXSET command in the PLOT+ Users Guide). The qualifierhas been added to support the curvilinear coordinate and map projectionscapabilities of the 3-argument versions of SHADE, FILL, and CONTOUR inwhich linear axes are inappropriate.

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

Enhancements 
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-yeartime 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 theaxes 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 argument1 is wrapped only within the indocated sub-range of those axis. For example,suppose the variable uwnd contains monthly data from Jan 1982to 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 wrappedonto the X and Y axes of the grid of argument B because both A and B sharedthe same X and Y axes.

      • ZAXREPLACE(V,ZVALS,ZAX)

        • The ZAXREPLACE function is a tool to convert between alternative monotonicZ axes, where the mapping between the source and destination Z axes isa function of X, Y, and or T. Typical applications in the field of oceanographyinclude converting from a Z axis of layer number to a Z axis in units ofdepth (e.g. for sigma coordinate fields) and converting from a Z axes ofdepth 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 variableis available on what we will refer to as the "source" Z-axis-- say in terms of layer number. The second argument, ZVALS, containsthe values of the desired destination Z axis defined on the source Z axis-- for example, it may contain the depth values associated with each verticallayer. It should always share the Z axis from the first argument. The thirdargument, ZAX, is defined on the destination Z axis. Only the Zaxis 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 functionto analyze sigma-coordinate fields see the FERRET FAQ entry, Howto 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 tothe closest valid point above this coordinate position on the indicatedaxis. The distance will be reported in the units of the axis. If a givengrid point is valid (not missing) then the result of @CDA for that pointwill be 0.0.

          • @CDB (closest distance below)

            The transformation @CDB will compute at each grid point how far it is tothe closest valid point below this coordinate position on the indicatedaxis. The distance will be reported in the units of the axis. If a givengrid point is valid (not missing) then the result of @CDB for that pointwill be 0.0.

          • @CIA (closest index above)

            The transformation @CIA will compute at each grid point how far it is tothe closest valid point above this coordinate position on the indicatedaxis. The distance will be reported in terms of the number of points (distancein index space). If a given grid point is valid (not missing) then theresult 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 tothe closest valid point below this coordinate position on the indicatedaxis. The distance will be reported in terms of the number of points (distancein index space). If a given grid point is valid (not missing) then theresult 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 valuesfrom asource grid to adestination grid only at those positions where thereis an exact coordinate match between the source and destination axis pointson the axis in question. Other destination points will be set to "missing".This transformation is especially useful for taking multiple in-situ dataprofiles, 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

            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 itto 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="hourssince 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)

            Last modified: Wed Nov 26 11:00:56 PST 1997