Chapter 1: INTRODUCTION

Ch1 Sec1. OVERVIEW

Ferret is an interactive computer visualization and analysis environment designed to meet the needs of oceanographers and meteorologists analyzing large and complex gridded data sets. "Gridded data sets" in the Ferret environment may be multi-dimensional model outputs, gridded data products (e.g., climatologies), singly dimensioned arrays such as time series and profiles, and for certain classes of analysis, scattered n-tuples (optionally, grid-able using Ferret's objective analysis procedures). Ferret accepts data from ASCII and binary files, and from two standardized, self-describing formats. Ferret's gridded variables can be one to four dimensions—usually (but not necessarily) longitude, latitude, depth, and time. The coordinates along each axis may be regularly or irregularly spaced

Ferret offers the ability to define new variables interactively as mathematical expressions involving data set variables and abstract coordinates. Calculations may be applied over arbitrarily shaped regions. Ferret's "external functions" framework allows external code written in FORTRAN, C, or C++ to merge seamlessly into Ferret at runtime. Using external functions, users may easily add specialized model diagnostics, advanced mathematical capabilities, and custom output formats to Ferret. A collection of general utility external functions is included with Ferret.

Ferret provides fully documented graphics, data listings, or extractions of data to files with a single command. Without leaving the Ferret environment, graphical output may be customized to produce publication-ready graphics. Graphic representations include line plots, scatter plots, line contours, filled contours, rasters, vector arrows, polygonal regions and 3D wire frames. Graphics may be presented on a wide variety of map projections. Interfaces to integrate with 3D and animation applications, such as Vis5D and XDataSlices are also provided.

Ferret has an optional point-and-click graphical user interface (GUI). The GUI is fully integrated with Ferret's command line interface. The user may freely mix text-based commands with mouse actions (push buttons, etc.). Ferret's journal file will log all of the actions performed during a session such that the entire session, including GUI inputs, can be replayed and edited at a later time.

This User's Guide describes only the command line interface to Ferret. Other documents describe the point and click interface.

Ferret was developed by the Thermal Modeling and Analysis Project (TMAP) at NOAA/PMEL in Seattle to analyze the outputs of its numerical ocean models and compare them with gridded, observational data. Model data sets are often multi-gigabyte in size with mixed 3- and 4-dimensional variables defined on staggered grids.

Ferret is supported on a variety of Unix workstations with a version also available for Windows NT/9x. Ferret is available at no charge from anonymous FTP [node ftp.ferret.noaa.gov] or from the World Wide Web [URL http://ferret.wrc.noaa.gov/Ferret].


Ch1 Sec1.1. Ferret User's Group

The Ferret User's Group provides a venue to ask experienced Ferret users for advice solving problems and to keep abreast of the latest Ferret updates. To (un)join simply send an e-mail message to

Majordomo@ferret.wrc.noaa.gov

and include a message which says simply

(un)subscribe ferret_users

(Note this must be in the e-mail message BODY—not in the subject line.) To learn about the user's list without joining send this message instead to the same address:

info ferret_users



Ch1 Sec1.2. Ferret Home Page

The Ferret Home Page contains source code distributions, on line documentation, Users' Group archives, Frequently Asked Questions and more. It is available at

http://ferret.wrc.noaa.gov/Ferret/FAQ



Ch1 Sec2. GETTING STARTED

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" (p. 187). (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.


Ch1 Sec2.1. Concepts

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



figure1_01

Ch1 Sec2.1.1. Thinking like a Ferret:

(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:

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. U[Z=200,D=U_DATA]). 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,


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


Ch1 Sec2.2. Unix command line switches

ferret [-batch<file>.ps][-memsize Mwords] [-unmapped] [-gui] [-help]

-memsize Mwords
specify the memory (data cache) size in Megawords default: 3.2

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

-gui
start Ferret in point-and-click mode (may not be available on all platforms)

-help
obtain help on the Unix command line options

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

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:

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

ferret -batch <file>.ps

where <file> is the name of the output file. Note that the filename must end with ".ps".

Please note the following when using PostScript mode:

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):

figure1_02

% 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):

figure1_03

% 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.

figure1_04

% 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.

figure 1_05

% 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):

figure1_06

% 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):

Command

Description

 

USE

names the data set to be analyzed (alias for "SET DATA")

SHOW DATA

produces a summary of a variable

SHOW GRID

examines the coordinates of a grid

SET REGION

sets the region to be analyzed

LIST

produces a listing of data

PLOT

produces a plot

CONTOUR

produces a line contour plot

FILL

produces a color filled contour plot

SHADE

produces a shaded-area plot

VECTOR

produces a vector arrow plot

POLYGON

plots polygonal regions

DEFINE

define new axes, grids, and symbols

STATISTICS

produces summary statistics about variables and expressions

LET

defines a new variable

SAVE

saves data in NetCDF format

GO

executes Ferret commands contained in a file

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

COMM

is a command name   yes? LIST

Q1...

are qualifiers of the command yes? CONTOUR/SET_UP

SUBCOM

is a subcommand name   yes? SHOW MODE

S1...

are qualifiers of the subcommand  yes? SET LIST/APPEND

ARG1...

are arguments of commands   yes? CANCEL MODE INTERPOLATE

notes...

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.

Name

Description

   

tutorial

brief tour through Ferret capabilities

topographic_relief_demo

global topography

coads_demo

view of global climate using the Comprehensive

 

Ocean-Atmosphere Data Set

levitus_demo

T-S relationships using Sydney Levitus' climatological Atlas of the World Oceans

fnoc_demo

Naval Fleet Numerical Oceanography Center data

vector_demo

vector plots

wire_frame_demo

3D wire frame representation

custom_contour_demo

customized contour plots

viewports_demo

output to viewports

multi_variable_demo

multiple variables with multiple dependent axes

objective_analysis_demo

interpolating scattered data to grids

mp_demo

map projections demo

log_plot_demo

log plots using PPLUS in Ferret

depth_to_density_demo

contour with a user-defined variable as an axis

file_reading_demo

reading an ASCII file

regridding_demo

tutorial on regridding data

mathematics_demo

abstract function calculation

statistics_demo

probability distributions

spirograph_demo

for-fun plots from abstract functions

splash_demo

for-fun mathematical color shaded plots

symbol_demo

how to use symbols for plot layouts

sigma_coordinate_demo

how to work with sigma coordinates



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.


 

Tool name

Description

     

OVERLAYS

 

basemap

a geographical basemap of continents to overlay on

 

land

overlays continental boundaries (color controls)

 

bold_land

overlays darker continental boundaries

 

fland

overlays filled continents (color and resolution controls)

 

focean

overlays ocean mask (for terrestrial plots)

 

graticule

sets the plot axis style to use a graticule (rather than tics)

 

tics

resets the plot style to use axis tics (rather than a graticule)

 

gridxy

overlays a "graticule" labeling the I,J subscripts

 

gridxz

overlays a "graticule" labeling the I,K subscripts

 

gridxt

overlays a "graticule" labeling the I,L subscripts

 

gridyz

overlays a "graticule" labeling the J,K subscripts

 

gridyt

overlays a "graticule" labeling the J,L subscripts

 

gridzt

overlays a "graticule" labeling the K,L subscripts

 

box

draws a box at the specified location on the plot

 

ellipse

draws an ellipse at the specified location on the plot

     

MATHEMATICAL

 

frequency_histogram

makes a frequency distribution plot (histogram) of data

 

ts_frequency

creates a 2-variable histogram (typically an oceanographer's TS density diagram)

 

polar

defines R and THETA from X and Y to perform (limited) polar plots

 

regressx

defines variables for linear regression along X axis

 

regressy

defines variables for linear regression along Y axis

 

regressz

defines variables for linear regression along Z axis

 

regresst

defines variables for linear regression along T axis

 

unit_square

sets unit square as default for abstract variables

 

variance

defines variables to compute variances and covariances

 

var_n

refines TVARIANCE with corrected n/n+1 factors

 

dynamic_height

defines Ferret variables for dynamic height calculations

     

SAMPLE DISPLAYS

 

line_samples

draws specimens of the available line styles

 

line_thickness

draws examples of pen color/thickness styles in PPLUS

 

fill_samples

draws specimens of the available fill styles

 

show_symbols

draws specimens of the default symbols

 

show_88_syms

draws specimens of all 88 PPLUS symbols

     

GRAPHICS

 

bar_chart

makes a color-filled bar chart from a line of data

 

bar_chart2

makes a bar chart using hollow rectangles

 

centered_vectors

makes a vector plot with coords at vector midpoints

 

scattered_vectors

makes a vector plot from an ASCII file: x,y,u,v

 

stick_vectors

makes a stick vector plot of a line of U,V values

 

extremum

annotate contour extrema on a plot

 

split_z

oceanographic-style plot with 2 z-axis scalings

     

PLOT APPEARANCE

 

margins

tweak the sizing of the plot on the page

 

magnify [factor]

increases the data plotting area (area inside the axes)

 

unmagnify

restores the plot origin and axis lengths to default values

 

black

sets video background to black, foreground to white

 

white

sets video background to white, foreground to black

 

bold

sets up PLOT+ and Ferret to produce bolder-looking plots

 

unbold

resets plot environment to normal after "GO bold"

 

unlabel [label #]

removes a specified (numbered) PPLUS movable label

 

remove_logo

removes labels 1–3 that form the Ferret logo

 

box_plot

produces a plot with "bare" axes (no tics, no labels)

 

reminder

place small annotations in upper left corner of plot

COLOR

 

try_palette [pal]

displays palette appearance for various numbers of color levels

 

try_centered_palette

displays centered palette appearance for various numbers of levels

 

exact_colors

sets up Ferret and PPLUS to modify individual colors in a color palette

 

squeeze_colors

modifies a color palette by squeezing and stretching the color scale

     

MULTIPLE X AND Y AXES  (run demo: yes? GO multi_variable_plots)

 

left_axis_plot

plots a single variable preparing for a 2nd axis on the right

 

right_axis_plot

overlays a plot of a single variable using an axis on the right

 

multi_xaxis_plot1

draws a plot formatted for later overlays using multiple X axes

 

multi_xaxis_overlay

overlays a variable with a distinct X axis

 

multi_yaxis_plot1

draws a plot formatted for later overlays using multiple Y axes

 

multi_yaxis_overlay

overlays a variable with a distinct Y axis

     

MAP PROJECTIONS (run demo: yes? GO mp_demo)

 

mp_~name~

individual projections include
bonne, craster_parabolic, eckert_greifendorff, eckert_iii, eckert_v, hammer, lambert_cyl, mcbryde_fpp, mercator, orthographic, plate_caree, polyconic, sinusoidal, stereographic_eq, stereographic_north, stereographic_south, vertical_perspective, wagner_vii, winkel_i

 

mp_aspect

set the appropriate window aspect ratio for this map projection

 

mp_fland

overlays "map projected" filled continents (color controls)

 

mp_graticuled

overlays "map projected" graticule (color controls)

 

mp_label

plots a label using world coordinates

 

mp_land

overlays "map projected" continental boundaries (color controls)

 

mp_land_stripmap

creates a land-centric, interrupted "stripmap" using the current map projection

 

mp_line

overlays "map projected" plotted data

 

mp_ocean_stripmap

creates an ocean-centric, interrupted "stripmap" using the current map projection

 

mp_polygon

overlays "map projected" polygons

     

SAMPLING A GRIDDED FIELD

 

bullseye

locate a bullseye in a 2d field

 

digitize

obtain data values from a plot using the cursor

     

TESTS

 

test

tests proper functioning of FER_GO

 

ptest

produces a quick test plot

 

squares

creates a filled-area test plot



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 (parameters, a maximum of 9)


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:

region:

Save the current default region with the command DEFINE REGION/DEFAULT save. Restore it at the end of your GO tool with SET REGION save.

   

data set:

Save the current default data set with SET DATA/SAVE. Restore it at the end of your GO tool with SET DATA/RESTORE.

   

grid:

Save the current default grid set with SET GRID/SAVE. Restore it at the end of your GO tool with SET GRID/RESTORE.

   

modes:

If you modify a mode inside your GO tool by issuing a SET MODE or a CANCEL MODE command the original state of that mode can be restored using SET MODE/LAST.



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. 269) 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

Data set

Description

   

etopo120

relief of the earth's surface at 120-minute resolution

etopo60

relief of the earth's surface at 60-minute resolution

levitus_climatology

subset of the Climatological Atlas of the World Oceans by Sydney Levitus (Note: the updated World Ocean Atlas, 1994, is also available with Ferret)

coads_climatology

12-month climatology derived from 1946–1989 of the Comprehensive Ocean/Atmosphere Data Set

monthly_navy_winds

monthly-averaged Naval Fleet Numerical Oceanography Center global marine winds (1982–1990)

esku_heat_budget

Esbensen-Kushnir 4×5 degree monthly climatology of the global ocean heat budget (25 variables)



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:

?

interactive help for "more"

q

exit (quit)

space

advance to next screen

return

advance to next line

b

back one screen

/string

locate the next occurrence of "string" (Note: the string is case sensitive)



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:

Ftoc

browse the table of contents of the User's Guide

Fapropos

locate words or character strings in the User's Guide

Fhelp

enter and browse the User's Guide

Fman

enter and browse the User's Guide as formatted hypertext (not yet implemented)

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.



ferret_ug@pmel.noaa.gov

Last modified: September 27, 2000