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.  The GUI version is not currently supported, and is not available on all operating systems. 

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 graphics calls are made using the Plot Plus (PPLUS) graphics package, which is contained within Ferret. Plot Plus was written by Don Denbo.  The Ferret version of PPLUS has diverged somewhat from the original, and the Ferret developers are responsible for these changes and for all of Ferret's graphics.  Additions to PPLUS, for Ferret only,  are documented in Appendix C of this manual (p. 557), which also has a brief history of the PPLUS graphics package. 

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


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 list server address

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.pmel.noaa.gov/FERRET_17sep07/FAQ/ferret_FAQ.html



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. 257). (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. 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, 


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


Ch1 Sec2.2.  Unix command line switches 

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

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

-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 

where <file> is the name of the output file. <file>.ps will write postscript files and <file>.plt will write metafiles. 

Please note the following when using PostScript mode: 

When in batch metafile mode: 

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

The following commands are ignored in metafile batch mode: 

New plots may be started with these commands 

-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 supresses 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] 



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 netCDFdata 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. 33) 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. 63), 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. 112), 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. 73) 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 netCDFformat 

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

Examples: 

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 

bar_chart_demo 

plotting bar charts 

binary_read_demo 

binary file reading (version 5.0 and after) 

coads_demo 

view of global climate using the Comprehensive Ocean-Atmosphere Data Set 

constant_array_demo     

shows {3,5,6} constant-array syntax 

custom_contour_demo 

customized contour plots 

depth_to_density_demo 

contour with a user-defined variable as an axis 

dods_demo 

using DODS to access remote datasets 

edit_data_file_demo 

"hand-editing" variables using netCDFdatasets and SAVE 

ef_eof_demo 

EOF functions 

ef_fft_demo 

FFT functions 

ef_sort_demo 

using the SORT and SAMPLE functions 

ef_wv5d_demo 

writing Vis5D-formatted files 

error_bars_demo 

making error bars on plots 

file_reading_demo 

reading an ASCII file 

fnoc_demo 

Naval Fleet Numerical Oceanography Center data 

levitus_demo 

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

log_plot_demo 

log plots using PPLUS in Ferret 

mathematics_demo 

abstract function calculation 

mercator_demo 

mercator map projection 

minmax_label_demo 

use FINDLO and FINDHI to label extrema on a plot 

mp_demo 

map projections 

mp_stereo_demo 

fancy map projection techniques 

multi_line_labels_demo 

many-line titles and other labels 

multi_variable_demo 

multiple variables with multiple dependent axes 

objective_analysis_demo 

interpolating scattered data to grids 

overlay_on_time_axis_demo 

PLOT/VS and POLYGON over a time axis 

palette_demo 

shows uses of various palettes 

pattern_demo 

patterns on shade and fill plots 

plot_swath_demo 

fill between line plots for "swaths" of color 

plot_vectors 

draw vectors from u,v,lat,lon 

poly_vec_demo 

use filled polygons to plot vector fields 

polymark_demo 

show use of polymark script 

polytube_demo 

"lagrangian" plots along a path using color fill 

regridding_demo 

tutorial on regridding data 

sigma_coordinate_demo 

how to work with sigma coordinates 

spirograph_demo 

for-fun plots from abstract functions 

splash_demo 

for-fun mathematical color shaded plots 

statistics_demo 

probability distributions 

symbol_demo 

how to use symbols for plot layouts 

taylor_example1 

using scripts to make Taylor diagrams 

topographic_relief_demo 

global topography 

trackplot_demo 

use of trackplot.jnl script 

vector_demo 

vector plots 

viewports_demo 

output to viewports 

wire_frame_demo 

3D wire frame representation 



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. 257, 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) 

 

land_detailed 

overlays detailed continents, national and state boundaries,  rivers 

 

bold_land 

overlays darker continental boundaries 

 

fland 

overlays filled continents (color and resolution controls) 

 

focean 

overlays ocean mask (for terrestrial plots) 

 

multi_xaxis_overlay 

Overlay a line plot over an existing one, with a new horizontal axis 

 

multi_yaxis_overlay 

Overlay a line plot over an existing one, with a new vertical axis 

 

graticule 

sets the plot axis style to use a graticule (rather than tics) (See also the /GRATICULE qualifier on all plot commands, and MODE GRATICULE) 

 

tics 

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

 

gridxy 

overlays a "graticule" at the I,J grid locations (see also the /GRAT qualifier for plot commands, and MODE GRATICULE) 

 

gridxz 

overlays a "graticule" at the I,K grid locations 

 

gridxt 

overlays a "graticule" at the I,L grid locations 

 

gridyz 

overlays a "graticule" at the J,K grid locations 

 

gridyt 

overlays a "graticule" at the J,L grid locations 

 

gridzt 

overlays a "graticule" at the K,L grid locations 

 

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 

 

taylor_example1 

demonstrates tools for making Taylor diagrams 

     

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) 

 

portrait 

set window for 8.5 x 11 portrait page 

 

portrait1x2 

set window for 8.5 x 11 portrait page and two viewports 

 

portrait1x3 

set window for 8.5 x 11 portrait page and three viewports 

 

portrait1x4 

set window for 8.5 x 11 portrait page and four viewports 

 

portraitNxN 

set window for 8.5 x 11 portrait page and NxN viewports 

 

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_graticule 

overlays "map projected" graticule (color controls) 

 

mp_grid.jnl 

Associates a data grid with a predefined map projection. 

 

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_polymark 

overlays "map projected" polygons 

 

mp_polymark     

Plot polygons using a predefined map projection. 

 

mp_polytube 

 Plot a colored tube using a predefined map projection. 

 

mp_trackplot 

 Plot a trackplot using a predefined map projection 

 

 mp_viewport_aspect 

 Define a viewport for plotting map projections 

     

SAMPLING A GRIDDED FIELD 

 

bullseye 

locate a bullseye in a 2-D field 

 

digitize 

obtain data values from a plot using the cursor 

 

vertical_section 

create 2-D vertical section from a 3-D field 

 

samplexy_demo 

create 2-D vertical section along any path 

 
 

UTILITY SCRIPTS 

 

datestring.jnl 

create date string from year, month, day, etc 

 
 

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 (a maximum of 99 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: 

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 99 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,... $99 or $0 where $0 is replaced by the name of the GO tool itself.   "$*" is replaced by all the arguments as a single string, separated by spaces. 

If there are more than 9 arguments, the syntax $nn (nn may  be 1 through 99) is equivalent to to ($nn), however the parentheses enclosed form is generally preferred as it avoids ambiguities. Specifying $12.dat is equivalent to ($12).dat but is less clear. 

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 F