A quick way to get to know Ferret is to run the tutorial provided with the distribution.

% ferret
yes? GO tutorial

If Ferret is not yet installed consult the chapter "Computing Environment" (The tutorial is also available through the World Wide Web through Ferret's on-line demonstrations page.) The tutorial demonstrates many of Ferret's features, showing the user both the commands given and Ferret's textual and graphical output. You may find the explanations, terms and examples in this manual easier to understand after running the tutorial.

Words in bold below are defined in the glossary of this manual.

In Ferret all variables are regarded as defined on grids. The grids tell Ferret how to locate the data in space and time (or whatever the underlying units of the grid axes are). A collection of variables stored together on disk is a data set.

To access a variable Ferret must know its name, data set and the region of its grid that is desired. Regions may be specified as subscripts (indices) or in world coordinates. Data sets, after they have been pointed to with the SET DATA command (alias "USE"), may be referred to by data set number or name.

Using the LET command new variables may be created "from thin air" as abstract expressions or created from combinations of known variables as arbitrary expressions. If component variables in an expression are on different grids, then regridding may be applied simply by naming the desired grid.

The user need never explicitly tell Ferret to read data. From start to finish the sequence of operations needed to obtain results from Ferret is simply:

1) specify the data set

2) specify the region

3) define the desired variable or expression (optional)

4) request the output

For example (Figure 1_1),

yes? USE coads !global sea surface data
yes? SET REGION/Z=0/T="16-JAN-1982"/X=160E:160W/Y=20S:20N
yes? VECTOR uwnd,vwnd !wind velocity vector plot

(A discussion on the Ferret outlook on the concepts of data, variables, grids and other basics of Ferret.)

Plottable variables

For this discussion we will coin the term "plottable variables." There are no non-plottable variables that will come up in this discussion but "variables" is a bit too generic. Plottable variables are of 3 types:

• file variables – read from disk files
• user-defined variables – defined by the LET command
• pseudo-variables – regions (I,J,K,L,X,Y,...) used as variables

As much as possible Ferret tries to make all types of variables indistinguishable. All plottable variables are defined on grids. No plottable variables exists in a vacuum for Ferret. The grid on which a plottable variable exists tells how to locate the variable in space and time. In cases where the variables are abstract in nature—disconnected from space and time—Ferret will associate those variables with grids that are abstract, too. Where a geographical grid will associate the Nth position along an axis with a location (like 20 degrees north latitude) an abstract grid will simply associate the Nth position with the number N. Plottable variables may be regridded to other grids than the one on which they are defined. (Done with "G=".)

All references to plottable variables must have a complete context. A complete context will be described in detail later—briefly it means a region in space, an interval in time and the data set(s) in which the variables will be found.

Grids

All Ferret grids are 4-dimensional. In most cases the axes have the obvious interpretation of 3 space coordinates and time but sometimes the axes are abstract.

A grid is composed of 4 axes, each describing the coordinates along one dimension. 3d, 2d, 1d and 0d grids are regarded as special cases of the full 4 dimensions in which 1 or more axes are set to "NORMAL".

Ferret tries to look at all axes equally—the same syntax of regions and transformations applies to each. Calendar dates, east-west longitudes and north-south latitudes are merely convenient ways to format positions along axes that have special interpretations to people—not to Ferret. (The only exception to this is that if the Y axis has units of Latitude Ferret will insert cosine(Latitude) factors into some calculations.)

Axes and grids may be defined by "grid files" (which normally have .GRD filename extensions). Axes may also be defined by the DEFINE AXIS command; grids by the DEFINE GRID command.

Contexts

A context is a region or point in space and time and a data set(s). This is the information needed by Ferret to make sense of a reference to a plottable variable. Suppose that "U" is a variable in a data set (file) called U_DATA. A command like "PLOT U" is meaningful only when Ferret knows that it is supposed to be looking for U in data set U_DATA and knows where in 4-dimensional space it is supposed to plot.

The context space-time region may be described by a mix of subscript and world coordinate positions. Subscripts are specified by I=,J=,K=,L= for axes 1 through 4, respectively. World coordinates are specified by X=,Y=,Z=,T=. On the right of the equal sign a single point may be given or a range specified by low:high may be given. Special formats are allowed for X= (longitude, e.g. 160W), Y=(latitude, e.g. 23.5S) and time (calendar dates like "7-NOV-1989:12:35:00" in quotation marks).

The data set may be given by name or number. The commands SET DATA and CANCEL DATA and the D= context descriptor all accept the name of the data set or its number. The data sets are numbered by the order in which they are pointed to with SET DATA. This order may be seen with SHOW DATA.

You can tell Ferret the context in 3 places:

1. The program context: Using the commands SET REGION and SET DATA you can describe a context in which all commands and expressions will be interpreted. You can look at the program context with SHOW REGION and SHOW DATA. (The command SET DATA is used both to initialize new data sets and to make previously initialized sets the current program context. When SET DATA initializes a new data set that set automatically becomes the data set for the program context.) Example: SET REGION/Z=50

2. The command context: Using the command qualifiers I,J,K,L,X,Y,Z,T and D commands like PLOT,CONTOUR,SHADE,LIST and VECTOR can specify additional context information. Command context information on any axis or on the data set will replace any program context information on the same axis or the data set.

3. The variable context: Using the same qualifiers as the command context any plottable variable name can be modified with additional context information in square brackets (e.g. LET U200 = U[Z=200,D=U_DATA], or LIST U[I=1:100:5]). Variable context information on any axis or the data set will replace any program or command context information on the same axis or the data set.

Transformations

Ferret can transform plottable variables along their axes. Transformations may be specified only in the variable context. Ferret understands a number of transformations that may be specified with the space-time region qualifiers. Some examples: PLOT U[Z=0:100@AVE] — the variable U averaged between Z=0 and Z=100 LIST/L=1:200 U[L=@SBX:5] — U with a boxcar smoother of width 5 points along L.

Also,

• @FAV (fill data holes with averages)
• @DIN (definite integral) @IIN (indefinite integral)
• @DDC (centered derivative)
• @SHF (shift data a number of points along an axis)
• @MIN (minimum value along an axis)

... and others (see HELP TRANSFORMATIONS inside Ferret)

ferret [-batch <file>.ps][-memsize Mwords] [-unmapped] [-gui] [-help] [-gif] [-server] [-script [arg1] [arg2]...]

-memsize Mwords
specify the memory (data cache) size in Megawords (default is 25.6)

If memory is severely limited on a system Ferret's default memory cache size may be too large to permit execution. In this case use the "-memsize" qualifier on the command line to specify a smaller cache.

-unmapped
use invisible output windows (useful for creating animations and GIF files, or to create metafiles when window resizing is needed. In this case you can create metafiles, using any SET WINDOW/SIZE or /ASPECT commands required. Then use gksm2ps to convert to postscript, using gksm2ps options to control orientation and sizing.)

-gui
start Ferret in point-and-click mode (may not be available on all platforms). This option is not currently supported. Starting Ferret with ferret -gui will run the current version of Ferret, but some features may not work. If you need such features, or if -gui is not functioning on your platform, you will need to use the command-line version of Ferret.

-help
obtain help on the Unix command line options

-nojnl
start Ferret without a journal file. Within the Ferret session, you can use SET MODE JOURNAL:<filename> to turn on journaling and set the journal file name if desired.

-gif
Ferret can run in batch mode—without an X server (see also -server below). Graphical output is buffered, and is stored in a GIF file by executing the FRAME command. For example:

> ferret -gif 
yes? (commands that generate a plot...) 
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 gif 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.

-batch
Ferret can generate PostScript files or metafiles without an X server. If you wish to use this mode, start Ferret with the -batch option:

ferret -batch <file>.ps
ferret -batch <file>.plt
ferret -batch

where <file> is the name of the output file. <file>.ps will write postscript files and <file>.plt will write metafiles. If no file is specified, Ferret will writeemetafiles named metafile.plt.

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. (If window sizing is needed, can start Ferret with the -unmapped option, and create metafiles, using any SET WINDOW/SIZE or /ASPECT commands required. Then use gksm2ps to convert to postscript, using gksm2ps options to control orientation and sizing if desired.)
• 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.

When in batch metafile mode:

A new myfile.plt.~*~ file is started with each new plot "page" that we'd see when running interactively.

SET MODE METAFILE newname.plt will change the name of the metafile to the new name.

The following commands are ignored in metafile batch mode:

• SET MODE METAFILE ! except for
  - SET MODE METAFILE newname.plt ! subsequent metafiles will have the new name
  
• 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, WIRE
• CANCEL VIEWPORT
• SET WINDOW/CLEAR
• PPLUS/RESET

-server
Run in server mode -- don't stop on message commands. This mode uses primitive (but faster) command line reading, so it is generally preferred when setting up Ferret from a pipe or batch process. See the notes above under -gif regarding window sizing commands.

-script
Run a script, with optional arguments, and exit. Ferret starts, the script runs, and Ferret exits. If Ferret encounters an error, it will issue any error messages and exit to the command line. The switch also sets the -nojnl, -server, and -noverifyswitches (MODE VERIFY and MODE JOURNAL may be turned back on within the script). It suppresses the banner lines. So that the command line reader can read and process any arguments to the script, this option must be specified last, after any other command-line switches (e.g. -gif or -memsize).

ferret -script file.jnl [arg1] [arg2] [arg3]

This section presents a number of short Ferret sessions that demonstrate common uses. Data sets used in these sessions and throughout this manual are included with the distribution. If Ferret is installed on your system, you can duplicate the examples shown.

In this sample session, the data set "monthly_navy_winds" is specified and certain aspects of it are examined. The command SHOW DATA/VARIABLES displays the variables in "monthly_navy_winds" and where on each axis they are defined. SET REGION specifies where in the grid the user wishes to examine the data. VECTOR produces a vector plot of the indicated variables over the specified region.

yes? USE monthly_navy_winds ! specify the data set
yes? SHOW DATA/VARIABLES ! what's in it?
 currently SET data sets:
    1> /home/porter/tmap/ferret/linux/fer_dsets/data/monthly_navy_winds.cdf  (default)
 
 name     title                             I         J         K         L
 UWND     ZONAL WIND                       1:144     1:73      ...       1:132
             M/S on grid GDN1 with -99.9 for missing data
             X=18.8E:18.8E(378.8)  Y=91.2S:91.2N  
 VWND     MERIDIONAL WIND                  1:144     1:73      ...       1:132
             M/S on grid GDN1 with -99.9 for missing data
             X=18.8E:18.8E(378.8)  Y=91.2S:91.2N  
 
  time range: 16-JAN-1982 20:00 to 17-DEC-1992 03:30

Many examples of accessing ASCII data are available later in this manual. See the chapter, "Data Sets" The simplest access, one variable with one value per record, looks like this:

% ferret
yes? FILE/VARIABLE=v1 snoopy.dat
yes? PLOT v1
yes? QUIT