Ferret v6.02 release notes

# Ferret Version 6.02 Release Notes

27-April-2007

Version 6.02 is primarily a bug-fix release.

## New Features and Enhancements in Version 6.02

- Native strides for netCDF file access.
- Enhanced BATCH mode, in which we can create multiple metafiles.
- New RETURN=xmod, RETURN=tmod to get the modulo character of a grid.
- Axis names preserved on netCDF output
- Improvements to ASCII list output

## Bug Fixes in Version 6.02

- Changes made by SET VAR/TITLE=/UNITS= were not saved in output file
- Changes made by SET or DEFINE or CANCEL AXIS were not available to the attribute-access commands
- Long strings in symbols are now allowed
- The global missing-value flag was not set for some datasets
- `var[d=fname.cdf],RETURN=size` failed
- Parsing error when there was a tab before a comment
- Plot was mis-labelled when variable had no long_name attribute
- "** netCDF error: Variable not found" when writing data with irregular axes
- Vectors on VECTOR/ASPECT plots pointed in the wrong direction.
- Error message when saving variables with the same time axis to a file.
- Error checking irregular axis failed, some axes.
- Error listing a string variable when the last element is missing
- (32-bit linux only) Error listing a string variable when the last element is missing

## New Features and Enhancements in Version 6.02

- Native strides for netCDF file access. This lets us keep the original names of variables, while defining striding for faster access of data on large grids. The syntax is

         yes? SET AXIS/STRIDE=[/OFFSET=] axisname
         yes? CANCEL AXIS/STRIDE  axisname

  For example,

         yes? SET DATA "http://iridl.ldeo.columbia.edu/SOURCES/.NOAA/.NGDC/.ETOPO5/dods"
         yes? SHOW DATA
              currently SET data sets:
             1> http://iridl.ldeo.columbia.edu/SOURCES/.NOAA/.NGDC/.ETOPO5/dods  (default)
          name     title                             I         J         K         L
          ELEV     elevation/bathymetry             1:4320    1:2160    ...       ...

         yes? SET AXIS/STRIDE=5 `elev,RETURN=xaxis`
         yes? sET AXIS/STRIDE=5 `elev,RETURN=yaxis`
         yes? SHOW GRID elev
             GRID GCR1
          name       axis              # pts   start                end
          (AX004)   LONGITUDE          864mr   0E                   0.41699W(359.58)
          (AX005)   LATITUDE           432 i   89.916S              89.666N
          normal    Z
          normal    T

  This is equivalent to the older (but still valid) striding syntax, which required us to define a new variable

         yes? SET DATA "http://iridl.ldeo.columbia.edu/SOURCES/.NOAA/.NGDC/.ETOPO5/dods"
         yes? LET strided_elev = elev[i=1:4320:5,j=1:2160:5]

  Now the data can be used as if it is on the smaller grid. If we want to resume use of the original grid,

         yes? CANCEL AXIS/STRIDE `elev,RETURN=xaxis`
         yes? CANCEL AXIS/STRIDE `elev,RETURN=yaxis`

  The offset if specified must be smaller than the stride. If a stride is not specified this qualifier is ignored. The OFFSET value refers to the first point to keep, i.e. these two command would define the same striding in X:

         yes? SET AXIS/STRIDE=5/OFFSET=2 `elev,RETURN=xaxis`
         yes? LET strided_elev = elev[i=2:4320:5]

  For example,

         yes? USE coads_climatology
         yes? LIST sst[X=61:79,J=50,K=1,L=50]
                      VARIABLE : SEA SURFACE TEMPERATURE (Deg C)
                      FILENAME : coads_climatology.cdf
                      SUBSET   : 10 points (LONGITUDE)
                      LATITUDE : 9N
                      TIME     : 15-FEB-0012 14:19
                        9N
                        50
          61E   / 21:  26.86
          63E   / 22:  27.00
          65E   / 23:  27.29
          67E   / 24:  27.69
          69E   / 25:  27.93
          71E   / 26:  28.08
          73E   / 27:  28.23
          75E   / 28:  28.32
          77E   / 29:  28.23
          79E   / 30:  27.82

         yes? SET AXIS/STRIDE=4/OFFSET=2 `sst, return=xaxis`
          !-> SET AXIS/STRIDE=4/OFFSET=2 COADSX

         yes? LIST sst[X=61:79,J=50,K=1,L=50]
                      VARIABLE : SEA SURFACE TEMPERATURE (Deg C)
                      FILENAME : coads_climatology.cdf
                      SUBSET   : 3 points (LONGITUDE)
                      LATITUDE : 9N
                      TIME     : 15-FEB-0012 14:19
                       9N
                       50
          63E   / 6:  27.00
          71E   / 7:  28.08
          79E   / 8:  27.82

  This acts on the axis, so variables that share an axis, whether they come from a single dataset or several datasets that use the same exact axis, will all be affected by the strides.
- Enhanced BATCH mode, in which we can create multiple metafiles.

  Start Ferret with

         > ferret -batch myfile.plt

  When in this batch mode, xwindows are not used, and a new myfile.plt.~*~ file is started with each new plot "page" that we'd see when running interactively.

  The following commands are ignored

  - SET MODE METAFILE
  - CANCEL MODE METAFILE
  - SET WINDOW ! except for
  - SET WINDOW/ASPECT applies the new aspect ratio
  - SET WINDOW/CLEAR starts a new metafile

  New plots may be started with these commands

  - New plot command (if we are not in a viewport and not overlaying)
    PLOT,CONTOUR,SHADE,FILL,VECTOR,CONTOUR
  - CANCEL VIEWPORT
  - SET WINDOW/CLEAR
  - PPLUS/RESET

  Note that there is still a choice of output graphics type when starting Ferret with -batch. Only one type may be chosen.

      > ferret -batch metafiles.plt  ! metafile

      > ferret -batch psfiles.ps     ! postscript

      > ferret -gif                  ! gif output

  In -gif mode, recall that we must use use FRAME/FILE= commands to create each gif image files.
- New RETURN=xmod, RETURN=tmod to get the modulo character of a grid. It returns the modulo length of the axis in the units of the axis.

         yes? USE coads_climatology
         yes? SAY `sst,RETURN=xmod`
          !-> MESSAGE/CONTINUE 360
         360

         yes? SAY `sst,RETURN=tmod`
          !-> MESSAGE/CONTINUE 8765.8
         8765.8

         yes? SAY `sst,RETURN=tunits`
          !-> MESSAGE/CONTINUE hour
         hour

- New attribute available, orig_file_axname

  When initializing a dataset, if Ferret encounters an axis name that's already in use, it creates a new name by adding a digit, e.g. if TEMP is already in the list of axis names, then it uses TEMP1 for the new data for uniqueness. When this happens, we continue to new name with the dataset attribute information, and add an attribute orig_file_axname containing the original name. That original name is used on output to a netCDF file.

      yes? DEFINE AXIS/T=1:5:1 time  ! create an axis called TIME
      yes? USE coads_climatology     ! there is also a TIME axis in this dataset

      yes? show grid sst  ! The time axis is called TIME1
          GRID GSQ1
       name       axis              # pts   start                end
       COADSX    LONGITUDE          180mr   21E                  19E(379)
       COADSY    LATITUDE            90 r   89S                  89N
       normal    Z
       TIME1     TIME                 3mr   16-JAN 06:00         17-MAR 02:58

      yes? ! Ferret automatically defines an attribute orig_file_axname
      yes? SHOW ATTRIBUTE (TIME1).orig_file_axname
           attributes for dataset: ./coads_climatology.cdf
       (TIME1).orig_file_axname = TIME

      yes? SAVE/FILE=a.nc/X=181/Y=1 sst  ! This file has the time axis named TIME

- Improvements to ASCII list output

  When data contains missing values, LIST/FORMAT=comma or LIST/FORMAT=tab now writes a comma or tab as placeholder for the missing value. Previously these listings were ambiguous.

      yes? LET a = {1,1,,1,1,,1,1}
      yes? LET b = {4,4,4,4,4,4,4,4}
      yes? LIST/FORM=comma a,b
                   X: 0.5 to 8.5
       Column  1: A is {1,1,,1,1,,1,1}
       Column  2: B is {4,4,4,4,4,4,4,4}
             A,B
      1   / 1:1,4
      2   / 2:1,4
      3   / 3:,4
      4   / 4:1,4
      5   / 5:1,4
      6   / 6:,4
      7   / 7:1,4
      8   / 8:1,4

## Bug fixes in Version 6.02

- Changes made by SET VAR/TITLE=/UNITS= were not saved in output file

         yes? USE mydat.nc
         yes? LIST/Y=1/K=1/L=1 temp  !See the title and units
                      VARIABLE : TEMPERATURE (deg. C)
                      FILENAME : mydat.cdf
                      SUBSET   : 3 points (LONGITUDE)
                      LATITUDE : 0.8N
                      DEPTH (m): 5
                      TIME     : 15-MAR-1983 10:00
                         0.83N
                         48
          160.5W / 70:  31.20
          159.5W / 71:  31.34
          158.5W / 72:  31.45

         yes? ! Make changes to variable with SET VARIABLE
         yes? SET VAR/TITLE="Temp"/units="DegC" temp

         yes? SAVE/FILE=a.nc/CLOBBER temp

         yes? CANCEL DATA/ALL
         yes? USE a.nc

         yes? ! The file has the NEW var title and units
         yes?  lIST/Y=1/K=1/L=1 temp
                      VARIABLE : Temp (DegC)
                      FILENAME : a.nc
                      SUBSET   : 3 points (LONGITUDE)
      ...

- Changes made by SET AXIS or DEFINE AXIS were not available to the attribute-access commands

         yes? USE mydat.nc  ! a dataset whose time axis needs changes

         yes? ! Use DEFINE AXIS to redefine it.
         yes? SET AXIS/T0="1-jan-2004"/UNITS=days `temp,RETURN=taxis`

         yes? ! We can make further chages with SET AXIS

         yes? SET AXIS/MODULO/CALENDAR=noleap `temp,RETURN=taxis`
         yes? SHOW ATT/ALL  `temp,RETURN=taxis`

          !-> SHOW ATT/ALL  TIME
           attributes for dataset: ./mydat.nc
       (TIME).units = DAYS
       (TIME).time_origin = 1-JAN-2004
       (TIME).orig_file_axname = TIME
       (TIME).calendar = NOLEAP
       (TIME).modulo =

         yes? ! CANCEL AXIS may also be used to change axis features

         yes? CANCEL AXIS/MODULO `temp,RETURN=taxis`
         yes? SHOW DATA/ATT  ! see dataset with all the attributes
           currently SET data sets:
          1> ./mydat.nc  (default)
       VARIABLE               ATTRIBUTE NAME      TYPE    SIZE OUTFLAG VALUE
      --------------------------------------------------------------------------------
      ...
         (TIME)               units               CHAR    4    T      DAYS
                              time_origin         CHAR    10   T      1-JAN-2004
                              orig_file_axname    CHAR    4    F      TIME
                              calendar            CHAR    6    T      NOLEAP

- Long strings in symbols: Previously the value of a symbol was cut off at 255 characters. Now they may be up to 2048 characters.
- The global missing-value flag was not set for some datasets; if a netCDF file has no global attributes, and the variables do not have missing-value attributes, the missing data flag was set to 0. This is fixed; Ferret's default missing value of -1eE+34 is used.
- `var[d=fname.cdf],RETURN=size` failed, when the filename included the dot and extension. This is fixed.
- Parsing error when there was a tab before a comment, the command-line parsing was thrown off and we got an error about an invalid ENDIF. This is fixed.
- Plot was mis-labelled when the variable had no long_name attribute, the plot had only the units label; now it is named with the variable name as well.
- Error message "** netCDF error: Variable not found" when writing data with irregular axes. These data are now written correctly with no messages.
- Vectors on VECTOR/ASPECT plots pointed in the wrong direction; this is fixed.
- Error message when saving variables with the same time axis to a file.

  The error message was

         " **TMAP ERR: attempt to redefine line
           axis TIME doesnt match CDF file

  This was a bug in matching the axis names, in the code that allows for CANCEL MODE UPCASE_OUTPUT. This is now fixed.
- Error checking irregular axis failed, some axes. Version 6.0 had a new method for checking whether axes are irregular, when initializing a netCDF data set. For axes whose coordinate spacing varies widely, this method failed, and the axis was designated regular. This is now fixed.
- Error listing a string variable when the last element is missing

      yes? LET a = {"a", "b",  }
      yes? LIST a
                   VARIABLE : {"a", "b",  }
                   SUBSET   : 3 points (X)
       1   / 1:"a"
       2   / 2:"b"
       3   / 3:""