-unmapped
use invisible output windows (useful for creating animations and GIF files)

Ch1 Sec2.3. Sample sessions

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.

Ch1 Sec2.3.1. Accessing a NetCDF data set

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> /opt/local/ferret/fer_dsets/descr/monthly_navy_winds.des  (default)
    FNOC 2.5 Degree 1 Month Average World-wide Wind Field
name     title                          I         J         K         L
UWND     ZONAL WIND                    1:144     1:73      ...       1:132
            M/S on grid FNOC251 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 FNOC251 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

Ch1 Sec2.3.2. Reading an ASCII data file

Many examples of accessing ASCII data are available later in this manual. See the chapter, "Data Sets" (p. 29) 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

Ch1 Sec2.3.3. Using viewports

The command SET VIEWPORT allows the user to divide the output graphics "page" into smaller display viewports.

In this sample session, we create two plots in two halves of a window (Figure 1_2):

% ferret
yes? USE coads_climatology
yes? SET REGION/X=160E:130W
yes? SET REGION/Y=-10:10/L=5
yes? SET VIEWPORT upper
yes? CONTOUR sst
yes? SET VIEWPORT lower
yes? CONTOUR airt
yes? QUIT

Ch1 Sec2.3.4. Using abstract variables

Abstract variables (expressions that contain no dependencies on disk-resident data) can be easily displayed with Ferret. See the chapter "Variables and Expressions", section "Abstract variables" (p. 50), for several examples and detailed information.

For example, a user wishing to examine the function SIN(X) on the interval [0,3.14] might use (Figure 1_3):

% ferret
yes? PLOT/I=1:100 sin(3.14*I/100)
yes? QUIT

Ch1 Sec2.3.5. Using transformations

A transformation is an operation performed on a variable along a particular axis and is specified with the syntax "@trn" where "trn" is the name of a transformation. See the chapter "Variables and Expressions", section "Transformations" (p. 75), for detailed information.

A user may wish to look at ocean temperatures averaged over a range of depths. In this sample session, we look at temperatures averaged from 0 to 100 meters of depth using a data set which has detailed resolution in depth (Figure 1_4). We plot the data along longitude 160 west from latitude 30 south to 30 north.

% ferret
yes? USE levitus_climatology
yes? SET REGION/Y=30s:30n/X=160W
yes? PLOT temp[Z=0:100@AVE]
yes? QUIT

Ch1 Sec2.3.6. Using algebraic expressions

See the chapter "Variables and Expressions", section "Expressions" (p. 53) for a description of valid expressions.

In this example, the data set contains raw sea surface temperatures, air temperatures, and wind speed measurements. We wish to look at a shaded plot of sensible heat at its first timestep (L=1) (Figure 1_5). We specify a latitude range and contour levels.

% ferret
yes? USE coads_climatology            !monthly COADS climatology
yes? LET kappa = 1                    !arbitrary
yes? LET/TITLE="SENSIBLE HEAT"  sens_heat = kappa * (airt-sst) * wspd
yes? SHADE/L=1/LEV=(-20,20,5)/Y=-90:40 sens_heat
yes? QUIT

Ch1 Sec2.3.7. Finding the 20-degree isotherm

Isotherms can be located with the "@LOC" transform, which returns the axis location where the value of the argument of @LOC first occurs. Thus, "TEMP[Z=0:200@LOC:20]" locates the first occurrence of the temperature value 20 along the Z axis, scanning all the data between 0 and 200 meters.

A session examining the 20-degree isotherm in mid-Pacific ocean data (Figure 1_6):

% ferret
yes? USE levitus_climatology
yes? SET REG/Y=10s:30n/X=140E:140W
yes? PPL CONSET .12  !label size
yes? CONTOUR temp[Z=0:200@LOC:20]
yes? QUIT

Note that the transformation @WEQ could have been used to display ANY variable on the surface defined by the 20 degree isotherm.

Ch1 Sec3. COMMON COMMANDS

A quick reference to the most commonly used Ferret commands (typing "SHOW COMMANDS" at the Ferret prompt lists all commands):

Information on all Ferret commands is available in Part II, Commands Reference, of this manual.

Ch1 Sec4. COMMAND SYNTAX

Commands in program Ferret conform to the following template:

COMM [/Q1/Q2...] [SUBCOM[/S1/S2...]] [ARG1 ARG2 ...] [!comment]

where

notes...

• Items in square brackets are optional.
• One or more spaces or tabs must separate the command from the subcommand and from each of the arguments. Spaces and tabs are optional preceding qualifiers.
• Multiple commands, separated by semi-colons, can be given on the same line.
• Command names, subcommand names, and qualifiers require at most 4 characters.
  (e.g., yes? CANCEL LIST/PRECISION is equivalent to yes? CANC LIST/PREC)
• Some qualifiers take an argument following "=" (e.g., yes? LIST/Y=10S:10N).
• An exclamation mark normally signifies the end of a command and the start of (optional) comment text.
• The backslash character (\), when placed directly before an exclamation point (!), apostrophe ('), semicolon (;), or forward slash (/), will hide it ("escape it") from Ferret.
• See the Expressions section (p. 53) for information on algebraic expressions as arguments to commands
• See the Symbols sections (p. 169) for information on symbol substitution in commands

Ch1 Sec5. GO FILES

GO files are files containing Ferret commands. They can be executed with the command "GO filename". Throughout this manual, these files are referred to as GO scripts or journal files (the file names end in *.jnl). There are two kinds of GO files provided with the distribution (differing in function, not form)—demos and tools.   A list of the demonstrations and scripts can be found in Ferret's on-line documentation in "on-line demonstrations".

Ch1 Sec5.1. Demonstration files

Demonstration GO files provide examples of various Ferret capabilities (the tutorial is such a script) . The demonstration GO files may be executed simply by typing the Ferret command

yes? GO demo_name    
example:  yes? GO vector_demo

Below is a list of the demo files provided as of 4/99 (located in directory $FER_DIR/examples). The Unix command "Fgo demo" will list all GO scripts containing the string "demo". Use Fgo '*' to see all the scripts that are currently available on your system.

Ch1 Sec5.2. GO tools

GO tools are scripts which contain Ferret commands and perform dataset-independent tasks. For example, "GO land" overlays the outline of the continents on your plot. (Note: In order for Ferret to locate the GO scripts, the environment variable FER_GO must be properly defined. See the chapter "Computing Environment," p. 187, for guidance.)

To run any GO tool,  from the Ferret command line, type,

Yes? GO scriptname

Or if the script has arguments,  they follow the script name with optional comma separators.

yes? GO script2 arg1, arg2

To find out about the script,  use the /HELP qualifier, which opens the script with the more command to type the first 20 lines of the script and allow you to see the documentation at the start of the script.

yes? GO/HELP scriptname

To omit arguments from a GO script,

yes? GO script arg1, , arg3

Or double quotes with a space to indicate the missing item.

yes? GO script arg1 "  " arg3

The Unix command Fgo has been provided to assist with locating tools within the Unix directory hierarchy. For example,

    % Fgo grid    displays all tools with the substring "grid" in their names
    % Fgo '*'    displays all GO tools and demonstrations

When passing arguments to GO commands sometimes it is necessary to pass enclosing quotation marks. An common example is the passing of the argument to the CONTOUR/LEVELS qualifier in cases such as

CONTOUR/LEVELS="(-100) (-10,10,2) (100)" my_var

where there may be blanks embeddd inside of the string. There are 3 methods to embed quotations inside of strings

1. use "\" to protect the quotation marks in the GO command line

yes? go my_go_script "\"(-100) (-10,10,2) (100)"\"

with the script containing the line

CONTOUR/LEVELS=$1 my_var

2. use "\" to define a symbol which contains the quotation marks

yes? DEFINE my_quoted_string \"$1\"
yes? CONTOUR/LEVELS=($my_quoted_string) my_var

3. use the symbol substitution syntax to add quotes to theGO argument

Yes? CONTOUR/LEVELS=$1&|*>"*"&

Of course, in the above examples one could also simply use

yes? CONTOUR/LEVELS="$1" my_var

Below is a table of the tools provided with your Ferret installation. Some tools accept optional arguments to control details. Use Fgo -more script_name for details on a script.

Ch1 Sec5.3. Writing GO tools

A GO tool ("GO script," "journal file," ...) is simply a sequence of Ferret commands stored in a file and executed with the GO command. Writing a simple GO tool requires nothing more than typing normal commands into a file.

To write a robust GO tool that may be shared, however, certain guidelines should be followed:

    1) the GO tool should be well documented

    2) the GO tool should leave the Ferret context unmodified

    3) the GO tool may need to run "silently"

    4) the GO tool may need to accept arguments (a maximum of 9 parameters)

Ch1 Sec5.3.1. Documenting GO tools

Documentation consists primarily of well-chosen comment lines (lines beginning with an exclamation mark). In addition, a line of this form should be included:

! Description:  [one-line summary of your GO tool]

This line is displayed by the Fgo tool.

Ch1 Sec5.3.2. Preserving the Ferret state in GO tools

Often a complex GO tool requires setting data sets, modifying the current region, etc. But to a user executing this tool its behavior may seem erratic if the user's previous context is modified by running the tool. A tool can restore the previous state of Ferret by these means:

Ch1 Sec5.3.3. Silent GO tools

If a user has set mode "verify" then by default every line of your GO tool, including comment lines, will be displayed at the screen as Ferret processes it. To make your GO tool run silently include the command CANCEL MODE VERIFY at the beginning of the GO tool and SET MODE/LAST VERIFY at the end. If the backslash character "\" is found at the beginning of any line that single line will not be displayed regardless of the state of MODE VERIFY. Thus the command "\CANCEL MODE VERIFY" is often the first line of a GO tool. Note also that the command LET/SILENT is useful in GO tools which need to define variables.

Ch1 Sec5.3.4. Arguments to GO tools

Arguments (parameters) may be passed to GO tools on the command line. There is an  upper  limit of nine arguments allowed.  For example,

yes? GO land red

passes the string "red" into the GO file named land.jnl. Inside the GO tool the argument string "red" is substituted for the string "$1" wherever it occurs. The "1" signifies that this is the first argument—similar logic can be applied to $1,... $9 or $0 where $0 is replaced by the name of the GO tool itself. Similarly "$*" is replaced by all the arguments, 1–9 as a single string, separated by spaces.

As Ferret performs the substitution of $1 (or other) arguments it offers a number of string processing and error processing options. For example, without these options, if a user failed to supply an argument to "GO land" then Ferret would not know what to substitute for $1 and it would have to issue an error message. A default value can be supplied by the GO tool writer using the syntax

$1%string%

for example,

$1%black%

inside land.jnl would default to "black" if no color were specified. Note that in the example percent signs were used to delimit the default string but any of the characters ! # $ % or & also work as delimiters.

In another case it might not be appropriate to supply a default string but instead it would be desirable to issue an instructional error message. The "<" character indicates an error message text:

$1"<you must supply an argument to this GO tool"

In still other cases there are a range of acceptable arguments but all other arguments are illegal. The allowable arguments can be specified following "|" (vertical bar) characters as in this example:

$1"|black|red|<You must specify black or red"

or a default of "black" could be specified together with the options as

$1"black|black|red|"

In the interest of "friendliness" a GO file may want to allow the user to specify a string other than the string actually needed by the GO tool. For example, a red plot line is actually obtained by the PLOT command qualifier /LINE=2—the string "red" never appears in this command. To allow a user to specify "red" and yet have the string "2" substituted, Ferret has provided the replacement arrow ">". Thus

$1"1|red>2|"

specifies a default string of "1" if no argument is given but substitutes "2" if "red" is supplied. In a typical GO tool line, defaults, options, substitutions, and an error message are combined like this:

PLOT/LINE=$1"1|red>2|green>3|blue>4|<must be red, green, or blue"

Note that the error message will be issued only if some color other than "red," "green," or "blue" is specified; if no argument is specified then "1" is substituted.

An asterisk (*) can be used to designate that any text whatsoever is acceptable as an option.

PLOT/LINE=$1"1|red>2|green>3|blue>4|*>7"

would never generate an error and would use line style 7 (thick black) if an unrecognized argument string such as "orange" were given.

An asterisk (*) can also be used on the right-hand side of a substitution, in which case it stands for the entire original argument string. For example

SET VARIABLE/TITLE=$1%*>"*"%

will place double quotation marks around the string in argument 1.

A final style note to keep in mind when writing GO tools that use arguments: providing error message feedback and appropriate documentation for the user is essential. In complex GO tools, all arguments should be checked at the beginning of the GO tool using the no-op command (has no effect) "QUERY/IGNORE". Thus the GO tool land.jnl might contain these lines at the beginning:

! check the argument
QUERY/IGNORE $1"1|red|green|blue|<must be red, green, or blue"

Once argument errors have been trapped and reported, the lengthy error text would not be needed again in the GO tool.

GO tools that use arguments should also be carefully documented. There are numerous examples provided with Ferret; try, for example, the Unix commands

% Fgo -more fland.jnl
% Fgo -more stick_vectors

or

% Fgo -more squeeze_colors

Ch1 Sec5.3.5. Flow Control in GO tools

There are several Ferret commands and techniques to assist with flow control in your GO scripts.

GO (subroutines)

The GO command may be used inside of a GO script (tool) to execute another (nested) GO script. If an error occurs inside of a nested GO script and SET MODE IGNORE_ERROR has not been issued then the GO script will be interrupted and control returns to the command line.

REPEAT (looping)

The REPEAT command may be used to execute loops within Ferret. The loop "counter" may be an index (I,J,K, or L) or a world coordinate (longitude, latitude, depth, or time). The increment between loop iterations need not correspond to the spacing of points on a grid. When used in conjunction with the "d" options of SET REGION, such as SET REGION/DI="-5:-5" the loops may be used to zoom in or out of a region or to pan a limited-width window of view across a larger region. See the Advanced Movie-Making section (p. 126) of this manual for further details.

IF-THEN-ELSE (conditional execution)

An IF-THEN-ELSE syntax can be used to conditionally execute Ferret commands. It may be used in two styles—single line and multi-line. See the IF command (p. 271) in the Commands Reference section of this manual for further details.

Ch1 Sec5.3.6. Debugging GO tools

As the complexity of Ferret GO scripts increases it becomes more challenging to locate and correct errors in GO scripts. This is especially true if, as so many GO scripts do, the scripts are made silent by containing the command CANCEL MODE VERIFY. In a silent script it can be unclear from where within the script an error message is originating.

A special VERIFY mode has been provided to assist with locating the source of these error messages

SET MODE VERIFY:ALWAYS

The ALWAYS argument to this command instructs Ferret to ignore CANCEL MODE VERIFY commands inside of command files. All of the script commands that Ferret executes will be echoed when this mode is set. Error messages will appear with the commands that generated them. To restore normal non-debugging operations issue CANCEL MODE VERIFY or SET MODE VERIFY (no argument) interactively from the yes? prompt.

Complex webs of variable definitions (defined with LET or DEFINE VARIABLE) may also create challenges for debugging scripts. See Debugging Complex Hierarchies of Expressions (p. 101) for further discussion of this topic.

Ch1 Sec6. SAMPLE DATA SETS

A number of demonstration data sets are included with this distribution. Several of these data sets are used by the demonstration "GO" files, above. The data sets should be accessible simply by typing the Ferret command

yes? USE data_set_name      for example,
yes? USE coads_climatology

Ch1 Sec7. UNIX TOOLS

A number of tools are provided with Ferret to assist with Unix-level activities: on-line help, converting data to Ferret's formats, locating files, etc. They are located in the Ferret installation area—typically $FER_DIR/bin. See the chapter "Copmuting Environment", section "Setting Up an Account" (p. 187), if the tools are not available on-line. They are described below.

Faddpath        Usage: Faddpath new_path
Faddpath will add a new path name to the default lists of directories that Ferret searches a) in response to the SET DATA command; b) when looking for grid definition files; c) when looking for data files.

Fapropos        Usage: Fapropos string    (i.e. % Fapropos regridding)
Fapropos searches the Ferret User's Guide for all occurrences of the given word or string. The string is not case sensitive. If the string contains multiple words it must be enclosed in quotation marks. Fapropos will list all lines of the User's Guide that contain the word or string and report their line numbers. The line numbers may be used with Fhelp to enter the User's Guide at the desired location.

Fdata        Usage: Fdata data_file_substring
Searches the list of directories contained in the environment variable FER_DATA to find the data files whose names contain the indicated substring. For example,

    % Fdata coads

locates the data files containing "coads" in their names. (Use this command to locate NetCDF data sets by giving the string "cdf".)

Fdescr        Usage: Fdescr des_name_substring
Searches the list of directories contained in the environment variable FER_DESCR to find the descriptor files whose names contain the indicated substring. For example,

    % Fdescr coads

locates the descriptor files containing "coads" in their names. ("Fdescr .des" will list all accessible descriptors.)

Fenv        Usage: Fenv
Prints the values of environment variables used by Ferret

Fgo        Usage: Fgo name_substring
Searches the list of directories contained in the environment variable FER_GO to find the GO command files whose names contain the indicated substring. For example,

    % Fgo grid

locates the Ferret tools that contain "grid".

Fgrids        Usage: Fgrids gridfile_substring
Searches the list of directories contained in the environment variable FER_GRIDS to find the grid definition files whose names contain the indicated substring. For example,

    % Fgrids fnoc

locates the grid definition files containing "fnoc" in their names. ("Fgrids .grd" will list all accessible grid files.)

Fhelp        Usage: Fhelp line_number or Fhelp string
Fhelp enters the Ferret User's Guide beginning at the indicated line number or at the first occurrence of the given string. The string, if used, is not case sensitive. The Unix "more" command is used to access the User's Guide. The most commonly used "more" commands are documented under Ftoc.

        Examples:    % Fhelp  1136
                % Fhelp  "modulo axis"

Fman        Usage: Fman
(Not yet implemented.) Enters the Ferret User's Guide as on-line, formatted hypertext.

Fpalette        Usage: Fpalette name_substring
Searches the list of directories contained in the environment variable FER_PALETTE to find the palette files whose names contain the indicated substring. For example,

    % Fpalette blue

locates the palette files containing "blue" in their names.

Fpurge        Usage: Fpurge filename_template
Fpurge is a support routine to manage multiple versions of files created by Ferret—particularly journal files and graphic metafiles. Fpurge will remove all versions of a file except the current version. For example, "Fpurge ferret.jnl" will eliminate all past versions of ferret.jnl in the current directory.

Fsort        Usage: Fsort filename_template
Fsort is a support routine for sorting file versions. Fsort reorders the incorrect ordering of emacs-style version numbers assigned by the Unix "ls" utility. For example, when sorting, ls will place filename.~19~ before filename.~2~. "Fsort filename*" will take care of this problem. Fsort may be used in Unix pipes.

Ftoc        Usage: Ftoc
Ftoc enters the table of contents of the Ferret User's Guide using the Unix "more" command. Within "more" the following are the most commonly used commands:

Ch1 Sec8. HELP

Ch1 Sec8.1. Unix on-line help

On Unix systems interactive Ferret help is available from the command line. If multiple windows are not available on your system the ^Z key can be used to suspend the current Ferret session and access the help; the Unix "fg" command resumes the suspended session.

Several Unix commands provide assistance with rapidly locating information in the Ferret User's Guide. The entire Ferret User's Guide is available on-line as document $FER_DIR/doc/ferret_users_guide.txt. A printable version is also available in PostScript: $FER_DIR/doc/ferret_users_guide.ps.

These commands are available to access the Ferret User's Guide:

Normally Ftoc or Fapropos is used first to locate the desired information in the User's Guide. Then Fhelp is used to enter the User's Guide at the selected location.

Ch1 Sec8.2. Examples and demonstrations

As discussed earlier in this chapter (Getting Started, GO files), the demonstrations that come with the Ferret distribution are a source of help. See the introductory chapter, section "Demonstration files," (p. 14) for a list of demonstrations, or look in $FER_DIR/examples; you may find something that addresses your problem.

Ch1 Sec8.3. Help from within Ferret

Typing "help" while running Ferret will give you information on using the Unix tool Fhelp to access the User's Guide.

The Ferret command SHOW COMMANDS will list all Ferret commands; SHOW COMMAND "command" will display all qualifiers for the specified command.

The Ferret command SHOW FUNCTIONS lists all Ferret functions and their arguemnts.  SHOW FUNCTION *string* will show all functions containing the string "string".  SHOW FUNCTIONS EXTERNAL shows the names and arguments of external functions (see External Functions Chapter, page 217)

The Ferret command SHOW TRANSFORMS lists all Ferret transforms, including variable transforms and regridding transforms.

If you want to get details on a script, type 'GO/HELP scriptname" to see the documentation at the start of the script.  For example:

GO/HELP land

When writing scripts, include documentation listing the purpose of the script and its arguments in the first few lines of the script.  Then this feature will let you and others who may use the script get instant information about it.

Ch1 Sec8.4. Web-based information

From the Ferret web page, at http://ferret.wrc.noaa.gov/Ferret, see these sections:

1. Ferret support policy outlines the support available to users and sources of information

2.  FAQ section  discusses many topics where questions often arise.

3. Email archives, which are searchable and contain questions and solutions from the Ferret users group.

4. Documentation section, including release notes, this manual which is updated regularly on the web, and on-line information on demonstration scripts, data formats, and the Plot Plus graphics used by Ferret.