Personal tools
You are here: Home Documentation Users Guide 1. Introduction 1.5 GO FILES
Document Actions

1.5 GO FILES

by Catherine Nunkai — last modified 2012-08-16 14:22

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


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



1.5.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," 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 calculation

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



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


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


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



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


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

If the argument is a 2-digit number, and we are making a substitution, the replacement text goes inside the parentheses. For example, plot the variable passed as argument 1 with the color given by argument 12, or green if no argument 12 is given:

PLOT/COLOR=($12#green#) $1

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, in older Ferret versions red plot line was actually obtained by the PLOT command qualifier /LINE=2—the string "red" never appeared 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.


1.5.3.5 Documentation and checking arguments to GO tools

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


1.5.3.6 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. Note that anytime an error is issued, whether MODE IGNORE_ERROR is set or not, a symbol FER_LAST_ERROR is set, which contains the string that was written to standard error.

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 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 in the Commands Reference section of this manual for further details.


1.5.3.7 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 for further discussion of this topic.



Powered by Plone CMS, the Open Source Content Management System

This site conforms to the following standards: