Ferret Version 6.0 Release Notes
24-Aug-2006.
New Features and Enhancements in Version 6.0
- Access to and control over netCDF attributes.
- Control over output data types when writing netCDF files.
- New MODE UPCASE_OUTPUT controls netCDF output.
- New functions for determining if items are included in a list
- New ferret symbol FER_LAST_ERROR
- Correct OPeNDAP error messages
- New flexibility for defining an axis using BOUNDS
- A new qualifier LIST/NOROWHEAD for ASCII listings
- New external functions TAX_* return various conversions of time axis information
- Most functions previously distributed as external functions now statically linked
- Longitude or latitude labels on plot axes can be labelled with Degrees-Minutes-Seconds
Bug Fixes in Version 6.0
- LIST/FORMAT=tab or /FORMAT=comma now behave the same as LIST with default formatting
- LIST of string variables had stray characters in the listing; this is fixed.
- SHOW FUNCTIONS now correctly finds all external functions
- FILL plots of data with subspan-modulo axes got incorrect data when the region plotted was larger than the range of the data. This is fixed.
- In an IF block, Ferret attempted to parse commands even when they were not executed. This has been fixed.
- Errors with nonstandard calendar time axes are fixed
- _FillValue and missing_value flag now correctly applied to packed NetCDF data
- Improved computation of areas on the Earth.
- Polygon/line commands now work correctly on reversed axes
New Features and Enhancements in Version 6.0
- Access to and control over netCDF attributes.
With new syntax varname.attname we can access the numeric and string attributes of variables and
datasets. The ideas of netCDF attributes from the netCDF standards are extended to Ferret user-variables and variables from other
kinds of datasets.
Some of the capabilities are
! Make an expanded SHOW DATA listing with all the attribute information yes? SHOW DATA/ATTR ! List the value of an attribute yes? LIST var.units ! Find out the number of attributes a variable has yes? LET natt = var.nattrs ! Define a Ferret variable whose value is an attribute ! (This is the syntax for accessing a global attribute) yes? LET my_string = ..history ! Add an attribute, or redefine an existing one yes? DEFINE ATTRIBUTE var.units = "Degrees" ! Determine which attributes are written to netCDF files yes? SET ATTRIBUTE/output var.add_offset yes? SET ATTRIBUTE/output var.scale_factor
Full documentation may be found in the Users Guide, Ch3 Sec 1.8, Variable and dataset attributes. Look up "attributes" in the index.
- Control over output data types when writing netCDF files. As a consequence of the above control over attributes, we may now set the output data type for variables to be written to netCDF data files.
yes? SET DATA etopo60 yes? SET VAR/OUTTYPE=short rose yes? SAVE/X=180/FILE=r_int.nc rose
Note that Ferret still always converts data to single-precision floats on input, except for coordinate data which is represented internally as double-precision floating point. If a different output data type is requested, netCDF calls are used to convert floating-point data to the requested type.
Care must be taken to reset the missing value flag if needed so that its value may be represented in the output data type. Ferret will issue an error if the flag cannot be represented in the new type. For the above example we would have to change the missing-value flag for rose before the data could be written
yes? SET DATA etopo60 yes? SET VAR/OUTTYPE=short rose yes? SET ATTRIBUTE rose.missing_value = -20000 yes? SAVE/X=180/FILE=r_int.nc rose *** NOTE: Converting data type of missing_value NC_FLOAT to match output type of variable NC_SHORT - New MODE UPCASE_OUTPUT controls netCDF output.
Ferret has always converted variable names to uppercase when writing them to netCDF files. This behavior is
still the default, but if you wish to keep lowercase or mixed-case spelling of variable and attribute names
when they are written to netCDF files, issue the command
yes? CANCEL MODE UPCASE_OUTPUT
and the original upper- or lower-case spellings to be used.
- New functions for determining if items are included in a list
- IS_ELEMENT_OF(arg1, arg2) returns 1 if arg1 any element of arg2 matches any element of arg1 and 0 if there is no match.
- IS_ELEMENT_OF_STR same as IS_ELEMENT_OF but with string arguments
- ELEMENT_INDEX(arg1, arg2) Returns index value in ARG2 for each point in ARG1
- ELEMENT_INDEX_STR same as ELEMENT_INDEX but with string arguments
- New ferret symbol FER_LAST_ERROR contains the text that is output to standard error, from the last error that occurred. If it is a multi-line error, the symbol contains all the text from all the lines, strung together.
Example:
yes? SET DATA nofile.nc **TMAP ERR: non-existent or not on line nofile.nc yes? SHOW SYM FER_LAST_ERROR FER_LAST_ERROR = "**TMAP ERR: non-existent or not on line nofile.nc " - Correct OPeNDAP error messages are returned for attempts to access netCDF or OPeNDAP files.
- New flexibility for defining an axis using BOUNDS
In the command DEFINE AXIS/BOUNDS, the bounds on an axis may be specified either with a list of 2*N bounds
for the lower and upper bound of each grid cell, or with a list of the N+1 edges. These two definitions are
the same:
yes? DEF AXIS/X/BOUNDS xax = {1,2,5,6}, {0.5,1.5, 1.5,2.5, 2.5,5.5, 5.5,6.5} yes? DEF AXIS/X/BOUNDS xax = {1,2,5,6}, {0.5, 1.5, 2.5, 5.5, 6.5} - A new qualifier LIST/NOROWHEAD for ascii listings removes the coordinate labels from each row of output. See examples under LIST/FORMAT=tab or /FORMAT=comma
- New external functions TAX_* return various conversions of time axis information
tcoords - variable containing time values, e.g. t[gt=var,L=40:42]
var - variable from which time encoding will be inferred- TAX_YEAR(tcoords, var)
- returns year (integer)
- TAX_MONTH(tcoords, var)
- returns month (integer)
- TAX_DAY(tcoords, var)
- returns day of month (integer)
- TAX_DAYFRAC(tcoords, var)
- returns time of day as a [0,1] decimal value
e.g. HOUR=INT(TAX_DAYFRAC()*24)
- TAX_JDAY(tcoords, var)
- returns day number within current year
- TAX_JDAY1900(tcoords, var)
- returns day number since Jan. 1 1900
(matching DAYS1900 function)
- TAX_UNITS(var)
- returns unit conversions in seconds. 1=seconds, 60=minutes, ...
- TAX_YEARFRAC(tcoords, var)
- returns fraction of year as a decimal value in [0,1]
- TAX_DATESTRING(tcoords, var, prec)
- returns string of dates
- prec is the output precision, e.g. 'hour'.
- TAX_YEAR(tcoords, var)
yes? use "http://www.ferret.noaa.gov/cgi-bin/nph-dods/data/PMEL/smith_sandwell_topo_v8_2.nc" yes? fill/set/x=222.9:223.1/y=28.22:29.1 rose yes? ppl xfor (dm) yes? ppl yfor (dm) yes? ppl fill
To request degrees, minutes, and seconds the syntax is PPL XFOR (DMS) or PPL YFOR (DMS). Here is an example where two lists of points are defined as longitudes and latitudes and plotted using plot/vs, with degrees, minutes, and seconds on the Y axis.
yes? plot/vs/set/title="DMS on y axis"/vlim=2.28:2.4/hlim=144.5:144.8 xpts, ypts yes? ppl xfor (dm) yes? ppl yfor (dms) yes? ppl plot
the plot; on a horizontal axis they may overwrite one another. The margins may be adjusted by defining and plotting in a viewport or by the PPL XORG or PPL YORG commands; the tic interval may be changed with the PPL tics command.
Bug fixes in Version 6.0
- LIST/FORMAT=tab or /FORMAT=comma now behave the same as LIST with
default formatting. When multiple variables are specified, LIST/FORMAT=tab and LIST/FORMAT=comma used
to behave as if we had given a LIST/SINGLY command: each variable was listed separately, one after the
other.
Now, comma-delimited and tab-delimited formats are treated the same as automatically formatted LISTings for multiple variables. If we want the old behavior, then LIST/SINGLY/FORM=tab etc. can be specified. The header line listing the variable names uses the same delimiter between names. A new qualifier LIST/NOROWHEAD removes the coordinate labels from each row of output. For example
! Define some variables yes? let country = {"CN", "CN", "US"} yes? let id = {1,2,3} yes? let aa = 4000* id yes? let bb = 1000000* id + 500 ! List with default LIST formatting yes? LIST id, country, aa, bb X: 0.5 to 3.5 Column 1: ID is {1,2,3} Column 2: COUNTRY is {"CN", "CN", "US"} Column 3: AA is 4000* ID Column 4: BB is 1000000* ID + 500 ID COUN AA BB 1 / 1: 1.000 "CN" 4000. 1000500. 2 / 2: 2.000 "CN" 8000. 2000500. 3 / 3: 3.000 "US" 12000. 3000500. ! List with /COMMA formatting yes? LIST/FORMAT=COMMA id, country, aa, bb X: 0.5 to 3.5 Column 1: ID is {1,2,3} Column 2: COUNTRY is {"CN", "CN", "US"} Column 3: AA is 4000* ID Column 4: BB is 1000000* ID + 500 ID,COUNTRY,AA,BB 1 / 1:1,"CN",4000,1000500 2 / 2:2,"CN",8000,2000500 3 / 3:3,"US",12000,3000500 ! List with /TAB formatting yes? LIST/FORMAT=TAB id, country, aa, bb X: 0.5 to 3.5 Column 1: ID is {1,2,3} Column 2: COUNTRY is {"CN", "CN", "US"} Column 3: AA is 4000* ID Column 4: BB is 1000000* ID + 500 ID COUNTRY AA BB 1 / 1:1 "CN" 4000 1000500 2 / 2:2 "CN" 8000 2000500 3 / 3:3 "US" 12000 3000500 ! /NOROWHEAD removes the coordinate labels for each row yes? list/format=tab/NOROWHEAD id, country, aa, bb X: 0.5 to 3.5 Column 1: ID is {1,2,3} Column 2: COUNTRY is {"CN", "CN", "US"} Column 3: AA is 4000* ID Column 4: BB is 1000000* ID + 500 ID COUNTRY AA BB 1 "CN" 4000 1000500 2 "CN" 8000 2000500 3 "US" 12000 3000500 ! Or use /NOHEAD and /NOROWHEAD for no header at all yes? list/format=tab/NOROWHEAD/NOHEAD id, country, aa, bb 1 "CN" 4000 1000500 2 "CN" 8000 2000500 3 "US" 12000 3000500 - LIST of string variables had stray characters in the listing; this is fixed. (previously there was an extra N in the data lines below)
yes? list id, country X: 0.5 to 3.5 Column 1: ID is {1,2,3} Column 2: COUNTRY is {"CA", "CA", "US"} COUNTRY 1 / 1: 1.000N"CA" 2 / 2: 2.000N"CA" 3 / 3: 3.000N"US" ! Now, this listing is yes? list id, country X: 0.5 to 3.5 Column 1: ID is {1,2,3} Column 2: COUNTRY is {"CA", "CA", "US"} COUNTRY 1 / 1: 1.000 "CA" 2 / 2: 2.000 "CA" 3 / 3: 3.000 "US" - SHOW FUNCTIONS now correctly finds all external functions (The previous pattern matching could not match names with the wildcard at the start
yes? SHOW FUNC *date
Now correctly returns SAMPLET_DATE. - FILL plots of data with subspan-modulo axes got incorrect data when the region plotted was larger than the range of the data. This is fixed.
! create a dataset with subspan modulo x axis yes? set data coads_climatology yes? save/clobber/file=sst.nc/y=0/x=130e:80w sst yes? cancel dat/all yes? use sst.nc yes? set v left; shade/x=120e:80w sst yes? set v right; fill/x=120e:80w sst ! This plot was incorrect - In an IF block, Ferret attempted to parse commands even when they were not executed. e.g.
IF 0 THEN LET a = 12 IF `a` THEN say "variable a is defined" ENDIF ENDIFShould just skip all the contents of the IF. Instead it resulted in an error: "**ERROR: variable unknown or not in data set: A"
The entire contents of the IF 0 THEN is now skipped. - Errors with nonstandard calendar time axes are fixed.
When listing data from a dataset having a nonstandard calendar axis (calendars such as NOLEAP or 360_DAY), the dates listed were incorrect for some axes. This has been fixed.
- _FillValue and missing data applied incorrectly in packed NetCDF data
According to the CF conventions (2.5.1 Missing Data) the missing value flag
should be processed BEFORE data are unpacked (at least if the data type of the
flag matches the packed data type. Previously in Ferret the reverse was done. This is now fixed.
- Improved computation of areas on the Earth. Previously Ferret's area computations were
slightly too large. The difference is most pronounced on coarse grids. The previous correction used a simple
cosine(latitude) correction; the new computation implements the method discussed in
http://mathworld.wolfram.com/Zone.html
- Polygon/line commands now work correctly on reversed axes. Previously, POLYGON/FILL worked
correctly but POLYGON/LINE and POLYGON/LINE/FILL did not plot the lines, or plotted them in the wrong location.