This document includes:
NOTE: See significant additions to capabilities in V5.4
The NetCDF conventions document discusses and defines usage for different calendar axes. See:
http://www.cgd.ucar.edu/cms/eaton/netcdf/merge_current.html#calThe NetCDF conventions recommend that the calendar be specified by the attribute calendar which is assigned to the time coordinate variable. These conventions for calendars are implemented in Ferret version 5.3 The calendars defined are: Gregorian (the default), noleap (365 day years), Julian (every four years is leap year), 360day (years are 360 days divided into 30-day months). These calendars are compatible with the Udunits standard which has slightly different naming conventions.
NetCDF files use the attribute time:calendar when there is a non-Gregorian calendar associated with a data set, i.e.
time:calendar=noleapExample: Define a calendar axis, regrid an existing variable to this axis:
yes? DEFINE AXIS/CALENDAR=360DAY/T="15-JAN-1982":"15-DEC-1985":30/UNITS=days tmodel
yes? LET twind = uwnd[GT=tmodel@NRST]When regridding from one calendar axis to another the length of a year is assumed to be constant, therefore the regridding calculates a scale factor based on the length of a second in each calendar, computed from the number of seconds per year for the calendars.
yes? let a = {system:"ls"}
yes? list a
{SYSTEM:"ls"}
1 / 1:"TutorialModels98.zip"
2 / 2:"ferret.jnl"
3 / 3:"movies.zip"
4 / 4:"movies1.zip"
5 / 5:"movies2.zip"
6 / 6:"movies3.zip"
7 / 7:"roseent8054c_timelocked2.exe"
8 / 8:"tutorial.zip"
XBOXLO, XBOXHI, YBOXLO, ... reveal the grid cell lower and upper bounds explicitly
enhanced to show lower bound of each grid cellSHOW GRID, SET GRID, DEFINE GRID/LIKE= and SET VAR/GRID= can take expressions as arguments
These may be formatted with w=width or zw=zero-filled width. For exampleyes? SAY Answer: `5.3,w=8`
Answer: 5.3
yes? SAY Answer: `5.3,zw=8`
Answer: 000005.3
Nearest coordinate regridding VAR[GX=newaxis@NRST] chooses the value from the source axis coordinate closest to the destination axis. If source coordinates above and below are equally close to a destination coordinate the value at the lower coordinate will be chosen. (This is most useful for regridding between axes whose coordinate values are very close, though not exactly matched -- e.g. between equally and unequally spaced monthly time axes.)
Command lines ending with back slash are regarded as incomplete -- a special prompt is given to indicate that the next line is a continuation .The length of the command buffer is increased to 2048 charactersExample:
yes? let a = 123 + 456 + \
...? 789
yes? list a
123 + 456 + 789
1368.
For example, if you wanted to know the maximum value of the second wave, where (say) rising above a magnitude of 0.1 in variable "ht" represented the onset of a wave, then
yes? let wave2_mask = IF ht[T=@evnt:0.1] EQ 2 THEN 1
is a mask for the second wave, only. The maximum wave height may be found with
yes? let wave2_ht = wave2_mask * ht
yes? let wave2_max_ht = wave2_ht[T=@max]
Note that @EVNT can be used together with @LOC and @WEQ to determine the location when an event occurs and the value of other variables as the event occurs, respectively. Since there may be missing values in the data, and since the instant at which the event occurs may lie immediately before the step in value for the event mask, the following expression is a general solution.
yes? let event_mask = my_var[t=@evnt:<value>]
yes? let event_n = IF ABS(MISSING(event_mask[L=@SBX],event_mask)-n)
LE 0.67 THEN
my_var
So that
event_n[t=@loc:<value>] is the
time at which event "n" occurs
and
event_n[t=@weq:<value>] is the
integrating kernel (see @WEQ)
This is effectively a RENAME command -- applies to all classes of variables (not pseudo-variables). Useful for "repairing" variables whose definitions are inadequate as-is but whose variable names are significant. A common application of this is in creating output NetCDF files in which contain modified versions of variables from input files.NetCDF time axes encoded as year 0000 or 0001 are automatically flagged as modulo
REPEAT/ANIMATE[/LOOP=n]
is used to start an animation sequence. Given LOOP=n, the animation sequence will repeat n times.Example:
yes? set data coads_climatology
yes? repeat/l=1:12/animate/loop=5 (shade sst; go fland)NOTE: In order to properly display on SGI's, it is necessary to have backing store enabled for the Xserver.
(in beta versions this was named STREAKLINE). A new qualifier to the VECTOR command VECTOR/FLOWLINE (alias FLOWLINE) draws continuous flowlines from the vector components U and V. The qualifier /DENSITY controls the number of lines drawn. There is also a 4-argument form of this command for drawing flowlines in curvilinear coordinates. Note that Ferret does not compute a stream function, but draws a pathline integration of a 2-dimensional instantaneous flow field. In a 3-dimensional flow field the plots are only useful as a qualitative visualization tool.Example:
yes? USE coads_climatology
yes? SET REGION/x=150e:130w/y=40s:50n/l=6
yes? FLOW/DENSITY=4 uwnd,vwndThe underlying algorithm is used with permission from the GrADS program. Our thanks to COLA, the Center for Ocean-Land-Atmosphere Studies, for access to this technique.
PLOT/STEP and PLOT/STEP=connected
These qualifiers give a plot style that is consistent with grid cell interpretation of data. Especially useful for time series to show the span of each time bin.
Note that setting axtype with a PPLUS call before the plot call will not result in a log plot, though making an axtype setting with PLOT/SET_UP still works as in previous versions.
new syntax:
yes? PLOT/VLOG/VLIMITS=10:1000 my_ fcn
! plots a function on a log axis
replaces older syntax:
yes? ppl axtype 1, 3
yes? PLOT/VLIMITS=1:3 my_fcn
! This will NOT produce a log plot, as the
! PLOT command resets the status of the axes.
yes? PLOT/SET_UP/vlimits=1:3
my_fcn ! These commands duplicates the new syntax.
yes? ppl axtype, 1, 3
yes? ppl plot
For 2-dimensional CONTOUR, FILL, or SHADE plots, you must set up log plotting
manually as in the FAQ
How can I make a 2D log (or log-log) plot?
SET DATA/FORMAT=DELIMITED[/DELIMITERS=][/TYPE=][/VAR=] filenameinitializes a file of mixed numerical, string, and date fields. If the data types are not specified the file will be analyzed automatically to determine data types. Using delimited files, the number of variables that can be read from a single file is increased from 20 to 100.
The alias COLUMNS stands for "SET DATA/FORMAT=DELIMITED"
/DELIMITER - list of field delimiters. Default is tab or comma e.g. /DELIM="X,\t,\,"
special characters include/TYPE is the list of data types of the fields. Field types may be any of\b - blank \t - tab \n - newline \nnn - decimal value from ASCII table "-" - skipped NUMERIC TEXT LATITUDE - e.g. 87S or 21.5N (interpreted as negative or positive, respectively) LONGITUDE - e.g. 160W or 30E (interpreted as negative or positive, respectively) DATE - e.g. mm/dd/yy or mm/dd/yyyy or yyyy-mm-dd or yyyymmdd - value returned is days from 1-jan-1900 (consistent with the DAYS1900 function)
EURODATE - e.g. dd/mm/yy or dd/mm/yyyy or yyyy-mm-dd TIME - e.g. hh:mm or hh:mm:ss.s
Previous to version 5.2 Ferret performs sanity checking on an MC data set by comparing the time coordinates with those found in the data files as the data are read. In version 5.3 and higher no sanity checks are performed. This means that the MC descriptor mechanism can be used to associate into time series groups of files that are not internally self documenting with respect to time, however, it also shifts an additional burden onto the user of carefully checking the validity of the STEPFILE records in the descriptor files. Also note there is enhanced documentation of MC descriptors in the Users Guide, Chapter 10 sec 4.
This allows for long file pathnames and DODS filenames in MC datasets.Performance of NetCDF "SAVE/APPEND ..." greatly increased for large file output
Support for command files created by Windows (embedded CR characters)
Files written by Windows software have embedded carriage return characters. Journal files with this formatting can now be read by Ferret.
These functions are similar to ZAXREPLACE but use other regridding methods to replace a Z axisArguments to EOF functions changed.ZAXREPLACE_AVG(V,ZVALS,ZAX)
Use weighted averaging to convert between alternative monotonic Z axes. The weighting is
done according to the portion of the source box that lies within the destination grid cell.ZAXREPLACE_BIN(V,ZVALS,ZAX)
Use unweighted averaging to convert between alternative monotonic Z axes. The function
finds the source points within each destination box and averages them.
The second argument in previous versions has been removed. This argument had the functions scale and return only EOF spatial and time functions up to a given percent variance explained. However this didn't save much computation. The functions now return all the EOF's.
yes? SHOW FUNCTION eof_* EOF_SPACE(A,frac_timeser) Compute EOF spacial fields from XYT field A: Variable in x,y,t; may be fcn of z frac_timeser: Use only those time series with this fraction valid data EOF_STAT(A,frac_timeser) EOF statistics from XYT field. j=1:#EOFs, j=2:%variation,j=3:eigenvalues A: Variable in x,y,t; may be fcn of z frac_timeser: Use only those time series with this fraction valid data EOF_TFUNC(A,frac_timeser) Compute EOF time functions from XYT field. A: Variable in x,y,t; may be fcn of z frac_timeser: Use only those time series with this fraction valid data
yes? LET a = {"s1","s2", ,"s3"}
yes? LIST a
yes? SAVE/CLOBBER/FILE=test_string.cdf/HEADING=enhanced
a[i=2:4]
yes? LIST a[i=@shf]
The features of DODS 3.2 include
Strides can be applied across the "branch point" of a modulo variable without loss of efficiency for NetCDF data set, as long as the stride is an integer fraction of the modulo length* (the number of points on the axis)Nesting of GO files is no longer limited to 10 deep.
Ferret now supports up to 200 deep, but typically you will limited to fewer by Unix itself.New qualifiers EXIT/LOOP, EXIT/SCRIPT, EXIT/PROMPT, EXIT/PROGRAM
EXIT/LOOP exit from current repeat loop
EXIT/SCRIPT exit from current script
EXIT/PROMPT exit to Ferret prompt
EXIT/PROGRAM exit program completely"QUIT" in a command file is an alias for EXIT without a qualifier. It will exit the current script, or the program if you are at the Ferret prompt.
New option for defining
viewports, DEFINE VIEW/AXES
Allows the user precise control over the position of plots in viewports. Here the user's limits are interpreted as the normalized positions of the plot axes rather than of the entire viewport. For example:Doubled the default memory to 6.4 Mwordsyes? DEFINE VIEWPORT/AXES/XLIM=0.5:1/YLIM=0:0.5 lraxNotes:
yes? SET VIEW lrax
yes? PLOT/VS/LINE/I=1:314 i*cos(i/20),i*sin(i/20); pause
yes? PLOT/VS/LINE/NOYADJUST/I=1:314 i*cos(i/20),i*sin(i/20)
- Can change PPL ORIGIN and PPL AXLEN only after SET VIEW is issued
- Use new qualifier PLOT/NOYADJUST to avoid resetting the Y origin -- relevant during PLOT commands that require extra room for a large key block under the axes or for viewports that lie close to the bottom of the window where there may not be much room below the Y axis
Recall that you can always change the memory at startup with the -memsize option, or during a Ferret session with the SET MEMORY command.Plotting is no longer limited by a fixed plot memory buffer.
Memory for plotting is allocated as needed. Previously there was a fixed memory buffer used for plotting.
Control of dashed lines
with PLOT/DASH[=dn1,up1,dn2,up2]
This allows use of all the color and thickness controls available with the PLOT qualifiers and control over the dash characteristics using the arguments as in the PPLUS "LINE" command: DOWN1, UP1, DOWN2, UP2 in inches.New plot qualifier /AXES[=top,bottom,left,right]Example:
plot/dash/i=1:100 sin(i/5)
plot/over/dash=(0.3,0.1,0.3,0.1)/color=red/thick/i=1:100 sin(i/7)
plot/over/dash=(0.6,0.2,0.1,0.2)/color=blue/thick=1/i=1:1000 sin(i/9)
For all plot commands, turns plotting of individual axes off and on. This is equivalent to the "PPL AXSET" command. The syntax isPLOT/AXES[=top,bottom,left,right] where the arguments are 1 to turn the axis on and 0 to turn it off. For example:
CONTOUR/AXES=0,1,1,0 sst ! Plots the bottom and left axes onlyOne can still use the "ppl axset" command to turn axes off or on, and that setting will persist from one plot to another in a script. The "ppl axset" setting will be restored after a PLOT/AXES= plot is drawn. For example:PPL AXSET 0,0,0,0
PLOT/i=1:12 1./i ! no axes drawn
PLOT/i=1:100/AXES=1,0,0,1 sin(i) ! top and right axes drawn
SHADE/i=1:10/j=1:5 i+j ! no axes drawnMakes a dot at each point. This implements the GKS "dot" polymarker, which uses the smallest dot that can be represented on the display device (Note the dots may not show up well on all devices).New functions COMPRESS*_BY Compress data according to a maskCOMPRESSI_BY (var, mask), COMPRESSJ_BY (var, mask), COMPRESSK_BY (var, mask), COMPRESSL_BY (var, mask)Compress variable "dat" along its I (or J, K, or L) axis using the (multi-dimensional) mask supplied in the second argument.Modified heading output of LIST command
For example:yes? LET mask = {1,,1,,1} + 0*L[l=101:102] + 0*K[k=10:11]
yes? LIST mask
{1,,1,,1} + 0*L[L=101:102] + 0*K[K=10:11]
1 2 3 4 5
1 2 3 4 5
---- L:101 T: 101
10 / 10: 1.000 .... 1.000 .... 1.000
11 / 11: 1.000 .... 1.000 .... 1.000
---- L:102 T: 102
10 / 10: 1.000 .... 1.000 .... 1.000
11 / 11: 1.000 .... 1.000 .... 1.000yes? LIST compressi_by({11,22,33,44,55},mask)
COMPRESSI_BY({11,22,33,44,55},MASK)
1 2 3 4 5
1 2 3 4 5
---- L:101 T: 101
10 / 10: 11.00 33.00 55.00 .... ....
11 / 11: 11.00 33.00 55.00 .... ....
---- L:102 T: 102
10 / 10: 11.00 33.00 55.00 .... ....
11 / 11: 11.00 33.00 55.00 .... ....New lines list the file name and path, and complete information on the subset of the data being listed. See the next section on LIST/WIDTH for an example.New qualifier: LIST/WIDTH=columnsFor multi-column output, controls the width of the listing on the page, for example:Allow the qualifier /TITLE for DODS or NetCDF datasetsyes? USE coads_climatology
yes? LIST/L=1/WIDTH=50/Y=0:4 sst
VARIABLE : SEA SURFACE TEMPERATURE (Deg C)
DATA SET : COADS Monthly Climatology (1946-1989)
FILENAME : coads_climatology.des
FILEPATH : /home/ja9/tmap/fer_dsets/descr/
SUBSET : 180 by 2 points (LONGITUDE-LATITUDE)
TIME : 16-JAN 06:00
... listing every 36th point
21E 93E 165E 123W 51W
1 37 73 109 145
3N / 47: .... 28.30 29.04 25.36 27.49
1N / 46: .... 28.29 29.12 24.82 27.49yes? LIST/L=1/WIDTH=80/Y=0:4 sst
VARIABLE : SEA SURFACE TEMPERATURE (Deg C)
DATA SET : COADS Monthly Climatology (1946-1989)
FILENAME : coads_climatology.des
FILEPATH : /home/ja9/tmap/fer_dsets/descr/
SUBSET : 180 by 2 points (LONGITUDE-LATITUDE)
TIME : 16-JAN 06:00
... listing every 18th point
21E 57E 93E 129E 165E 159W 123W 87W 51W 15W
1 19 37 55 73 91 109 127 145 163
3N / 47: .... 27.42 28.30 28.10 29.04 27.30 25.36 27.08 27.49 27.90
1N / 46: .... 27.67 28.29 28.48 29.12 26.62 24.82 25.82 27.49 27.41
SET DATA/TITLE associates a title with a dataset (previously not allowed for these file types.)includes the PlotPlus manual and Ferret-specific PPLUS enhancements Guide as appendices. Some cross-references and index entries are included; more will be added. New Ferret Users' Guide
PPLUS Symbol and Font tables are linked to the Documentation webpagePPLUS Character Fonts
PPLUS Symbol FontsKnown bugs in Version 5.4
- Installation note: Error messages about libXm.so.2: cannot open shared object file Indicates that X motif libraries are not loaded on your linux system.
- NOTE: The -gui startup option is not supported. Some features of Ferret may not work in the -gui mode.
- "**ERROR: illegal data type (float,string,...) for operation:" may occur for graphical operations on expressions involving IF--THEN.
- Strides at the IO level may result in improper wrapping of data (highly visible corruption).
- FILL/VLIM/HLIM var, does not properly fill in the requested region, when VAR is on an irregular grid.
- Ferret hangs when attempting to access invalid DODS URLS
- Nested REPEATs involving parentheses are parsed incorrectly.
- /HLOG and /VLOG qualifiers should NOT be on the CONTOUR command.
Backwards compatibility issues:
- PPL AXLABP when issued before a plot command does not remove the labels from the axes.
- Argument syntax in go tools.
- Single quotes in argument to MESSAGE (SAY) command.
Bug descriptions:
- Installation note: Error messages about libXm.so.2: cannot open shared object file
After installing, when you try to run Ferret, you see the error messages
/usr/local/ferret/bin/ferret: error while loading shared libraries:
libXm.so.2: cannot open shared object file: No such file or directory
This indicates that the X motif libraries are not loaded on your linux system. You can find Xmotif (free software) at: http://www.opengroup.org/openmotif/. Installing these libraries should solve the problem. Future Ferret versions will have static versions of these libraries linked in with the executable.
- NOTE: The -gui startup option is not supported. Some features of Ferret may not work in the -gui mode.
- "**ERROR: illegal data type (float,string,...) for operation:" may occur for graphical operations on expressions involving IF--THEN. Work-around: Typically, if the same command is given a second time Ferret will execute it correctly. If that fails, then try reducing the complexities of the "IF" clause to a separate variable -- e.g. replace "SHADE IF (a LT 5 AND b GT 15) THEN ..." with "LET c = a LT 5 AND b GT 15; SHADE IF c THEN ..."
example:
DEFINE AXIS/X=0:359:1/MODULO/UNIT=longitude lon
LET A = IF (X[GX=lon] GE -10) THEN 1
PLOT a ! --->error
- Strides at the IO level may result in improper wrapping of data (highly visible corruption). (lo:hi:delta -- eg. "my_netCDF_variable[i=1:1024:4]") This can occur when these strides are combined with automatic axis reversal, either through a NetCDF file in which coordinates are in decreasing order or through the use of USE/ORDER= and only in association with large memory requests (exceeding the size of a memory block as shown in SHOW MEMORY/FREE).
Workaround: the use of strides at the NetCDF IO level may be avoided by applying the strides to a user-defined variable. In the example above, let my_var = my_netCDF_variable and then use my_var[i=1:1024:4].
- FILL/VLIM/HLIM var, does not properly fill in the requested region, when VAR is on an irregular grid.
yes? use levitus_climatology
yes? fill/x=180/vlim=112:212/hlim=47:80 temp
A workaround is to specify a region explicitly, or use FILL/Z=112:212/Y=47:80
yes? fill/x=180/z=112:212/y=47:80/vlim=112:212/hlim=47:80 temp
- Ferret hangs when attempting to access invalid DODS URLS
Whenever an attempt is made to open an invalid DODS URL in Ferret, Ferret will hang. Invalid URL's include datasets which don't exist, or datasets served by DODS servers which are currently unavailable. The only way around this bug is to ensure that DODS URLS are typed correctly and/or the requested DODS servers are available. We are working with the DODS group to fix this bug.- Nested REPEATs are parsed incorrectly when the commands are in parentheses, resulting in a stack overflow
yes? REPEAT/K=1:2 (REPEAT/L=1 say hello) ! works fine
yes? REPEAT/K=1:2 (REPEAT/L=1 (say hello)) ! stack overflow
Workaround: If you must have the parentheses inside a nested REPEAT, place the commands in a script, and call that from the innermost loop.
- /HLOG and /VLOG qualifiers should NOT be on the CONTOUR command.
The PPLUS command AXTYPE, 2,2 command was implemented as command-line options /HLOG and /VLOG. The transformation of the coordinates is only done by PPLUS for 1-dimensional plots, so CONTOUR/HLOG /VLOG plots untransformed data with meaningless log axes. To do log plots for 2-dimensional data, see the FAQ, How can I make a 2D log (or log-log) plot?
- Backwards compatibility issue: PPL AXLABP when issued before a plot command does not remove the labels from the axes.
yes? ppl axlabp 0 0
yes? plot my_var ! Axes still have labels
Workaround: use the /set_up qualifier and issue the ppl axlabp command...
yes? plot/set_up my_var
yes? ppl axlabp 0, 0
yes? ppl plot
The old behavior will be restored in future versions of Ferret.
- Backwards compatibility issue: Argument syntax in go tools. ($1) within the script needs an extra set of parentheses to be sure of getting the correct interpretation, e.g. in a script you need to use XSEQUENCE(($1)). See the item above "Up to 99 arguments for GO commands using either $nn or ($nn) syntax"
- Backwards compatibility issue: Single quotes in argument to MESSAGE (SAY) command Previously one could issue a command
yes? SAY It's good data
This now results in an error regarding unpaired quotes (due to changes that allow enhanced support for string variables). A workaround is to put the string in double quotes:
yes? SAY "It's good data"
14-Feb-2002
404 Not Found Not Found
The requested URL "/footer.txt" was not found on this server.