An alias for DEFINE ALIAS.
Cancels a program state or definition—generally paired with a SET or DEFINE command. See commands SET (p. 290) and DEFINE (p. 253) for further information.
Arguments:
The arguments, which are names of variables, data sets, or other definitions can be specified using wildcards. The * wildcard matches any number of characters in the name; the ? wildcard matches exactly one character.
Cancels a user-defined command alias.
yes? CANCEL ALIAS ALIAS_NAME
The command UNALIAS is an alias for CANCEL ALIAS.
/MODULO
CANCEL AXIS forms the complement to DEFINE AXIS. It is also applicable to "persistent" axes which are defined by netCDF files such as climatological_axes.cdf -- axes which are not associated with any variables in the netCDF file, itself, and are not automatically deleted when the data set is canceled.
Attempts to CANCEL AXIS on a axis which is used by a variable in a currently open data set will be rejected with a message indicating the reason.
Command qualifiers for CANCEL AXIS:
CANCEL AXIS/MODULO
Cancels the modulo nature of a user-defined axis.
yes? CANCEL AXIS/MODULO my_x_axis
or
yes? CANCEL AXIS/MODULO my_t*
/ALL /NOERROR
Removes the specified data set from the list of available sets.
yes? CANCEL DATA_SET dset1, dset2, ..., dsetn
where each dset may be the name or number of a data set; or
yes? CANCEL DATA/ALL
(See also SET DATA_SET, p. 291, and SHOW DATA SET, p. 320.)
Command qualifiers for CANCEL DATA_SET:
Eliminates all data sets from the list of accessible data sets.
CANCEL DATA/NOERROR
Suppresses the error message otherwise generated when a data set that was never set is canceled. Useful in GO scripts for closing data sets that may have been opened in previous usage of the script.
Note that if a grid or axis from a netCDF file is used in the definition of a LET-defined variable (e.g. LET my_X = X[g=sst[D=coads_climatology]]) that variable definition will be invalidated when the data set is canceled (CANCEL DATA coads_climtology, in the preceding example). There is a single exception to this behavior: netCDF files such as climtological_axes.cdf, which define grids or axes that are not actually used by any variables. These grids and axes will remain defined even after the data set, itself, has been canceled. They may be deleted with explicit use of CANCEL GRID or CANCEL AXIS.
Un-specifies the current context expression. Ferret's "action" commands can be issued without an argument (e.g., yes? PLOT), in which case Ferret uses the current context expression. This expression is either the argument of the most recent action command, or an expression set explicitly with SET EXPRESSION.
yes? CANCEL EXPRESSION
The qualifier /ALL can be used with this command, but it exists for compatibility purposes only and has no effect.
CANCEL GRID forms the complement to DEFINE GRID It is also applicable to "persistent" grids which are defined by netCDF files such as climatological_axes.cdf -- grids which are not associated with any variables in the netCDF file, itself, and are not automatically deleted when the data set is canceled.
Attempts to CANCEL GRID on a grid or axis which is used by a variable in a currently open data set will be rejected with a message indicating the reason.
/ALL /APPEND /FILE /FORMAT /HEADING /PRECISION
Toggles the effects of the SET LIST command. See command SET LIST (p. 298).
yes? CANCEL LIST[/qualifiers]
Command qualifiers for: CANCEL LIST
Restores all aspects of the LIST command to their default behavior.
Resets the listed output to NOT append to existing file.
Resets the listed output to automatic file naming.
Resets the listed output to its default formatting.
Instructs listed output to omit the descriptive data header.
Resets the precision of listed data to 4 significant digits.
/ALL /PERMANENT /TEMPORARY
Clears data currently cached in memory.
yes? CANCEL MEMORY[/qualifier]
Use this command to save memory space—by clearing data as soon as it is no longer needed virtual memory requirements can be reduced. This is especially useful for efficient batch processing. Default is CANCEL MEMORY/TEMPORARY.
Example:
To produce an animation using minimal virtual memory try:
yes? REPEAT/T=lo:hi:delta GO min_mem_movie
Where the file min_mem_movie.jnl contains
CONTOUR/FRAME temp[Z=0] ! contour plot
CANCEL MEMORY/ALL ! clear memory for next time step
Command qualifiers for CANCEL MEMORY:
Clears all variables stored in memory.
Clears all "permanent" variables stored in memory (i.e., variables loaded into memory with LOAD/PERMANENT).
CANCEL MEMORY/TEMPORARY (default)
Clears all non-permanent variables stored in memory.
Sets the state of a mode to "canceled."
yes? CANCEL MODE mode_name
(See command SET MODE, p. 301, for descriptions of modes.)
This command is unnecessary in Ferret version 3.1 and later; it is provided for compatibility with older versions of Ferret. It restores the default movie file name (ferret.mgm) but is not needed to conclude capturing graphics to a movie file.
yes? CANCEL MOVIE
The qualifier /ALL can be used with this command, but it exists for compatibility purposes only and has no effect.
/ALL
Deletes a user-defined symbol (string variable) definition.
yes? CANCEL STRING[/qualifier] [symbol_name]
Command qualifiers for CANCEL SYMBOL:
CANCEL SYMBOL/ALL
Deletes all user-defined symbol definitions.
Examples:
yes? CANCEL SYMBOL my_x_label !eliminate my_x_label from the definitions
yes?
CANCEL SYMBOL *x_label !remove all strings ending in x_label
yes? CANCEL
SYMBOL/ALL !remove all user-defined symbols.
/I/J/K/L /X/Y/Z/T /ALL
Cancels part or all of the current or named region.
yes? CANCEL REGION[/qualifier] [region_name]
Examples:
yes? CANCEL REGION !clear the current region
yes? CANCEL REGION/T !eliminate T from the current context
yes? CANCEL REGION reg1 !clear the region named "reg1"
Command qualifiers for CANCEL REGION:
CANCEL REGION/I /J /K /L /X /Y /Z /T
Eliminates I, J, K, L, X, Y, Z, or T axis information from current context or named region.
Eliminates ALL stored region information (rarely used).
/ALL /DATASET
Deletes a user-defined variable definition.
yes? CANCEL VARIABLE[/qualifier] [var_name]
Command qualifiers for CANCEL VARIABLE:
Deletes all user-defined variable definitions.
Examples:
yes? CANCEL VARIABLE my_sst !eliminate my_sst from the definitions
yes?
CANCEL VARIABLE *wind !delete all variables ending in wind
yes? CANCEL
VARIABLE tau? !delete variables named tau plus one character
yes? CANCEL
VARIABLE/ALL !delete all user-defined defined variables
CANCEL VARIABLE/DATASET
Deletes user define variables associated with the
named dataset, which were defined by a DEFINE VARIABLE/DATASET command.
Cancels a defined viewport or cancels use of viewports.
yes? CANCEL VIEWPORT view_name !un-define view_name
yes? CANCEL VIEWPORT !return to full window output
/ALL
Removes graphics window(s) from the screen.
yes? CANCEL WINDOW n !or
yes? CANCEL WINDOW/ALL
Command qualifiers for CANCEL WINDOW:
Removes all graphics windows.
/I/J/K/L /X/Y/Z/T /D /FILL /FRAME /KEY /LEVELS /LINE /NOAXIS /NOKEY /NOLABEL /OVERLAY /PALETTE /PATTERN /SIZE /SPACING /SIGDIG /PEN /SET_UP /TITLE /COLOR /TRANSPOSE /HLIMITS /VLIMITS /XLIMITS /YLIMITS
Produces a contour plot.
yes? CONTOUR[/qualifiers] [expression]
Example:
yes? CONTOUR var1 !produce a contour plot of the variable var1
Parameters
Expressions may be any valid expression. See the chapter "Variables and Expressions", section "Expressions" (p. 53), for a definition of valid expressions. The expression will be inferred from the current context if omitted from the command line.
Command qualifiers for CONTOUR:
CONTOUR/I=/J=/K=/L=/X=/Y=/Z=/T=
Specifies value or range of axis subscripts (I, J, K, or L), or axis coordinates (X, Y, Z, or T) to be used when evaluating the expression being plotted.
Specifies the default data set to use when evaluating the expression being contoured.
Creates a color filled contour image.
Causes the graphic image produced by the command to be captured as an animation frame in the file specified by SET MOVIE. In general the FRAME command (p. 267) is more flexible and we recommend its use rather than this qualifier.
Displays a color key for the palette used in a color-filled contour plot. Only valid in conjunction with /FILL (default with CONTOUR/FILL or alias FILL).
Specifies the contour levels or how the levels will be determined. If the /LEVELS qualifier is omitted Ferret automatically selects reasonable contour levels.
See the chapter "Customizing Plots", section "Contouring" (p. 156) for examples and more documentation on /LEVELS and color_thickness indices. See also the demonstration "custom_contour_demo.jnl".
Overlays contour lines on a color-filled plot. Valid only with /FILL (or as a qualifier to alias FILL). When /LINE is specified the color key, by default, is omitted. Use FILL/LINE/KEY to obtain both contour lines and a color key.
Turns off display of a color key for the palette used in a color-filled contour plot. Only valid in conjunction with /FILL (or with alias FILL).
Suppresses all axis lines, tics and labeling so that no box appears surrounding the contour plot. This is especially useful for map projection plots.
Suppresses all plot labels except axis labels.
Causes the indicated expression to be overlaid on the existing plot.
Note (CONTOUR/OVERLAY with time axes):
A restriction in PPLUS requires that if time is an axis of the contour plot, the overlaid variable must share the same time axis encoding as the base plot variable. If this condition is not met, you may find that the overlaid contour fails to be drawn. The solution is to use the Ferret regridding capability to regrid the base plot variable and the overlaid plot variable onto the same time axis.
Specifies a color palette (otherwise, the current default palette is used). Valid only with CONTOUR/FILL (or as a qualifier to the alias FILL). The file suffix *.spk is not necessary when specifying a palette. Try the Unix command % Fpalette '*' to see available palettes. See command PALETTE (p. 278) for more information.
Example:
yes? CONTOUR/FILL/PALETTE=land_sea world_relief
The /PALETTE qualifier changes the current palette for the duration of the plotting command and then restores the previous palette. This behavior is not immediately compatible with the /SET_UP qualifier. See the PALETTE (p. 278) command for further discussion.
Specifies a pattern file (otherwise, the current default pattern specification is used). Valid only with CONTOUR/FILL (or as a qualifier to the alias FILL). The file suffix *.pat is not necessary when specifying a pattern. Try the Unix command % Fpattern '*' to see available patterns. See command PATTERN (p. 279) for more information.
Sets line color (replaces the /PEN qualifier). The available color names are Black, Red, Green, Blue, LightBlue, and , Purple, and White (not case sensitive), corresponding to the /PEN values 1-6, respectively. (/COLOR also accepts numerical values.).
Example:
yes? CONTOUR/COLOR=red sst
Sets line style for contour lines (same arguments as PLOT/LINE=). Argument can be an integer between 1 and 18; run GO line_samples to see the styles for color devices.
Example:
yes? CONTOUR/PEN=2 sst
Controls the size of characters in the contour labels, using PLOT+ definition of "inches" .Default is 0.8' See example under CONTOUR/SPACING below.
Sets the number of significant digits for contour labels. Default is 2. See example under CONTOUR/SPACING below.
Sets spacing for contour lines, using PLOT+ definition of "inches". The default spacing is 5.0. (See the CONSET command in the on-line PLOT+ Users Guide)
Example o f CONTOUR/SIZE/SIGDIG/SPACING
yes? LET my_field = SIN(X[x=1:6:.1])*COS(Y[y=1:6:0.1])
yes? CONTOUR/SIGDIG=1/SIZE=0.15/SPACING=3
my_field
Specifies contour labels with a single significant digit using characters of height 0.15 "inches" at a nominal spacing of 3 "inches", consistent with the PLOT+ usage of "inches". (These are the same units as in, say, "ppl axlen 8,6", to specify plot axes of lengths 8 and 6 inches for horizontal and vertical axes, respectively.) Note that the PLOT+ CONPRE and CONPST commands are also useful, giving control over the text font and color used in the labels and adding units to the labels. For example, the commands
yes? PPL CONPRE @C002@CR
yes? PPL CONPST cm/sec
will transform the labels in the above CONTOUR example to red (002), Complex Roman font with a units label of "cm/sec".
CONTOUR/SET_UP
Performs all the internal preparations required by program Ferret for contouring but does not actually render output. The command PPL can then be used to make changes to the plot prior to producing output with the PPL CONTOUR command. This permits plot customizations that are not possible with Ferret command qualifiers. See the chapter "Customizing Plots", section "Contouring" (p. 156).
Allows user to specify a plot title (enclosed in quotation marks). Without this qualifier Ferret selects a title based on information about the expression. To include font change and color_thickness specifications (e.g., @TI@C002) in the title string, it is necessary either to CANCEL MODE ASCII or to include a leading ESC (escape) character.
Causes the horizontal and vertical axes to be interchanged. By default the X and T axes of the data are drawn horizontally on the plot and the Y and Z axes of the data are drawn vertically. For Y-Z plots the Z data axis is vertical by default.
Note that plots in the YT and ZT planes have /TRANSFORM applied by default in order to achieve a horizontal T axis. See /XLIMITS (below) for further details. Use /TRANSPOSE manually to reverse this effect.
Specifies axis range and tic interval for the horizontal axis. Without this qualifier, Ferret selects reasonable values.
yes? CONTOUR/HLIMITS=lo_val:hi_val[:increment] [expression]
The optional "increment" parameter determines tic mark spacing on the axis. If the increment is negative, the axis will be reversed.
The /HLIMITS and /VLIMITS qualifiers will retain their "horizontal" and "vertical" interpretations in the presence of the /TRANSPOSE qualifier. Thus, the addition of /TRANSPOSE to a plotting command mandates the interchange of "H" and "V" on the limits qualifiers.
Specifies the axis range and tic interval for the vertical axis. See /HLIMITS (above)
CONTOUR/XLIMITS=
Note: XLIMITS and YLIMITS have been denigrated. Please
use HLIMITS and VLIMITS instead.
Specifies axis range and tic interval for the X axis. Without this qualifier, Ferret selects reasonable values.
yes? CONTOUR/XLIMITS=lo_val:hi_val[:increment] [expression]
The optional "increment" parameter determines tic mark spacing on the axis. If the increment is negative, the axis will be reversed.
Note that the "X" in /XLIMITS refers to the horizontal axis of the plot rather than to the X axis of the grid. This can lead to confusion, especially on plots in the YT or ZT plane. Plots in these planes are automatically transposed to place the Y or Z axis, respectively, on the vertical axis of the plot. Plots may also be transposed manually with the /TRANSPOSE qualifier. On transposed plots /XLIMITS will refer to the vertical axis of the plot.
Note: XLIMITS and YLIMITS have been denigrated. Please use HLIMITS and
VLIMITS instead.
Specifies the axis range and tic interval for the Y axis.
See /XLIMITS (above).
Defines a new alias, region, grid, axis, variable, or viewport.
Defines an alias for a command. "ALIAS" is an alias for DEFINE ALIAS.
yes? DEFINE ALIAS NAME COMMAND
Example:
yes? DEFINE ALIAS SDF SHOW DATA/FULL
/X/Y/Z/T /DEPTH /FILE /FROM_DATA /MODULO /NAME /NPOINTS /T0 /UNITS /EDGES
Defines an axis (axis name up to 16 characters).
yes? DEFINE AXIS[/qualifiers] axis_name
or
yes? DEFINE AXIS[/qualifiers]
axis_name = expr
Example:
yes? DEFINE AXIS/X=140E:140W:.2 AX140
or
yes? DEFINE AXIS/X myaxis =
{1, 5, 15, 35}
Command qualifiers for DEFINE AXIS:
Specifies the limits and point spacing of an axis.
yes? DEFINE AXIS/X=lo:hi:delta axis_name
The limits may be in longitude, latitude, or date format (for X, Y, or T axis, respectively) or may be simple numbers. No units are assumed unless units are given explicitly with the /UNITS qualifier.
Use /UNITS=degrees to obtain latitude or longitude axes. The X or Y qualifier determines which orientation "degrees" refers to.
For T axis, the limits may be dates (dd-mmm-yyyy:hh:mm:ss) or may be time steps. The delta increment is regarded as hours unless the /UNITS qualifier specifies otherwise.
If the time limits are given as dates then this axis produces date-formatted output (unless CANCEL MODE CALENDAR is issued). If the time limits are given as time steps then all instances of this axis are labeled with time step values in the units specified with the /UNITS qualifier.
Examples (evenly-spaced axes):
yes? DEFINE AXIS/X=140E:140W:.2 ax140
yes? DEFINE AXIS/Y=15S:25N:.5 axynew
yes? DEFINE AXIS/Z=0:5000:20/UNITS=CM/DEPTH axzcm
yes? DEFINE AXIS/T="7-NOV-1953":"23-AUG-1988:11:00":24 axtlife
yes? DEFINE AXIS/T=25:125:5/UNITS=minutes axt5min
Specifies the Z axis to be a depth, positive downward, axis. A depth axis is indicated by a "(-)" following its title in a SHOW GRID or SHOW AXIS command. Depth axes are notated by "UD" (up-down) in the grid definition file, while normal vertical axes (such as an elevation axis in meteorology) are notated by "DU" (down-up).
Example:
yes? DEFINE AXIS/Z=0:5000:20/DEPTH/UNITS=CM AXZDCM
The /EDGES qualifier indicates that the coordinates provided refer to the edges or boundaries between grid cells. When /EDGES is used, the coordinates of the grid points will be computed at the midpoints between the indicated edges. When /EDGES is used in conjunction with /FROM_DATA the number of grid points created will be equal to the number of coordinates minus one, since the list of edges includes both the upper and lower edge of the axis. An example of defining an axis by its edges is
yes? DEFINE AXIS/Z=0:5010:20/EDGES/DEPTH/UNITS=CM AXZDCM
A class of especially important uses for the /EDGES qualifier is to create custom calendar axes. This example creates a true monthly axis, with axis cells beginning on the first of each month:
yes? let month = MOD(l-1,12)+1
yes? let add_year = INT((l-1)/12)
yes? let
tstep = DAYS1900(1980+add_year,month,1)
yes? define axis/from_data/T/units=days/name=tax/t0=1-jan-1900/edges
tstep[l=1:`20*12+1`]
The following example shows the computation of a custom climatological average. Given, for example, a multi-year time series of a daily measured variable, the climatological average of the variable for two unequal time periods could be computed by creating an axis with two points, using the FROM_DATA qualifier. The grid cells for these two points would extend from 15-Mar to 27-May (about 73 days), and from 27-May to 15-Mar (about 292 days). The actual dates on which the 2 points are located would be the midpoints of these two intervals, on 20-apr and 20-oct.
yes? define axis/t=1-jan-0001:1-jan-0002:1/unit=days/t0=1-jan-0000 tencoding
yes?
let tstep = t[gt=tencoding]
yes? let start_date = tstep[t=15-mar-0001]
yes?
let end_date = tstep[t=27-may-0001]
yes? define axis/from_data/T/units=days/name=tax/t0=1-jan-0000/edges/modulo
{`start_date,p=7`,`end_date,p=7`,`start_date+365.2425,p=7`}
yes? def grid /t=tax taxgrid
yes? sh/l=1:2 grid taxgrid
GRID TAXGRID
name axis # pts start
end
normal X
normal Y
normal Z
TAX TIME
2mi 20-APR 12:00 20-OCT 02:54
L T BOX_SIZE TIME_STEP (DAYS)
1> 20-APR 12:00:00 73 475.5
2> 20-OCT
02:54:35 292.2425 658.1212
Reads a gridfile for grid and axis definitions. The gridfile specified should be in the standard TMAP gridfile format. There are several documents in $FER_DIR/doc regarding gridfiles and TMAP format (e.g., "about_grid_files.txt").
yes? DEFINE AXIS/FILE=grid_file.grd
Used only in conjunction with /NAME to define an axis from any expression that Ferret can evaluate.
yes? DEFINE AXIS/FROM_DATA/NAME=axis_name expr
(This is a mechanism to convert dependent variables into independent axis data.)
When defining an axis from a LET-defined variable or expression the condensed syntax (e.g.)
yes? DEFINE AXIS/X axname=expression
replaces the older (still supported) syntax
yes? DEFINE AXIS/X/NAME=axname/FROM_DATA expression
Note that the values from which the axis is to be created must be in strictly increasing order. If the coordinates are repeated, Ferret will "micro-adjust" the values by adding multiples of 1 millionth of the axis range to the repeated values. Ferret will issue an informative message if it is micro-adjusting an axis.
Example (unevenly-spaced axis):
yes? DEFINE AXIS/FROM_DATA/X/NAME=my_xaxis pos[D=2]^0.5
defines each coordinate of the axis "my_xaxis" as the square root of variable "pos" from data set 2.
Specifies that the axis being defined be treated as modulo; that is, the first point will wrap around and follow the last point (e.g., a longitude axis).
Used only in conjunction with /FROM_DATA to specify the name of the axis to be defined.
yes? DEFINE AXIS/FROM_DATA/NAME=axis_name expr
Specifies the number of coordinate points on the axis being defined.
yes? DEFINE AXIS/Z=lo:hi/NPOINTS=n ax_name
This qualifier can be used instead of specifying Z=lo:hi:delta.
Specifies the date and time associated with the time step value 0.0
Example:
DEFINE AXIS/T="1-NOV-1980":"15-AUG-1988":72/T0="1-JAN-1800" TNEW
Note: The /T0 qualifier is optional; the underlying time step values are
transparent to Ferret users for most purposes. The default value is 15-JAN-1901.
Specifies the units of the axis being defined.
A DEFINE AXIS command such as DEFINE AXIS/X=130E:80W:2 xax infers from
the formatting of the longitude coordinates the implied qualifier "/UNITS=degrees".
Similar for latitudes.
Example:
yes? DEFINE AXIS/Z=0:2000:100/UNITS=CM ZCM
Any string (up to 10 characters) is acceptable as a units string, but only
the following units are recognized and used when computing axis transformations:
NOTES:
1) As of Ferret version 5.1 the definition of the unit "month" has been
redefined to be exactly 1/12 of a climatological year. This change applies
both to files that use "units=months" and to the DEFINE VARIABLE command.
The climatological month is the length of an average month in the Gregorian
calendar, including leap years -- 1/12 or 365.2485 days. Thus the command
yes? DEFINE AXIS/T0=1-JAN-0000/T=0:12:1/EDGES/units=months/MODULO month_reg
defines a climatological monthly axis which does not "drift" over time
due to leap years. This non-drift behavior can be observed using a commands
like
yes? SHOW AXIS /l=1:12001:1200 month_reg
which will show every 100th January over 1000 years.
2) The units dbar and mbar are recognized by Ferret, however, no automatic
conversion is attempted between these and any other units.
Ferret will convert recognized units of length to meters and recognized
units of time to seconds during transformations such as integration (@IIN
and @DIN) and differentiation (@DDB, @DDC, @DDF) (see "General Information
about transformations," p. 76). Using this characteristic it is always possible
to query Ferret about the conversion factors from meters or seconds by
integrating a grid cell of width one on an axis of the units in question.
For example:
yes? ! query conversion factor to meters
Axes which are "in use", because they are used by currently open data sets
may now be redefined using DEFINE AXIS.
Previously attempting to redefine an in-use axis generated an error.
This feature is especially useful to correct the interpretation of erroneous
files, or files which exhibit minor incompatibilities with Ferret. Use
this feature with caution as it can be used to "fool" Ferret into an incorrect
interpretation of a data file.
/X/Y/Z/T /FILE /LIKE
Defines a grid (name may be up to 16 characters).
yes? DEFINE GRID[/qualifiers] grid_name
Example:
yes? DEFINE GRID/LIKE=temp/T=my_t_axis my_grid
Command qualifiers for DEFINE GRID:
Specifies what particular axis is to be the X, Y, Z, or T axis for this
grid.
yes? DEFINE GRID/X=axname grid_name
The name axname may be the name of an axis, the name of a grid that uses
the axis desired, or the name of a variable for which the defining grid
uses the axis desired.
For example,
yes? DEFINE GRID/X=U gx
will create a grid named gx which is one-dimensional—normal to Y, Z, and
T.
Note: Many axes possess an orientation implicit in their units, especially
latitude, longitude, and time axes. The effects of using an axis in an
inappropriate orientation, such as /X=time_axis, are unpredictable.
Reads a gridfile for GRID and AXIS definitions. The gridfile specified
should be in the standard TMAP gridfile format. There are several documents
in $FER_DIR/doc regarding gridfiles and TMAP format (e.g., about_grid_files.txt).
Example:
yes? DEFINE GRID/FILE=new_grids.grd
Specifies a particular grid (by name or by reference to a variable defined
on that grid) to use as a template to create a new grid.
yes? DEFINE GRID/LIKE=grid_or_variable_name grid_name
All axes of the grid being created will be identical to the axes of the
"LIKE=" grid except those explicitly changed with the /X, /Y, /Z, or /T
qualifiers.
Example:
yes? DEFINE GRID/LIKE=temp[D=2]/Z=ZAX gnew !temp from data set 2
Examples: DEFINE GRID
1) yes? DEFINE AXIS/T="1-JAN-1980":"31-DEC-1983":24 axday
2) yes? DEFINE GRID/LIKE=temp[D=ba022]/T=sst[D=nmc] gnmc3d
3) yes? DEFINE AXIS/X=140E:140W:.2 xnew
/I/J/K/L /X/Y/Z/T /DI/DJ/DK/DL /DX/DY/DZ/DT /DEFAULT
Defines or redefines a named region_name (first 4 characters are recognized).
yes? DEFINE REGION[/qualifiers] region_name
If the qualifier /DEFAULT is not given only those axes explicitly named
will be stored. If the qualifier /DEFAULT is given all axes will be stored.
Command qualifiers for DEFINE REGION:
DEFINE REGION/I=/J=/K=/L=/X=/Y=/Z=/T=
Specifies region limits ( =lo:hi or =val).
DEFINE REGION/DI=/DJ=/DK=/DL=/DX=/DY=/DZ=/DT=
Specifies a change in region relative to the current settings (=lo:hi
or =val). See examples below.
Saves all axes and transformations, not just those explicitly given. Commonly,
a GO script begins with "DEFINE REGION/DEFAULT save" and ends with "SET
REGION save".
Examples: DEFINE REGION
1) yes? DEFINE REGION/DEFAULT save
2) yes? DEFINE REGION/X xonly
3) yes? DEFINE REGION/DX=-5 xonly
4) yes? DEFINE REGION/Y=20S:20N/Z yanz
5) yes? DEFINE REGION/DEFAULT/L=5 l5
6) yes? DEFINE REGION/DL=-1:+1 lp2
Allows the user to define a string variable. Symbol names must begin with
a letter and contain only letters, digits, underscores, and dollar signs.
yes? DEFINE symbol symbol_name=string
Example:
yes? DEFINE symbol my_x_label = sample number
/D /QUIET /TITLE /UNITS /BAD=
Allows the user to define a variable from a valid algebraic expression.
Note: LET is an alias for DEFINE VARIABLE.
yes? DEFINE VARIABLE[/qualifiers] name=expression
Example:
yes? LET SPEED = U^2 + V^2
Parameters
The expression may be any valid expression. See the chapter "Variables
and Expressions", section "Expressions" (p. 53) for a definition of valid
expressions.
The name specified with DEFINE VARIABLE can be 1 to 24 characters in length—letters,
digits, $ and _, beginning with a letter. Pseudo-variable, operator, and
function names are reserved and cannot be used (I, J, EQ, SIN,...). See
the chapter "Variables and Expressions" (p. 47) for recognized pseudo-variables,
operators, and functions.
If the name defined is the same as a variable name in a data set, the user-defined
variable is used instead of the file variable. (Look for LET/D=d_set to
control this behavior in future Ferret versions.)
To enter expressions in Reverse Polish ordering see SET MODE POLISH (p.
307).
Examples:
1) yes? DEFINE VARIABLE sum = a+b
2) yes? DEFINE VARIABLE/TITLE="velocity"/UNIT="m/sec" pos[T=@DDC]*0.01
Command qualifiers for DEFINE VARIABLE:
Allows user to control the missing value of user-defined variables The
specified value will be used whenever the variable is LISTed (or SAVEd)
to a file. Note that the missing value will revert to its default (-1E34)
when this variable is combined in further calculations.
Example:
yes? let/bad=3 gap_3 = I[I=1:5]
DEFINE VARIABLE/D=dataset
Restricts the scope of the variable name to the named data set. See further
discussion in the chapter "Variables and Expressions", section "Defining
New Variables" (p. 100).
The qualifier "DATASET=" (LET/DATASET=...) allows you detailed control
over the multiple use of the same name. If the name or number of a
data set is supplied then the /dataset qualifier indicates that this variable
name is to be defined only in the specified data set. For example
yes? LET/dataset=coads_climatology V_geostrophic = SLP[X=@DDC]/(F*RHO)
Defines V_geostrophic only in data set coads_climatology. In other data
sets the name V_geostrophic may refer to file variables or it may be given
different definitions or it may be undefined. The data set may be specified
either by name as in this example or by number as shown by SHOW DATA. Note
that variables defined using LET/dataset=[name_or_number] will be shown
in the SHOW DATA output for that data set as well as in SHOW VARIABLES.
If the /dataset qualifier is applied without specifying a data set name
then the interpretation is different. In this case the named variable becomes
a default definition -- one which applies only if a data-set specific variable
of the same name does not exist. For example, if the command
yes? LET/DATASET sst = temp[Z=0]
is issued then sst[D=levitus_climatology] will evaluate to temp[D=levitus_climatology,Z=0]
because the variable sst does not exist in levitus_climatology, but sst[D=coads_climatology]
will refer to the file variable name sst within the coads_climatology data
set.
LET/D is especially useful for editing data sets because it gives a ready
way to distinguish between the pre-edit and post-edit versions of the variable.
In this example we edit the data set etopo60, replacing a small rectangle
in the Pacific Ocean.
Example:
! Do not use memory-cached data when editing.
yes? SET MODE STUPID
! Save an exact copy of the original data for editing.
Suppresses message that, by default, tells you when you are redefining
an existing variable. This qualifier is useful in command files. (This
is the default behavior starting with Ferret version 5.2)
Specifies a title (in quotation marks) for the user-defined variable. This
title will be used to label plots and listings. If no title is specified
the text of the expression will be used as the title. (See also SET VARIABLE/TITLE,
p. 313.)
Specifies the units (in quotation marks) of the variable being defined.
(See command SET VARIABLE/UNITS, p. 313.)
/CLIP /ORIGIN /SIZE /TEXT /XLIMITS /YLIMITS
Defines a new viewport (a sub-rectangle of the graphics window).
yes? DEFINE VIEWPORT[/qualifiers] view_name
Issuing the command SET VIEWPORT is best thought of as entering "viewport
mode." While in viewport mode all previously drawn viewports remain on
the screen until explicitly cleared with either SET WINDOW/CLEAR or CANCEL
VIEWPORT. If multiple plots are drawn in a single viewport without the
use of /OVERLAY the current plot will erase and replace the previous one;
the graphics in other viewports will be affected only if the viewports
overlap. If viewports overlap the most recently drawn graphics will always
lie on top, possibly obscuring what is underneath. By default, the state
of "viewport mode" is canceled.
Example:
yes? DEFINE VIEWPORT/XLIMITS=0,.5/YLIMITS=0,.5 LL
Defines a viewport that will place graphical output into the lower left
quarter of the screen, and names the viewport "LL".
Command qualifiers for DEFINE VIEWPORT.
This qualifier is obsolete; see XLIMITS= and /YLIMITS= (below). Specifies
the location of the upper right corner of the viewport.
This qualifier is obsolete; see /XLIMITS= and /YLIMITS= (below). Specifies
the location of the lower left corner of the viewport.
This qualifier is obsolete; see /XLIMITS and /YLIMITS (below). Specifies
the scaling factor to use relative to the size of the full window.
Controls shrinkage (or expansion) of text.
yes? DEFINE VIEWPORT/TEXT=n view_name
In some cases text appearance may become unacceptable due to viewport size
and aspect specifications. A value of 1 produces text of the same size
as in the full window; 0 < n < 1 shrinks the text; n > 1 enlarges text.
Sensible values go up to about 2. When the qualifier /TEXT is omitted,
Ferret computes a text size that is appropriate to the size of the viewport.
Note that /TEXT modifies the prominence of the text through manipulation
of axis lengths rather than through direct manipulation of the many text
size specifications. A low value of text prominence produces axes that
are "long" (as seen with SHOW SYMBOLS, p. 169, or PPL LIST XAXIS, p. 138), making
the (fixed size) text appear less prominent.
DEFINE VIEWPORT/XLIMITS=/YLIMITS=
Specifies the portion of the full window to be used.
yes? DEFINE VIEWPORT/XLIMITS=x1,x2/YLIMITS=y1,y2 view_name
The values of the limits must be in the range [0,1]; they refer to the
portion of the window (of height and length 1) which defines the viewport.
Together, /XLIMITS and /YLIMITS replace the CLIP, ORIGIN, and SIZE qualifiers
in older Ferret versions.
The ELIF command is a part of Ferret's conditional command execution capability:
IF-THEN-ELIF-ELSE-ENDIF. It is valid only inside of an IF block. See further
description under the IF command (p. 269) in this Commands Reference section.
The ELSE command is a part of Ferret's conditional command execution capability:
IF-THEN-ELIF-ELSE-ENDIF. It is valid only inside of an IF block. See further
description under the IF command (p. 269) in this Commands Reference section.
The ENDIF command is a part of Ferret's conditional command execution capability:
IF-THEN-ELIF-ELSE-ENDIF. It is valid only inside of an IF block. See further
description under the IF command (p. 269) in this Commands Reference section.
/COMMAND_FILE
When issued interactively this command terminates program Ferret.
When executed within a command file this command terminates the execution
of the command file and returns control to the level in Ferret that executed
the file (the user or another command file).
When executed from within a command file EXIT/COMMAND_FILE forces an immediate
exit from Ferret rather than returning control to the user or another command
file.
The FILE command is an alias for SET DATA/EZ (p.295 ). All qualifiers and
restrictions are identical to SET DATA/EZ
Example:
yes? FILE/VARIABLES="u,v" velocities.dat
Alias for CONTOUR/FILL (color-filled contour plot). All qualifiers and
restrictions are identical to CONTOUR/FILL.
Example:
yes? FILL/PAL=land_sea etopo60
/FORMAT /FILE
Saves the current graphics display image as a frame in the movie file initialized
with the command SET MOVIE. FRAME is also a qualifier for the "action"
commands PLOT, CONTOUR, POLYGON, SHADE, VECTOR and WIRE.
yes? CONTOUR my_var
yes? FRAME
Note that FRAME follows a command which creates an image.
FRAME/FORMAT=format controls the format of the file produced.
FRAME/FORMAT=HDF appends an HDF raster 8 drawn to the specified or implied
input file. The default format is HDF.
FRAME/FORMAT=GIF creates a new GIF file, any existing GIF file with the
specified or implied name using relative version number or less. Note that
in this mode of grabbing an image Ferret creates a GIF by requesting the
image back from your screen (your X server). This means that the X server
normally has to be configured as pseudo-color. An alternative approach
which does not share this restriction is to start Ferret with "ferret -gif"
(see p. 6)
FRAME/FILE=filename specifies the name of the output file. If /FORMAT is
not specified the output format is inferred from filename extensions of
.hdf, .HDF, .gif, or .GIF.
The maximum filename length, including path, that is allowable is 255 characters.
/HELP
Executes a list of commands stored in a file.
yes? GO file_name
If no filename extension is specified a default of .jnl will be assumed.
If the full path is specified then the filename must be enclosed in double
quotation marks.
The GO command can pass arguments to the script (tool) it executes. See
the introductory chapter, section "Writing GO Tools" (p. 19) for more information.
Arguments to the GO command may be separated by blanks or commas. To specify
multiple words as a single argument, enclose them in quotation marks. To
specify an argument that is deliberately omitted, use " " or two consecutive
commas.
The response of Ferret to errors encountered during execution of the command
file is determined by mode IGNORE_ERRORS. (See command SET MODE, p. 301.)
The echoing of command file lines is controlled by mode VERIFY.
The GO command understands a special syntax called "relative version numbers."
If a filename is specified for the GO command which has a version value
of zero or less its value is interpreted as relative to the current highest
version number. See the chapter "Computing Environment", section "Relative
version numbers" (p. 194) for a discussion of relative version numbers of
files.
Note: The command SET MODE IGNORE_ERRORS is useful when rerunning past
sessions which may have errors.
The command GO/HELP filename opens the named script with the Unix "more"
command and displays the first 20 lines of the named file. Use this command
to quickly see the documentation in a GO script.
On Unix systems interactive Ferret help is available from the command line
with the commands Fapropos, Fhelp, and Ftoc. 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 command "fg" will then restore
the suspended session.
See the introductory chapter, section "Unix on-line help" (p. 26) for more
information.
Ferret provides an IF-THEN-ELSE syntax to allow conditional execution of
commands. It may be used in two styles—single line and multi-line. In both
the single and multi-line styles the true or false of the IF condition
is determined by case-insensitive recognition of one of these options:
TRUE condition:
FALSE condition:
Examples:
Embedded (grave accent) expressions can be used in conjunction with the
IF syntax. For example, `3 GT 2` (Is three greater than 2?) evaluates to
"1" (TRUE) and `3 LT 2` (Is three less than 2?) evaluates to "0" (FALSE).
If the result of a grave accent expression is invalid, for example division
by zero as in `1/0`, the string "bad" is, by default, generated. Thus invalid
expressions are regarded as FALSE.
Symbol substitution permits IF decisions to be based on text-based conditions.
Suppose, for example, the symbol ($DSET) contains either coads or levitus.
Then an IF condition could test for coads using ($DSET%|coads>TRUE|%*>FALSE%).
IF ($DSET%|coads>TRUE|*>FALSE%) THEN
The single line style allows IF-THEN-ELSE logic to be applied on a single
line. For example, to make a plot only when the surface (Z=0) temperature
exceeds 22 degrees we might use
IF `TEMP[X=160W,Y=2N,Z=0] GT 22` THEN PLOT TEMP[X=160W,Y=2N]
The single line syntax may be any of the following:
IF condition THEN clause_1
Note that both ELSE and ENDIF are optional in the single line syntax. Groups
of commands enclosed in parentheses and separated by semicolons can be
used as clause_1 or as clause_2. There is no ELIF (pronounced "else if")
statement in the single line syntax. However, IF conditions can be nested
as in
IF `i1 GT 5` THEN (IF `j1 LT 4` THEN go option_1 ELSE go option_2)
The multi-line style expands the IF capabilities by adding the ELIF statement.
Multi-line IF statement follows the pattern
IF condition_1 THEN
clause_1_line_1
clause_1_line_2
...
ELIF condition_2 THEN
clause_2_line_1
...
ELIF condition_3 THEN
...
ELSE
...
ENDIF
Note that THEN is optional at the end of IF and ELIF statements but the
ENDIF statement is required to close the entire IF block. Single line IF
statements may be included inside of multi-line IF blocks.
Also note that this usage is different from the "masking" IF-THEN-ELSE
logic; they share keywords but have different usage. See p. 92
/NOUSER
Places a label on the current plot; alias for PPL %LABEL. %LABEL is one
of PPLUS's primitive plot commands. It places a label on the plot immediately
after being issued (rather than deferring placement). PPLUS does not assign
numbers to labels created with LABEL, so they cannot be manipulated as
movable labels. The label can also be placed on the plot using the mouse
to point and click (see the chapter "Customizing Plots", section "Positioning
labels using the mouse pointer," p. 143).
yes? LABEL xpos, ypos, center, angle, size text
See the chapter "Customizing Plots", section "Labels" (p. 138) for examples.
Command qualifiers for LABEL:
Locates labels in inches instead of user units (xpos and ypos are specified
in inches rather than in world coordinates).
The LET command is an alias for DEFINE VARIABLE (p.262 ). All qualifiers and
restrictions are identical to DEFINE VARIABLE.
Example:
yes? LET A = B
/I/J/K/L /X/Y/Z/T /D /ILIMITS /JLIMITS /KLIMITS /LLIMITS /XLIMITS /YLIMITS
/ZLIMITS /TLIMIT /APPEND /FILE /FORMAT /HEADING /NOHEAD /TITLE /ORDER /RIGID
/PRECISION /CLOBBER /SINGLE /QUIET
Produces a listing of the indicated data.
LIST[/qualifiers] [expression_1 , expression_2 , ...]
Example:
yes? LIST/Z=10 u , v , u^2 + v^2
Lists the 3 quantities specified using the current default data set and
region (at depth 10).
Parameters
Expressions may be any valid expression. See the chapter "Variables and
Expressions", section "Expressions" (p. 53) for a definition of valid expressions.
If multiple variables or expressions are specified they may be listed together
in columns or in sequence depending on the /SINGLY qualifier. The expression(s)
will be inferred from the current context if omitted from the command line.
If multiple expressions are given on the command line and /SINGLY is not
specified, then the expressions must be conformable. See the chapter "Variables
and Expressions", section "Multi-dimensional expressions" (p. 54) for a definition
of conformable expressions. Degenerate or single point axis limits will
be promoted up (values repeated) as needed.
Example:
yes? LIST/I=1:3/J=1:2 i+j, i
Command qualifiers for LIST:
LIST/I= /J= /K= /L=/X= /Y= /Z= /T=
Specifies value or range of axis subscripts (I, J, K, or L), or axis coordinates
(X, Y, Z, or T) to be used when evaluating the expression(s) being listed.
LIST/ILIMITS=/JLIMITS=/KLIMITS=/LLIMITS=
Specifies the size of the desired NetCDF output file independently from
the actual data being saved. By specifying axis limits in excess of the
saved expression's limits it is possible to /APPEND data later. (See the
chapter "Converting to NetCDF", section "Simple Conversions Using Ferret,"
p. 195, ex. 4).
LIST/XLIMITS=/YLIMITS=/ZLIMITS=/TLIMITS=
Specifies the size of the desired NetCDF output file independently from
the actual data being saved. By specifying axis limits in excess of the
saved expression's limits it is possible to /APPEND data later. (See the
chapter "Converting to NetCDF", section "Simple Conversions Using Ferret,"
p. 195, ex. 4).
Specifies the default data set to be used when evaluating the expression(s)
being listed.
Use this qualifier together with the /FILE qualifier to indicate that the
listed data should be appended to a pre-existing file. If no file exists
by the name indicated a new file is created. This qualifier is not applicable
to /FORMAT=GT. When used with /FORMAT=CDF it permits any data in the file
to be overwritten, new variables to be added to the file, and appending
of new indices along the T axis of the variables in the file. This qualifier
overrides the command CANCEL LIST/APPEND.
Names a file to receive the listed data. If /FILE is specified with no
name then the default name is used from the SET LIST/FILE command.
Example:
yes? LIST/FILE=my_file.dat sst[D=coads_climatology]
See command SET LIST (p. 298) for further information on automatic filename
generation.
Used with LIST/FILE. Indicates that any existing file with the name used
is to be deleted, before writing. If CLOBBER is not specified and the
file exists, and error message is given.
Example:
yes? LIST/FILE=my_file.dat/CLOBBER sst[D=coads_climatology]
Specifies an output format ( =format_choice) for the data to be listed.
yes? SET LIST/FORMAT=format_choice
FORTRAN format
produces ASCII output
"UNFORMATTED"
produces unformatted (binary) output using FORTRAN record structure
"CDF"
produces NetCDF format output
"GT"
produces TMAP GT format
"STREAM"
produces unstructured binary floating point (C-style)
"tab"
produces tab-delimited output
"comma"
produces comma-delimited output
This command has the same function as SET LIST/FORMAT except that it does
not affect future LIST commands. See command SET LIST/FORMAT (p. 299) for
detailed documentation.
Notes for LIST/FORMAT:
1) All output values, regardless of the /FORMAT designation, will be of
type single precision floating point. For FORTRAN output formats this means
all numerical field specifiers must be "F", "E", or "G".
2) For FORTRAN-formatted and UNFORMATTED (binary) output, the contents of
a single output "record" are determined by the /ORDER qualifier. For example,
each record will be a line of Y values for LIST/ORDER=YX. If /ORDER is
omitted, the records will be the first output axis of greater than unity
length taken in the order X, Y, Z, then T. FORTRAN-formatted output records
may be further split by the usual rules of FORTRAN output formatting.
3) FORTRAN formats must be enclosed in parentheses. If blanks are included
in the format it must be enclosed in quotation marks. Output strings are
permitted in the format.
Example:
yes? LIST/FORMAT=("The temperature is:", F6.3) sst[X=180, Y=0]
4) When FORTRAN formats are used, and more than one value per record is
desired, the /ORDER qualifier ( p276) must be used, even if the variable
is defined along only one axis.
Example:
yes? LIST/FORMAT=(8F6.3)/ORDER=T sst[X=180, Y=0]
5) The default listing style includes labels for the rows and columns of
the output. When a FORTRAN format is specified, these labels are omitted.
6) On Unix systems the /FORMAT=UNFORMATTED specifier produces FORTRAN-style
variable-length records. On most implementations this means that a 4-byte
field containing the record length begins and ends each record of data.
7) The command alias SAVE is provided for the commonly used LIST/FORMAT=CDF.
NetCDF outputs are self-documenting, including grid definitions. The output
files can be used as input with the command USE—alias for SET DATA/FORMAT=CDF.
See command SAVE (p. 289) for further notes about NetCDF files.
For ASCII data listings this command determines whether to precede the
listing with a heading describing data set, variable and region. This qualifier
overrides the CANCEL LIST/HEAD command.
For ASCII data listings this qualifier determines whether to precede the
listing with a heading that describes the data set, variable, and region.
This qualifier overrides the CANCEL LIST/HEAD command. When the argument
/HEADING=ENHANCED is used a self-documenting heading is provided that includes
the axis coordinates.
For NetCDF output files (alias SAVE) the /HEADING=ENHANCED option causes
the NetCDF file structure to include extra coordinate information that
describes how the particular data subset being written fits within the
broader coordinate system of the grid from which it is extracted. When
a NetCDF file with an enhanced heading is accessed by Ferret (using SET
DATA or USE) the index values will appear to be consistent with the parent
data set.
Does not precede listing with a heading describing data set, variable and
region. This qualifier overrides the SET LIST/HEAD command.
Specifies the order (ORDER=permutation) in which axes are to be laid out
in the listing.
Examples:
yes? LIST/ORDER=XY sst !X varies fastest
yes? LIST/ORDER=YX sst !Y varies fastest
The "permutation" string may be any permutation of the letters X, Y, Z,
and T. /ORDER is applicable only to /FORMAT=unf and FORTRAN formats.
Note that a 1-dimensional list will, by default, place only one value per
record. The /ORDER qualifier can cause the 1-dimensional list to occur
in a single record. For example,
LIST/I=1:5 I
will list as 5 records whereas
LIST/I=1:5 /ORDER=X I
will list 5 values on a single record.
Controls the digit precision of LIST output
Using the qualifier /PRECISION=#digits the output precision of the LIST
command may be easily controlled. This qualifier functions exactly as does
the SET LIST/PRECISION= command but it applies only to the current command.
Using the qualifier /QUIET will prevent the message "LISTing to file XXXX.XXXX"
from being displayed.
Valid only with /FORMAT=CDF. Indicates that Ferret should not create a
NetCDF "record" axis as the time axis for any of the variables listed with
this command. Time axes are, instead, of fixed length and the /APPEND qualifier
is not usable to extend the listing.
This qualifier is relevant only when multiple expressions are specified
in the LIST command. When the /SINGLY qualifier is specified the entire
listing of each expression including (optional) heading and all data is
completed before proceeding to the next expression.
By default the expressions are not listed singly—each line contains one
value of each expression. The qualifier has no effect if only a single
expression is specified. If the /FILE qualifier is specified to use automatic
filename generation and /APPEND is not specified, then each expression
is listed to a separate file.
Valid only with /FORMAT=CDF. Causes the global attribute "title" to be
defined in a NetCDF file, thereby setting its title.
/I/J/K/L /X/Y/Z/T /D /NAME /PERMANENT /TEMPORARY
Loads a variable or expression into memory.
yes? LOAD[/qualifiers] [expression_1 , expression_2 , ...]
Loading may speed execution of later commands that will require the loaded
data. Often it is helpful to LOAD a large region of data encompassing several
small regions in which the analysis will be pursued.
Load interacts with the current context exactly as other "action" commands
CONTOUR, PLOT, SHADE, VECTOR, LIST, etc. do.
Parameters
Expressions may be any valid expression. See the chapter "Variables and
Expressions", section "Expressions" (p. 53) for a definition of valid expressions.
If multiple variables or expressions are specified they are treated in
sequence. The expression(s) will be inferred from the current context if
omitted from the command line.
Command qualifiers for LOAD:
Specifies value or range of axis subscripts (I, J, K, or L), or axis coordinates
(X, Y, Z, or T) to be used when evaluating the expression(s) being loaded.
Specifies the default data set to be used when evaluating the expression(s)
being loaded.
Obsolete. Provided for compatibility with much older Ferret versions.
Data loaded with LOAD/PERMANENT are kept in memory until a LOAD/TEMPORARY
command is given that refers to the same data. See command LOAD/TEMPORARY
(p. 278). Note that this command may cause memory fragmentation. It should
generally be given immediately following CANCEL MEMORY and preferably is
used only to load file variables (as opposed to expressions).
Data loaded with LOAD or LOAD/TEMPORARY is brought into memory but may
be unloaded based on a priority scheme of least recent use when memory
space is required.
/CONTINUE /QUIET /JOURNAL /ERROR
Displays a message at the terminal.
yes? MESSAGE text
By default a carriage return is required from the keyboard for program
execution to continue (used to halt the execution of a command file).
Command qualifiers for MESSAGE:
Continues program execution following the display of the message text without
waiting for a carriage return from the operator.
Writes the message to the journal file.
Writes the message to standard error.
Waits for a carriage return from the operator but does not supply a prompt
for it.
Alias for PPL SHASET SPECTRUM=. Specifies or restores the default color.
yes? PALETTE pal_name
The argument is the name of a palette file. Many palettes are included
in the Ferret distribution. Try the Unix command "Fpalette '*'" to see
a list of available palette files.
Some of the palettes are designed for particular needs. "centered.spk",
for example, emphasizes the contrast between positive and negative shade
levels. "land_sea.spk" uses blue tones for negative values and browns and
greens for positive values, making it suitable for topography displays.
Palette files end in the file suffix .spk, but the suffix is not necessary
when specifying a palette. Use GO try_palette pal_name to display a palette.
The GO files "exact_color.jnl" and "squeeze_colors.jnl" can be used to
modify palettes. You can also create new palette files with a text editor.
See the chapter "Customizing Plots", section "Shade and fill colors" (p.
147) for the format of a palette file.
PALETTE with no argument restores the default palette. When you use the
qualifier /PALETTE= in conjunction with /SET_UP, PPLUS makes the specified
color spectrum the new default palette, and all subsequent shaded or color-filled
plots will use that palette as the default. To restore the previous palette
to the default, use PALETTE with no argument after your customization.
Alias for PPL PATSET PATTERN=. Specifies or restores the default pattern.
The argument is the name of a pattern file. Many patterns are included
in the Ferret distribution. Try the Unix command "Fpattern '*'" to see
a list of available pattern files.
Ferret has the capability to make
color fill plots using solid color only
, and also with
colors laid on in patterns.
The PATTERN command sets the patterns to be used in a plot generated with
the SHADE, FILL and POLYGON commands. It is similar to the PALETTE command,
which sets colors, but the PALETTE and PATTERN commands act independently.
When Ferret is started up, only one pattern is set, SOLID. The SOLID pattern
is equivalent to not using any pattern, and SHADE, FILL and POLYGON fill
their cells with solid color.
Pattern files end in the file suffix .pat, but use of the suffix is not
necessary when specifying a pattern. Use GO try_pattern patt_name to display
the patterns specified in a pattern file. GO show_all_patterns draws a
plot showing
all the available pattern files and their names. Notice that patterns can be used with a single
color, or multiple colors, depending entirely on the PALETTE specification.
A pattern file may specify one or more patterns. If there are fewer patterns
specified in a pattern file than there are levels in a particular plot,
the patterns will be repeated.
Alias for MESSAGE
/I/J/K/L /X/Y/Z/T /D /FRAME /LINE /NOLABEL /OVERLAY/SET_UP /SYMBOL /TITLE
/TRANSPOSE /VS /HLIMITS /VLIMITS /XLIMITS /YLIMITS /COLOR /SIZE /THICKNESS
yes? PLOT[/qualifiers] [expression_1 , expression_2 , ...]
The indicated expression(s) must represent a line (not a plane) of data
(PLOT/VS is an exception). Unless the /VS qualifier is used, the independent
variable is the underlying coordinate axis for this line of data.
Example:
yes? PLOT/l=1:100 sst
produces a time series plot of the first 100 points of sst.
Parameters
The argument(s) for PLOT specify the variable or expression to be plotted.
When the /VS qualifier is used the indicated expressions may have any geometry
in 4D space but they must match in the total number of points in each expression.
The points are associated in the order of their underlying axes. When
the /VS qualifier is not used the indicated expression(s) must describe
a line (not a plane) of data.
The expression(s) are inferred from the current context if omitted from
the command line—i.e., if no expression is given then the argument most
recently given is used, or the default expression may be explicitly set
with SET EXPRESSION.
When Ferret plots multiple data lines simultaneously, PPLUS automatically
cycles through pen colors and symbols, creating up to 26 distinct line
types. Try GO line_samples to see
samples of these styles.
Command qualifiers for PLOT:
Specifies value or range of axis subscripts (I, J, K, or L), or axis coordinates
(X, Y, Z, or T) to be used when evaluating the expression(s) being plotted.
Specifies the default data set to be used when evaluating the expression(s)
being plotted.
Causes the graphic image produced to be captured as an animation frame
and written to the movie file specified by SET MOVIE. In general the FRAME
command (p. 267) is more flexible and we recommend its use rather than this
qualifier.
Simple syntax for line plots. For line plots it is possible with these
qualifiers to control line thickness and color with commands such as
yes? PLOT/COLOR=blue/THICK=2 I[i=1:3]
This is equivalent to the (still supported) use of the /LINE qualifiers
in
yes? PLOT/LINE=10 I[i=1:3] ! 4(blue) + 6*(2-1)
The available color names are Black, Red, Green, Blue, LightBlue, Purple,
and White (not case sensitive), corresponding to the /LINE values 1-6,
respectively. (/COLOR also accepts numerical values.) The line thickness
may be 1, 2, or 3 corresponding to pixel thickness on the screen or corresponding
to multiples of the default line thickness on hard copy. Note that White
is only available for THICKNESS=1 (the default thickness).
PLOT/COLOR=/SIZE=/THICKNESS=
yes? PLOT/COLOR=red/SIZE=0.2/THICKNESS=2/SYMBOL=4 I[i=1:5]
The available color names are Black, Red, Green, Blue, LightBlue, Purple,
and White (not case sensitive), corresponding to the /LINE values 1-6,
respectively. (/COLOR also accepts numerical values.) The line thickness
may be 1, 2, or 3 corresponding to pixel thickness on the screen or corresponding
to multiples of the default line thickness on hard copy; note that White
is only available in the default THICKNESS=1. The /SIZE is given in units
of "inches", consistent with the PLOT+ usage of "inches". (These are the
same units as in, say, "ppl axlen 8,6", to specify plot axes of lengths
8 and 6 inches for horizontal and vertical axes, respectively.)
The /LINE qualifier without =n causes the PLOT command to connect the plotted
points with a line regardless of the state of the /SYMBOLS qualifier.
For simpler specification of line characteristics see PLOT/COLOR=/THICKNESS=
above ( p. 281) . /LINE=n specifies the line style. "n" is an integer between
1 and 18. GO line_thickness
draws
samples of the available line styles
.
Line style "1" is always a solid line
in the foreground color (black or white). Other line styles are device
dependent (colors or dash patterns). For color devices, n=1–6 draws single-thickness
lines each a different color. n=7–12 draws double-thick lines in the same
color order, and n=13–18 draws triple-thick lines. See the chapter "Customizing
Plots", section "Text and line colors" (p. 145) for a chart of the default
colors.
Suppresses all plot labels except axis labels.
Causes the indicated field(s) to be overlaid on the existing plot. This
qualifier can also be used to overlay lines or symbols on 2D plots (SHADE,
CONTOUR, or VECTOR) provided the axis scalings are appropriate.
Performs all the internal preparations required by program Ferret for plotting
but does not actually render the plot. The command PPL can then be used
to make changes to the plot prior to producing output with the PPL PLOT
command. This makes possible certain customizations that are not possible
with Ferret command qualifiers. See the chapter "Customizing Plots" (p.
131).
The /SYMBOL qualifier causes the PLOT command to mark each plotted point
with a symbol. If the /LINE qualifier is given too the symbols are also
connected with a line; if /LINE is omitted no connecting line is drawn.
Optionally, the symbol number may be explicitly specified as an integer
value between 1 and 88. The integer refers to the PPLUS plot marker numbers
(e.g., 1 for x, 3 for +, etc.). Type "GO show_symbols" and "GO show_88_syms"
at the Ferret prompt to see
available symbols and their reference numbers. The symbols are also documented on page
1 of the document $FER_DIR/doc/pplus_fonts.ps.
Allows user to specify a plot title (enclosed in quotation marks). Without
this qualifier Ferret selects a title based on information about the expression(s).
To include font change and color_thickness specifications (e.g., @TI@C002)
in the title string, it is necessary either to CANCEL MODE ASCII or to
include a leading ESC (escape) character.
Causes the horizontal and vertical axes to be interchanged. By default
the X axis is drawn horizontally on the plot and the Y and Z axes are drawn
vertically. For Y-Z plots the Z data axis is vertical by default.
Specifies that the first expression given in the command line is to be
used as the independent axis.
Example:
yes? PLOT/Y=20S:20N/X=180/T=27740:27741/Z=100/VS temp , salt
Produces a plot of salinity (vertical axis) against temperature (horizontal
axis) along the indicated range of latitudes and times. The plot will be
labeled "salt"; the vertical (dependent) variable is the one that determines
the key. The qualifier /TRANSPOSE can be used in conjunction with /VS to
further manipulate the labeling and axis orientation.
PLOT/VS implies /SYMBOL by default to produce scatter plots. Use PLOT/VS/LINE
to produce a line plot.
Specifies axis range and tic interval for the horizontal axis. Without
this qualifier Ferret selects a reasonable range.
yes? PLOT/HLIMITS=lo:hi:[increment] [expression(s)]
The optional "increment" parameter determines tic mark spacing on the axis.
If the increment is negative, the axis is reversed.
The /HLIMITS and /VLIMITS qualifiers will retain their "horizontal" and
"vertical" interpretations in the presence of the /TRANSPOSE qualifier.
Thus, the addition of /TRANSPOSE to a plotting command mandates the interchange
of "H" and "V" on the limits qualifiers.
Specifies the axis range and tic interval for the vertical axis. See /HLIMITS
(above).
Note: XLIMITS and YLIMITS have been denigrated. Please use HLIMITS and
VLIMITS instead.
Specifies axis range and tic interval for the X axis. Without this qualifier
Ferret selects a reasonable range.
yes? PLOT/XLIMITS=lo:hi:[increment] [expression(s)]
The optional "increment" parameter determines tic mark spacing on the axis.
If the increment is negative, the axis is reversed.
Note that the "X" in /XLIMITS refers to the horizontal axis of the plot
rather than to the X axis of the grid. Plots may be transposed manually
with the /TRANSPOSE qualifier. On transposed plots /XLIMITS will refer
to the vertical axis of the plot.
Note: XLIMITS and YLIMITS have been denigrated. Please use HLIMITS and
VLIMITS instead.
Specifies the axis range and tic interval for the Y axis. See /XLIMITS
(above).
/I/J/K/L/X/Y/Z/T/OVERLAY/SET_UP/FRAME/D /TRANSPOSE /COORD_AX /SYMBOL /NOLABELS
/LEVELS /LINE /COLOR /PALETTE /TITLE /THICKNESS /XLIMITS /YLIMITS /NOAXES
/PATTERN /FILL /KEY /NOKEY/HLIMITS /VLIMITS
Produces a color-filled or line plot of polygons. By default a color key
is drawn and lines are not drawn.
POLYGON[/qualifiers] x-vertices, y-vertices [, values]
Parameters
The two x- and y- vertices parameters separately specify the x and y coordinates
of the vertices of the polygons to be plotted.
The values may be any valid expression. If a color-filled plot is specified,
the numerical value of the expression associated with each polygon determines
the color of that polygon, as in SHADE and FILL plots. See the chapter
"Variables and Expressions", section "Expressions" (p. 53) for a definition
of valid expressions. If values are omitted the /FILL option is not valid—only
/LINE plots may be made.
Example:
yes? LET XTRIANGLE = YSEQUENCE({-1,0,1})
Command qualifiers for POLYGON:
POLYGON /I=/J=/K=/L=/X=/Y=/Z=/T=
Specifies value or range of axis subscripts (I, J, K, or L), or axis coordinates
(X, Y, Z, or T) to be used when evaluating the expression being plotted.
Specifies the default data set to be used when evaluating the expression
being plotted.
Causes the graphic image produced by the command to be captured as an animation
frame in the file specified by SET MOVIE. In general the FRAME command
(p. 267) is more flexible and we recommend its use rather than this qualifier.
Displays a color key for the palette used in the color-filled plot. By
default a key is drawn unless the /LINE or /NOKEY qualifier is specified.
Specifies the POLYGON levels or how the levels will be determined. If the
/LEVELS qualifier is omitted Ferret automatically selects reasonable POLYGON
levels.
See the chapter "Customizing Plots", section "Contouring" (p. 156) for examples
and more documentation on /LEVELS.
Outlines polygons specified by x and y vertices on a POLYGON plot. When
/LINE is specified the color key is omitted unless specifically requested
via /KEY.
Simple specification of outline characteristics f or polygon plots which
specify an outline line we control line thickness and color with commands
such as
yes? POLYGON/LINE/COLOR=blue/THICK=2 {1,2,1}, {3,2,1}
This is equivalent to the (still supported) use of the /LINE qualifiers
in
yes? POLYGON/LINE=10 {1,2,1}, {3,2,1} ! 4(blue) + 6*(2-1)
The available color names are Black, Red, Green, Blue, LightBlue, Purple,
and White (not case sensitive), corresponding to the /LINE values 1-6,
respectively. (/COLOR also accepts numerical values.) The line thickness
may be 1, 2, or 3 corresponding to pixel thickness on the screen or corresponding
to multiples of the default line thickness on hard copy, however the color
White is only available in the default THICKNESS=1.
COLOR
Specifies the POLYGON levels or how the levels will be determined. If the
/LEVELS qualifier is omitted Ferret automatically selects reasonable P
Suppresses the drawing of a color key for the palette used in the plot.
Suppresses all plot labels except axis labels.
Causes the indicated POLYGON plot to be overlaid on the existing plot.
Specifies a color palette (otherwise, a default rainbow palette is used).
Try the Unix command % Fpalette '*' to see available palettes. The file
suffix *.spk is not necessary when specifying a palette. See command PALETTE
(p. 278) for more information.
The /PALETTE qualifier changes the current palette for the duration of
the plotting command and then restores the previous palette. This behavior
is not immediately compatible with the /SET_UP qualifier. See the PALETTE
command (p. 278) for further discussion.
Specifies a pattern file (otherwise, a default SOLID pattern is used).
Try the Unix command % Fpattern '*' to see available pattern files. The
file suffix *.pat is not necessary when specifying a pattern file. See
command PATTERN (p. 279) for more information.
Performs all the internal preparations required by program Ferret for a
POLYGON plot but does not actually render output. The command PPL can then
be used to make changes to the plot prior to producing output with the
PPL FILLPOL command. This permits plot customizations that are not possible
with Ferret command qualifiers. See the chapter "Customizing Plots" (p.
131).
Allows user to specify a plot title (enclosed in quotation marks). Without
this qualifier Ferret selects a title based on information about the expression(s).
To include font change and color_thickness specifications (e.g., @TI@C002)
in the title string, it is necessary either to CANCEL MODE ASCII or to
include a leading ESC (escape) character. See the chapter "Customizing
Plots", section "Fonts" (p. 151).
yes? POLYGON/TITLE="title string" x-vertices, y-vertices, values
Causes the horizontal and vertical axes to be interchanged. By default
the X axis is drawn horizontally on the plot and the Y and Z axes are drawn
vertically. For Y-Z plots the Z data axis is vertical.
Note that plots in the YT and ZT planes have /TRANSFORM applied by default
in order to achieve a horizontal T axis. See /XLIMITS (below) for further
details. Use /TRANSPOSE manually to reverse this effect.
Specifies the horizontal axis range and tic interval (otherwise, Ferret
selects reasonable values).
yes? POLYGON/HLIMITS=lo:hi:increment
The optional "increment" parameter determines tic mark spacing on the axis.
If the increment is negative, the axis will be reversed.
The /HLIMITS and /VLIMITS qualifiers will retain their "horizontal" and
"vertical" interpretations in the presence of the /TRANSPOSE qualifier.
Thus, the addition of /TRANSPOSE to a plotting command mandates the interchange
of "H" and "V" on the limits qualifiers.
Specifies the vertical axis range and tic interval. See /HLIMITS (above)
POLYGON/XLIMITS=
Specifies the X axis range and tic interval (otherwise, Ferret selects
reasonable values).
yes? POLYGON/XLIMITS=lo:hi:increment
The optional "increment" parameter determines tic mark spacing on the axis.
If the increment is negative, the axis will be reversed.
Note that the "X" in /XLIMITS refers to the horizontal axis of the plot
rather than to the X axis of the grid. This can lead to confusion, especially
on plots in the YT or ZT plane. Plots in these planes are automatically
transposed to place the Y or Z axis, respectively, on the vertical axis
of the plot. Plots may also be transposed manually with the /TRANSPOSE
qualifier. On transposed plots /XLIMITS will refer to the vertical axis
of the plot.
Note: XLIMITS and YLIMITS have been denigrated. Please use HLIMITS and
VLIMITS instead.
/RESET
Invokes PPLUS ("PLOT PLUS" written by Don Denbo), to execute a command
or commands.
yes? PPLUS !(also PPL); invokes PPLUS interactively
yes? PPL pplus_command !executes a single PPLUS command
yes? PPL/RESET !restores PPLUS to start-up defaults
Example:
yes? PPL CROSS 1 !reference line through zero
Executes the PPLUS command "CROSS" and immediately returns control to
Ferret.
When PPLUS is invoked interactively the prompt is "PPL>" instead of the
usual "yes?". The EXIT command given at the "PPL>" prompt returns control
to Ferret.
See the chapter "Customizing Plots" (p. 131) for more information on Ferret/PPLUS
interactions. A complete list of PPLUS commands is in PLOT PLUS for Ferret
User's Guide.
Command Qualifiers for PPLUS:
Restores PPLUS to start-up settings.
Alias for EXIT; also just Q.
/I/J/K/L /X/Y/Z/T
Repeats a command or group of commands over a range of values along an
axis.
yes? REPEAT/q=lo:hi[:increment] COMMAND
The units of lo, hi, and increment are the units of the underlying grid
axis if the qualifier is X, Y, Z, or T. The qualifiers I, J, K, or L advance
the repeat loop by incrementing the indicated index (the default index
increment is 1). Use SHOW GRID to examine the axis units (if the units
are not displayed try CANCEL MODE LATITUDE, LONGITUDE, or CALENDAR as appropriate).
To run the loop from the highest value decreasing towards the lowest value,
specify increment to be less than zero. Any command or group of commands
that can be specified at the command line can also be given as an argument
to REPEAT. If MODE VERIFY is SET, the current loop index is displayed at
the console as REPEAT executes.
Examples:
1) yes? REPEAT/L=1:240 CONTOUR/Y=30S:50N/X=130E:70W/LEV/FRAME sst
2) yes? REPEAT/Z=300:0:-30 GO compz
3) yes? REPEAT/L=1:250:5 (GO set_up; CONTOUR sst; FRAME)
Command qualifiers for REPEAT:
REPEAT/I=/J=/K=/L=/X=/Y=/Z=/T=
Repeats the requested command(s) for the specified range of axis subscripts
(I, J, K, or L) or axis coordinates (X, Y, Z, or T). Note that when T axis
limits are specified as dates, the units of increment are hours.
The SAVE command is an alias for LIST/FORMAT=CDF (p.274 ). All qualifiers
and restrictions are identical to LIST/FORMAT=CDF.
Example:
yes? SAVE temp, salt
is identical to
yes? LIST/FORMAT=CDF temp, salt
Notes:
1) Gaps in NetCDF outputs are filled with the missing value flag of the
variable being written. (See the chapter "Variables and Expressions", section
"Missing value flags," p. 51.) In the example below, if "temp" and "salt"
share the same time axis then the L=2:4 values of salt will be so filled.
yes? SAVE/FILE=test.cdf temp[L=1:5], salt[L=1], salt[L=5]
2) Transformations that compress an axis to a point produce results that
Ferret regards as time-independent. Thus, this 12-month average:
yes? SAVE/FILE=annual.cdf sst[L=1:12@AVE]
creates a NetCDF file with no time axis. It would not be possible to append
the average of the next 12 months as the next time step of this file. However,
a time location can be inherited from another variable. In this example,
we inherit the time axis of "timestamp" in order to create a time axis
in the NetCDF file.
yes? DEFINE AXIS/T="1-JUL-1980":"1-JUL-1985"/UNIT=year tannual
yes? DEFINE GRID/T=tannual gannual
yes? LET timestamp = T[G=gannual] * 0 !always 0
yes? LET sst_ave = sst[L=1:12@AVE] + timestamp
yes? SAVE/FILE=annual.cdf sst_ave[L=1]
yes? LET sst_ave = sst[L=13:24@AVE] + timestamp
yes? SAVE/FILE=annual.cdf/APPEND sst_ave[L=2]
.
.
. etc.
3) Background documentation about the definition and data set of origin
for a variable are saved in the "history" attribute of a variable when
it is first saved in the NetCDF file. If the definition of the variable
is then changed, and more values are inserted into the file using SAVE/APPEND,
the modified definition will NOT be documented in the output file. If the
new definition changes the defining grid for the variable the results will
be unpredictable.
Sets features of the operating environment for program Ferret.
Generally, features may be toggled on and off with SET and CANCEL. Features
affected by SET may be examined with SHOW (see also CANCEL, p. 243, and SHOW,
p. 319).
/MODULO
Indicates that an axis is to be treated as a modulo axis (the first point
"wraps" and follows the last point, as in a longitude axis).
yes? SET AXIS/MODULO x_ax
Indicates that an axis is to be treated as a depth axis (graphics made
with positive down).
/EZ /VARIABLE /TITLE /FORMAT /GRID /SKIP /COLUMNS /SAVE /RESTORE /ORDER
/TYPE /SWAP /REGULART
SET DATA/EZ /COLUMNS /FORMAT /GRID /SKIP /TITLE /VARIABLE
Specifies ASCII, binary, NetCDF, GT, or TS-formatted data set(s) to be
analyzed.
1) ASCII or binary:
yes? SET DATA/EZ[/qualifiers] data_set1, data_set2, …
or equivalently, with alias FILE:
yes? FILE[/qualifiers] data_set1, data_set2, ...
2) NetCDF:
yes? SET DATA/FORMAT=cdf NetCDF_file
or equivalently, with alias USE
yes? USE NetCDF_file
3) GT or TS-formatted:
yes? SET DATA data_set1, data_set2, ...
In the case of GT or TS-formatted files, an extension of .des is assumed.
A previously SET data set can be SET by its reference number, as shown
by SHOW DATA, rather than by name.
If a Unix filename includes a path (with slashes) then the full path plus
name must be enclosed in double quotation marks.
yes? use "/home/mydirectory/mydata/new_salinity.cdf"
If the filename begins with a numeric character, Ferret does not recognize
the file, but it can be specified using the Unix pathname, e.g.
yes? use "./123"
or
yes? file/var=a "./45N_180W.dat"
Note: Maximum simultaneous data sets: 60 (as of Ferret ver. 3.1). Use
CANCEL DATA if the limit is reached.
Command qualifiers for SET DATA_SET:
Specifies the format of the data set(s) being SET. Allowable values for
"file_format" are "cdf", "free", "unformatted", "stream" or a FORTRAN
format in quotation marks and parentheses.
yes? SET DATA/FORMAT=file_format [data_set_name_or_number]
Valid arguments for /FORMAT=
1) free (default for SET DATA/EZ)
2) cdf
Example:
yes? SET DATA/FORMAT=CDF my_netcdf
or equivalently,
yes? USE my_netcdf
See the chapter "Data Set Basics", section "NetCDF data, p. 30."
Command qualifiers for SET DATA_SET/FORMAT:
SET DATA /FORMAT=CDF /ORDER=<permutation> /REGULART
The permutation argument contains information both about the order of the
axes in the file and the direction.
The order indicated through the /ORDER qualifier should always be exactly
the reverse of the order in which the dimensions of variables as revealed
by the netCDF ncdump -h command are declared. (This ambiguity reflects
the linguistic difference between "C ordering" and "FORTRAN ordering".
The default X-Y-Z-T ordering used in the COARDS standard and in Ferret
documentation would be referred to as T-Z-Y-X ordering if we used C terminology.)
Thus, to USE a file in Ferret in which the data on disk transposes the
X and Y axes we would specify
USE/ORDER=YX my_file.nc
To use a file in which the data were laid down in XZ "slabs", such as might
occur in model outpus we would specify
USE/ORDER=XZYT my_model.nc
To indicate that the coordinates along a particular axis are reversed
from the "right hand rule" ordering, for example a Y axis which runs north
to south (not uncommon in image data), we would precede that axis by a
minus sign. For example
USE/ORDER=-XY my_flipped_images.nc
The minus sign should be applied to the axis position **after** transposition.
Thus if a file both transposed the XY axis ordering and used north-to-south
ordering in latitude one would access the file with
USE/ORDER=Y-X my_transposed_flipped_images.nc
NetCDF files, while in principle self-documenting, may be contain axis
ambiguities. For example, a file which is supposed to contain a time series,
but lacks units on the coordinate variable in the file may appear to be
a line of data on the X axis. The /ORDER qualifier can be used to resolve
these ambiguities. For this example, one would initialize the file with
the command
USE/ORDER=T my_ambiguous_time_series.nc
Notes for USE/ORDER:
1) Note that specifying USE/ORDER=XYZT is not always equivalent to specifying
default ordering. For example, if a netCDF file contained variables on
an XYT grid, the /ORDER=XYZT specifaction would tell Ferret to interpret
it as an XYZ grid.
2) Also note, the /ORDER qualifier will be ignored if either the file is
not netCDF, or the file is netCDF but has an "enhanced" header (see SAVE/HEADING=enhanced,
p 275)
3) unformatted
4) FORTRAN format string
Example:
yes? SET DATA/EZ/FORMAT="(5X,F12.0)" my_data_set
or equivalently,
yes? FILE/FORMAT="(5X,F12.0)" my_data_set
5) stream (Ferret version 3.1)
This format specifier allows you to access any contiguous stretch of 4-byte
values from the file. The /SKIP=n qualifier specifies how many values should
be skipped at the file start. The /GRID=name qualifier specifies the grid
onto which the data should be read and therefore the number of values to
be read from the file (the number of points in the grid). Note that an
attempt to read more data than the file contains, or to read record length
information, will result in a fatal FORTRAN error on UNIX systems and will
crash the Ferret program.
For multiple variables, use the /COLUMNS=n specifier to specify how many
4-byte values separate each variable in the file. Each variable is assumed
to represent a contiguous stream of values within the file and all variables
are assumed to possess the same number of points. (A "poor man's" method
is to create multiple Unix soft links pointing to the same file and multiple
SET DATA/EZ commands to specify one variable from each link name.)
See the chapter "Data Set Basics", section "Binary data" (p. 33) for further
discussion and examples of binary types.
Speeds initialization of large netCDF data sets with known regular time
axes. When Ferret initializes a netCDF file (the SET DATA/FORMAT=cdf command
or the USE command alias), it checks for the attribute point_spacing
= "even" on the time axis. If found, Ferret knows that the coordinates
are evenly spaced and reads only the first and last coordinate on the axis
to obtain a complete description. If not found, Ferret must read the full
list of coordinates -- a time-consuming procedure for very large files.
After reading the coordinates, Ferret determines if they are regular. The
/REGULART qualifier instructs Ferret to treat the time axis as regular
regardless of the presence or absence of a point_spacing attribute in the
file, speeding up the initialization time on files lacking point_spacing,
but known to be regular.
Note that when writing netCDF files Ferret, by default, does NOT include
the point_spacing attribute. This is because Ferret's default file characteristic
is to be append-able, with no guarantees that the appended time steps will
be regularly spaced. For output files of fixed length with regular time
steps it is advisable to use the SAVE/RIGID qualifier. This allows Ferret
to include the point_spacing="even" attribute. If the files will be very
large (too large for the full time range to be in memory), then use the
/RIGID/TLIMITS= qualifiers to specify the full, ultimate fixed size and
use SAVE/APPEND to insert data into the file piecemeal.
Restores the current default data set number that was saved with SET DATA/SAVE.
This is useful in creating GO files that perform their function and then
restore Ferret to its previous state.
Saves the current default data set number so it can be restored with SET
DATA/RESTORE.
This is useful in creating GO files that perform their function and then
restore Ferret to its previous state.
Accesses data from an ASCII or unformatted file that is not in a standardized
format (TMAP or NetCDF). The command FILE is an alias for SET DATA/EZ.
yes? SET DATA/EZ[/qualifiers] ASCII_or_binary_file
or, equivalently,
yes? FILE[/qualifiers] ASCII_or_binary_file
Example:
yes? FILE/VARIABLE=my_var my_data.dat
See the chapter "Data Set Basics", section "ASCII data" (p. 37) for more
information and examples.
Command qualifiers for SET DATA_SET/EZ:
Specifies the number of columns in the EZ data file.
By default the number of columns is assumed to be equal to the number of
variables (including "-"'s) specified by the /VARIABLES qualifier.
Specifies the defining grid for the data in the EZ data set. The argument
can be the name of a grid or the name of a variable that is already defined
on the desired grid.
Example:
yes? SET DATA/EZ/GRID=sst[D=coads] snoopy
This is the mechanism by which the shape of the data (1D along T axis,
2D in the XY plane, etc.) is specified. By default Ferret uses grid EZ,
a line of up to 20480 points oriented along the X axis.
SET DATA/EZ/ORDER= (Ferret version 3.11)
Specifies the order (ORDER=permutation) in which axes are to be read.
Examples:
yes? FILE/ORDER=XY sst !X varies fastest
yes? LIST/ORDER=YX sst !Y varies fastest
The "permutation" string may be any permutation of the letters X, Y, Z,
and T. If the /format=stream qualifier is used, the string may also contain
V (for variable). This allows variables to be "interleaved."
Specifies the number of records to skip at the start of an EZ data set
before beginning to read the data. By default, no records are skipped.
For ASCII files a "record" refers to a single line in the file (i.e., a
newline character). If the FORMAT statement contains slash characters the
"data record" may be multiple lines; the /SKIP qualifier is independent
of this fact.
For FORTRAN-structured binary files the /SKIP argument refers to the number
of binary records to be skipped.
For unstructured (stream) binary files (e.g., output of a C program) the
/SKIP argument refers to the number of words (4-byte quantities) to skip
before reading begins.
Stream files only. Change the byte ordering of numbers read from the file;
big-endian numbers are converted to little-endian numbers and vice versa.
Associates a title with the data set.
yes? SET DATA/EZ/TITLE="title string" file_name
This title appears on plotted outputs at the top of the plot.
Stream files only. Specify the data type of a set of variables in a stream
file. Available values and their corresponding types are:
Value
FORTRAN
C
size in bytes
i1
INTEGER*1
char
1
i2
INTEGER*2
short
2
i4
INTEGER*4
int
4
r4
REAL*4
float
4
r8
REAL*8
double
8
yes? SET DATA/EZ/FORMAT=STREAM/TYPE=14,R4/VAR=V1,V2 foobar.dat
will read a file containing INTEGER*4 and REAL*4 numbers into the variables
v1 and v2.
Names the variables of interest in the file. Default is v1.
yes? FILE/VARIABLES="var1,var2,..." file_name
Except in the case of /FORMAT=stream, Ferret assumes that successive values
in the data file represent successive variables. For example, if there
are three variables in a file, the first value represents the first variable,
the second represents the second variable, the third the third variable,
and the fourth returns to representing the first variable. The maximum
number of variables allowed in a single data set is 20.
Variable names may be 1 to 24 characters (letters, digits, $, and _) beginning
with a letter. To indicate a column is not of interest use "-" for its
name.
Example: (the third column of data will be ignored)
yes? SET DATA/EZ/VARIABLES="temp,salt,-,u,v" ocean_file.dat
Specifies the default context expression. When Ferret's "action" commands
(PLOT, CONTOUR, SHADE, VECTOR, WIRE, etc.) are issued with no argument,
the default context expression is used. This is the expression last used
as argument to an action command, or it may be set explicitly with SET
EXPRESSION. See the chapter "Variables and Expressions", section "Expressions"
(p. 53) for a full list of action commands.
yes? SET EXPRESSION expr1 , expr2 , ...
Examples:
1) yes? SET EXPRESSION temp
2) yes? SET EXPRESSION u , v , u^2 + v^2
/RESTORE /SAVE
Specifies the default grid for abstract expressions. Type GO wire_frame_demo
at the Ferret prompt for an example of usage.
yes? SET GRID[/qualifier] [grid_or_variable_name]
Examples:
yes? SET GRID sst[D=coads]
yes? SET GRID ! use grid from last data accessed
See the chapter "Grids and Regions" (p. 103).
Command qualifiers for SET GRID:
Restores the current default grid last saved by SET GRID/SAVE. Useful together
with SET GRID/SAVE to create GO files that restore the state of Ferret
when they conclude.
Saves the current default grid to be restored later. Useful together with
SET GRID/RESTORE to create GO files that restore the state of Ferret when
they conclude.
/APPEND /FILE /FORMAT /HEADING /PRECISION
Uses SET LIST to specify the default characteristics of listed output.
yes? SET LIST/qualifiers
The state of the list command may be examined with SHOW LIST. See command
CANCEL LIST (p. 245) and LIST (p. 272).
Command qualifiers for SET LIST:
Specifies that by default the listed output is to be appended to a pre-existing
file. Cancel this state with CANCEL LIST/APPEND.
Specifies a default file for the output of the LIST command.
yes? SET LIST/FILE=filename
The filename specified in this way is a default only. It will be used by
the command
yes? LIST/FILE variable
but will be ignored in
yes? LIST/FILE=snoopy.dat variable
Ferret generates a filename based on the data set, variable, and region
if the filename specified is "AUTO". The resulting name is often quite
long but may be shortened by following "AUTO" with a minus sign and the
name(s) of the axes to exclude from the filename.
Note: the region information is not used in automatic NetCDF output filenames.
Examples:
yes? SET LIST/FILE=AUTO
yes? LIST/L=500/X=140W:110W/Y=2S:2N/FILE sst[D=coads]
Sends data to file WcoadsSST.X140W110WY2S2NL500.
yes? SET LIST/FILE=AUTO-XY
yes? LIST/L=500/X=140W:110W/Y=2S:2N/FILE sst[D=coads]
Sends data to file WcoadsSST.L500.
Specifies an output format for the LIST command. (When a FORTRAN format
is specified the row and column headings are omitted from the output.)
yes? SET LIST/FORMAT=option
yes? SET LIST/FORMAT !reactivate previous format
Options
FORTRAN format
produces ASCII output
"UNFORMATTED"
produces unformatted (binary) output
"CDF"
produces NetCDF output
"GT"
produces TMAP GT format
Examples:
1) yes? SET LIST/FORMAT=(1X,12F6.1)
2) yes? SET LIST/FORMAT=UNFORMATTED
Notes:
Specifies that ASCII output is to be preceded by a heading that documents
data set, variable, and region. Cancel the heading with CANCEL LIST/HEAD.
Specifies the data precision (number of significant digits) of the output
listings. This qualifier has no effect when /FORMAT= is specified.
yes? SET LIST/PRECISION=#_of_digits
/SIZE
yes? SET MEMORY/SIZE=megawords
The command SET MEMORY provides control over how much "physical" memory
Ferret can use. (In reality the distinction between physical and virtual
memory is invisible to Ferret. The SET MEMORY command merely dictates how
much memory Ferret can attempt to allocate from the operating system.)
SET MEMORY controls only the size of Ferret's cache memory—memory used
to hold intermediate results from computations that are in progress and
used to hold the results of past file IO and computations for re-use. The
default size of the memory cache is 3.2 megawords (equivalently, 3.2×4=12.8
megabytes). Cache memory size can be set larger or smaller than this figure.
Example:
yes? SET MEMORY/SIZE=4.2
Sets the size of Ferret's memory cache to 4.2 million (4-byte) words.
Notes:
/LAST
Specifies special operating modes or states for program Ferret.
yes? SET MODE[/LAST] mode_name[:argument]
Default
ASCII_FONT
imposes PPLUS ASCII font types on plot labels
set
CALENDAR
uses date strings for T axis (vs. time step values)
set
DEPTH_LABEL
uses "DEPTH" as Z axis label
set
DESPERATE
attempts calculations too large for memory
canceled
DIAGNOSTIC
turns on internal program diagnostic output
canceled
GUI
unsupported; used in GUI development
IGNORE_ERROR
continues command file after errors
canceled
INTERPOLATE
automatically interpolates data between planes
canceled
JOURNAL
records keyboard commands in a journal file
set
LATIT_LABEL
uses "N" "S" notation for labeling latitudes
set
LONG_LABEL
uses "E" "W" notation for labeling longitudes
set
METAFILE
captures graphics in GKS metafiles
canceled
POLISH
interprets expressions in Reverse Polish order
canceled
PPLLIST
listed output from PPLUS is directed to the named file
canceled
REFRESH
refreshes graphics on systems lacking "backing store"
canceled
SEGMENT
utilizes GKS segment storage
set
STUPID
controls cache hits in memory (diagnostic)
canceled
VERIFY
displays each command file line as it is executed
set
WAIT
waits for carriage return after each plot
canceled
Command qualifiers for SET MODE:
Resets mode to its last state.
yes? SET MODE/LAST mode_name
Example: (a command file that will not alter Ferret modes)
yes? SET MODE IGNORE_ERRORS ! 1st line of command file
.
. ... code which may encounter errors
.
yes? SET MODE/LAST IGNORE_ERRORS ! last line of command file
Ref Sec29.7.1.
SET MODE ASCII_FONT
The SET MODE ASCII_FONT command causes program Ferret to precede plot labels
with the PPLUS font descriptor "@AS" (ASCII SIMPLEX font). This assures
that special characters (e.g., underscores) are faithfully reproduced.
For special plots it may be desirable to use other fonts (e.g., to obtain
subscripts). CANCEL MODE ASCII_FONT is for these cases.
default state: set
Ref Sec29.7.2.
SET MODE CALENDAR
SET MODE CALENDAR causes program Ferret to output times in date/time format
(instead of time axis time step values). This affects both plotted and
listed output.
This mode accepts an optional argument specifying the degree of precision
for the output date. If the argument is omitted the precision is unchanged
from its last value.
default state: set (argument: minutes)
Arguments
SET MODE CALENDAR accepts the following arguments:
Argument
Equivalent precision
SECONDS
-6
MINUTES
-5 (default)
HOURS
-4
DAYS
-3
MONTHS
-2
YEARS
-1
The argument is uniquely identified by the first two characters.
Example:
yes? SET MODE CALENDAR:DAYS
Causes times to be displayed in the format dd-mmm-yyyy.
When CALENDAR mode is canceled the "equivalent" in the table above determines
the precision of the time steps displayed exactly as in SET MODE LONGITUDE.
Ref Sec29.7.3.
SET MODE DEPTH_LABEL
SET MODE DEPTH_LABEL causes Ferret to label Z coordinate information in
the units of the Z axis. This affects both plotted and listed output. This
mode accepts an optional argument specifying the degree of precision for
the output. If the argument is omitted the precision is unchanged from
its last value.
yes? SET MODE DEPTH:argument
default state: set (argument: -4)
Arguments
See SET MODE LONG (p. 306) for a detailed description of precision control.
Ref Sec29.7.4.
SET MODE DESPERATE
Ferret checks the size of the component data required for a calculation
in advance of performing the calculation. If the size of the component
data exceeds the value of the MODE DESPERATE argument Ferret attempts to
perform the calculation in pieces.
For example, the calculation "LIST/I=1/J=1 U[K=1:100,L=1:1000@AVE]" requires
100*1000=100,000 points of component data although the result is only a
line of 100 points on the K axis. If 100,000 exceeds the current value
of the MODE DESPERATE argument Ferret splits this calculation into smaller
sized chunks along the K axis, say, K=1:50 in the first chunk and K=51:100
in the second.
Ferret is also sensitive to the performance penalties associated with reading
data from the disk. Splitting the calculation along axis of the stored
data records can require the data to be read many times in order to complete
the calculation. Ferret attempts to split calculations along efficient
axes, and will split along the axis of stored data only in desperation,
if MODE DESPERATE is SET.
Example:
yes? SET MODE DESPERATE:5000
default state: canceled (default argument: 80000)
Note: Use MODE DIAGNOSTIC to see when splitting is occurring.
Arguments
Use SHOW MEMORY/FREE to see the total memory available (as set with SET
MEMORY/SIZE).
Whenever the size of memory is set using SET MEMORY the MODE DESPERATE
argument is reset at one tenth of memory size. For most purposes this will
be an appropriate value. The user may at his discretion raise or lower
the MODE DESPERATE value based on the nature of a calculation. A complex
calculation, with many intermediate variables, may require a smaller value
of MODE DESPERATE to avoid an "insufficient memory" error. A simple calculation,
such as the averaging operation described above, will typically run faster
with a larger MODE DESPERATE value. The upper bound for the argument is
the size of memory. The lower bound is "memory block size."
Ref Sec29.7.5.
SET MODE DIAGNOSTIC
SET MODE DIAGNOSTIC causes Ferret to display diagnostic information in
real time about its internal functioning. It is intended to help Ferret
developers diagnose performance problems by displaying what the Ferret
memory management subsystem is doing. The message "strip gathering on xxx
axis" indicates that Ferret has broken up a calculation into smaller pieces.
Subsequent "strip" and "gathering" messages indicate that sub-regions of
the calculations are being processed and brought together.
default state: canceled
Ref Sec29.7.6.
SET MODE IGNORE_ERROR
SET MODE IGNORE_ERROR causes Ferret to continue execution of a command
file despite errors encountered. (See command GO, p. 268.)
default state: canceled
Ref Sec29.7.7.
SET MODE INTERPOLATE
Note: The transformation @ITP provides the same functionality as MODE INTERPOLATE
with a greater level of control.
SET MODE INTERPOLATE affects the interpretation of world coordinate specifiers
(/X, /Y, /Z, and /T) in cases where the position is normal to the plane
in which the data is being examined. When this mode is SET and a world
coordinate is specified which does not lie exactly on a grid point, Ferret
automatically interpolates from the surrounding grid point values. When
this mode is canceled, the same world coordinate specification is shifted
to the grid point of the grid box that contained it before computations
were made (see examples).
default state: canceled
Example:
If the grid underlying the variable temp has points defined at Z=5 and
at Z=15 (with the grid box boundary at Z=10) and data is requested at Z=12
then
yes? SET MODE INTERPOLATE
yes? LIST/T=18249/X=130W:125W/Y=0:3N/Z=12 temp
lists temperature data in the X-Y plane obtained by interpolating between
the Z=5 and Z=15 planes. Whereas,
yes? CANCEL MODE INTERPOLATE
yes? LIST/T=18249/X=130W:125W/Y=0:3N/Z=12 temp
lists the data at Z=15. The output documentation always reflects the true
location used.
Ref Sec29.7.8.
SET MODE JOURNAL
SET MODE JOURNAL causes Ferret to record all commands issued in a journal
file. Output echoed to this file may be turned on and off via mode JOURNAL
at any time.
default state: set
Example:
yes? SET MODE JOURNAL:my_journal_file.jnl
The optional argument to MODE JOURNAL specifies the name of the output
journal file—with no argument, the default name "ferret.jnl" is used. Journal
files for successive Ferret sessions are handled by version number. See
the chapter "Computing Environment", section "Output file naming" (p. 193).
Ref Sec29.7.9.
SET MODE LATIT_LABEL
SET MODE LATIT_LABEL causes Ferret to output latitude coordinate information
in degrees N/S format (instead of the internal latitude coordinate). This
affects both plotted and listed output.
This mode accepts an optional argument specifying the degree of precision
for the output. If the argument is omitted the precision is unchanged from
its last value.
Example:
yes? SET MODE LAT:2
default state: set (argument: 1)
Arguments
See command SET MODE LONG (p. 306) for a detailed description of precision
control.
Ref Sec29.7.10.
SET MODE LONG_LABEL
SET MODE LONG_LABEL causes Ferret to output longitude coordinate information
in degrees E/W format (instead of the internal longitude coordinate). This
will affect both plotted and listed output.
This mode accepts an optional argument specifying the degree of precision
for the output. If the argument is omitted the precision will be unchanged
from its last value.
Example:
yes? SET MODE LONG:2
default state: set (argument: 1)
Arguments
The argument of SET MODE LONG is an integer specifying the precision. If
the argument is positive or zero it specifies the maximum number of decimal
places to display. If the argument is negative it specifies the maximum
number of significant digits to display.
Examples:
Suppose the longitude to be displayed is 165.23W. Then
yes? SET MODE LONG:1 will produce 165.2W
yes? SET MODE LONG:-3 will produce 165W
When LONG mode is canceled the argument still determines the output precision.
Ref Sec29.7.11.
SET MODE METAFILE
SET MODE METAFILE causes Ferret to capture all graphics in metafiles. These
metafiles can later be routed to various devices to obtain hard copy output.
The optional argument to MODE METAFILE specifies the name of the output
metafile—with no argument, the default name "metafile.plt" is used. Multiple
output files (i.e., successive plots) are handled by version number. See
the chapter "Computing Environment", section "Output file naming" (p. 193).
See the chapter "Computing Environment", section "Hard copy" (p. 190) for
details on generating hard copy.
Example:
yes? SET MODE METAFILE:june_sst.plt
default state: canceled (default argument when set: "metafile.plt")
Ref Sec29.7.12.
SET MODE POLISH
The SET MODE POLISH command causes program Ferret to expect algebraic expressions
to be entered in Reverse Polish order.
This mode exists only to assist with compatibility with earlier versions
of Ferret. It has no efficiency advantages.
default state: canceled
Ref Sec29.7.13.
SET MODE PPLLIST
Directs listed output from PPLUS commands (e.g., PPL LIST LABS) to the
specified file. This mode is useful for creating scripts that customize
plots. The user can specify the name of the output file by giving it as
an argument, otherwise file name "ppllist.out" is assigned.
Example:
yes? SET MODE PPLLIST:plot_symbols.txt
yes? PPL LISTSYM
yes? SPAWN grep "WIDTH" plot_symbols.txt
default state: canceled
Ref Sec29.7.14.
SET MODE REFRESH
The SET MODE REFRESH command causes Ferret to update windows following
"occlusion" events on X-servers that lack a backing store (SGI workstations
have been a case in point).
default state: canceled (except on SGI systems)
Ref Sec29.7.15.
SET MODE SEGMENTS
SET MODE SEGMENTS causes Ferret to utilize GKS segments ("GKS" is the Graphical
Kernel System—an international graphics standard). On some systems MODE
SEGMENTS may be necessary to update windows following "occlusion" events
or to resize window with the mouse.
Segments, however, make heavy demands on the system's virtual memory. If
Ferret crashes during graphics output due to insufficient virtual memory
try CANCEL MODE SEGMENTS.
default state: set
Ref Sec29.7.16.
SET MODE STUPID
Note: MODE STUPID is included for diagnostic purposes only.
SET MODE STUPID controls the ability of Ferret to reuse results left in
memory from previous commands. It also effects its ability to reuse intermediate
variables that are referenced multiple times during complex calculations.
Given with no argument
yes? SET MODE STUPID
causes Ferret to forget data cached in memory. The result is that all requests
for variables are read from disk and no intermediate calculations are reused.
The program will be significantly slower as a result.
A lesser degree of cache limitation occurs with the command
yes? SET MODE STUPID: weak_cache
which causes Ferret to revert to the cache access strategy that it used
previous to Ferret version 5.0. In this mode cache hits are unreliable
unless the region of interest is fully specified. (Unspecified limits will
typically default to the full range of the relevant axis.)
default state: canceled
Ref Sec29.7.17.
SET MODE VERIFY
SET MODE VERIFY causes commands from a command file ("GO file") to be displayed
on the screen as they are executed. Note that if MODE VERIFY is canceled,
loop counting in the REPEAT command is turned off.
default state: SET, argument "default"
Note: Many GO files begin with CANCEL MODE VERIFY to inhibit output and
end with SET MODE/LAST VERIFY to restore the previous state. Only if an error
or interrupt occurs during the execution of such a command file will the
state of MODE VERIFY be affected.
SET MODE VERIFY can accept arguments to further refine control over command
echoing.
yes? SET MODE VERIFY: DEFAULT
yes? SET MODE VERIFY: ALL
yes? SET MODE VERIFY: ALWAYS
SET MODE WAIT causes Ferret to wait for a keyboard keystroke from the user
after each plotted output is completed. This is useful on graphics terminals
that do not have a separate graphics plane; on these terminals SET MODE
WAIT prevents the graphical output from being wiped off the screen until
the user is ready to proceed.
default state: canceled
/COMPRESS /FILE /LASER /START
Designates a file (specified or default) for storing graphical images as
movie frames (in HDF Raster-8 format). Note that the FRAME/FILE=filename
qualifier is generally preferable to the SET MOVIE command, as it is simpler
and more flexible. See the chapter "Animations and GIF Images (p. 125) for
further explanation.
yes? SET MOVIE[/qualifiers]
Command qualifiers for SET MOVIE:
Turns on or off compression of HDF frames using run length compression.
yes? SET MOVIE/COMPRESS=OFF
The allowed arguments are "on" and "off" —CANCEL MOVIE does not affect
this qualifier.
default state: on
Specify an output file to receive movie frames.
!specify a new filename
or
!reactivate a previously specified filename after CANCEL MOVIE
The default movie filename extension is ".mgm"
The default movie filename is "ferret.mgm"
Output to Panasonic OMDR. Valid only on older VAX/VMS systems.
Only valid for use on older VAX/VMS systems with the Panasonic Optical
Memory Disk Recorder (OMDR). Only valid with /LASER qualifier.
/I/J/K/L /X/Y/Z/T /DI/DJ/DK/DL /DX/DY/DZ/DT
Specifies the default space-time region for the evaluation of expressions.
yes? SET REGION[/qualifiers] [ reg_name]
See the chapter "Grids and Regions", section "Regions" (p. 118) for further
information.
Examples:
1) yes? SET REGION/X=140E
2) yes? SET REGION/@N !N specifies X and Y but not Z or T
3) yes? SET REGION N
4) yes? SET REGION/@N/Z=50:250
5) yes? SET REGION/DZ=-5
6) yes? SET REGION/DJ=-10:10
Command qualifiers for SET REGION:
SET REGION/I=/J=/K=/L=/X=/Y=/Z=/T=
SET REGION/DI=/DJ=/DK=/DL=/DX=/DY=/DZ=/DT=
/BAD /GRID /TITLE /UNIT /DATASET
Modifies attributes of a variable defined by DEFINE VARIABLE or SET DATA/EZ.
This command permits variables within a single EZ data set to be defined
on different grids and it allows the titles and units to be superseded
for the duration of a session, only, on NetCDF and GT data sets.
yes? SET VARIABLE/qualifiers variable_name
Parameters
The variable name can be a simple name or a name qualified by a data set.
Example:
yes? SET VAR/UNITS="CM" WIDTH[D=snoopy]
Command qualifiers for SET VARIABLE:
SET VARIABLE/BAD=
When the command SET VARIABLE/BAD= is be used to set one of the two missing
value flags of a file variable, the bad value which is specified will be
used in subsequent outputs and calculations involving this variable
Ferret is aware of up to two missing value flags for each variable in a
netCDF file. Under most circumstances, netCDF file variables use only a
single flag. With a command like
SET VARIABLE/BAD=-999 my_file_var
you can specify -999 as an additional missing value flag. It is this value
which will be present in all subsequent SAVEs to files and calculations.
Note that if the netCDF file contains two distinct flag values specified
by the netCDF attributes "missing_value" and "_FillValue", then this command
will migrate the value specified by missing_value to the position previously
occupied by _FillValue and replace the one specified by missing_value.
Thus a double usage of this command allows you to control both flags. You
can use the command "SHOW DATA/VARIABLES" to see both bad value flags.
SET VARIABLE/GRID=
Example:
yes? SET VARIABLE/GRID=my_grid width[D=snoopy]
This is the mechanism by which the shape of the data (1D along T axis,
2D in the XY plane, etc.) is specified. By default Ferret will use grid
EZ, a line of up to 20480 points oriented along the X axis. The qualifier
is not applicable to variables defined with DEFINE VARIABLE.
SET VARIABLE/TITLE=
yes? SET VARIABLE/TITLE="title string" var_name
SET VARIABLE/UNITS=
yes? SET VARIABLE/UNITS="units string" var_name
Sets the rectangular region within the output window where output will
be drawn.
yes? SET VIEWPORT view_name
Issuing the command SET VIEWPORT is best thought of as entering "viewport
mode." While in viewport mode all previously drawn viewports remain on
the screen until explicitly cleared with either SET WINDOW/CLEAR or CANCEL
VIEWPORT. If multiple plots are drawn in a single viewport without the
use of /OVERLAY the current plot will erase and replace the previous one;
the graphics in other viewports will be affected only if the viewports
overlap. If viewports overlap the most recently drawn graphics will always
lie on top, possibly obscuring what is underneath. By default, the state
of "viewport mode" is canceled.
Pre-defined viewports exist for dividing the window into four quadrants
and for dividing the window in half horizontally and vertically. See the
chapter "Customizing Plots", section "Pre-defined viewports" (p. 153) for
a list.
/ASPECT /CLEAR /LOCATION /NEW /SIZE
Creates, resizes, reshapes or moves graphics output windows.
yes? SET WINDOW[/qualifiers] [window_number]
Note: Multiple windows may be simultaneously viewable but only a single
window receives output at any time.
See commands SHOW WINDOWS (p. 328) and CANCEL WINDOW (p. 249) for additional
information.
Examples:
1) yes? SET WINDOW/NEW
2) yes? SET WINDOW 3
3) yes? SET WINDOW/SIZE=.5
4) yes? SET WINDOW/ASPECT=.5
5) yes? SET WINDOW/LOCATION=0,.5
Command qualifiers for SET WINDOW:
SET WINDOW/ASPECT
Examples:
1) yes? SET WINDOW/ASPECT=y_over_x n
2) yes? SET WINDOW/ASPECT=y_over_x
3) yes? SET WINDOW/ASPECT=y_over_x:AXIS
The total size (area) of the output window is not changed.
The default value for the overall window ratio is y/x = 8.8/10.2 ~ 0.86.
The default value for the axis length ratio is y/x = 6/8 = 0.75.
Use PPLUS/RESET or SET WINDOW/ASPECT=.75:AXIS to restore defaults.
The aspect ratio specified is a default for future SET WINDOW commands
The origin (lower left) is restored to its default values: 1.2, 1.4
When using "SET WINDOW n" to return to a previous window that differs from
the current window in aspect ratio, it is necessary to re-specify its aspect
ratio with /ASPECT, otherwise PPLUS will not be properly reset.
SET WINDOW/CLEAR
SET WINDOW/LOCATION
yes? SET WINDOW/LOCATION=x,y [window_number]
SET WINDOW/NEW
yes? SET WINDOW/NEW
SET WINDOW/SIZE
yes? SET WINDOW/SIZE=r [window_number]
/I/J/K/L /X/Y/Z/T /D /FRAME /KEY /LEVELS /LINE /NOAXIS /NOKEY /NOLABELS
/OVERLAY /PALETTE /PATTERN /SET_UP /TITLE /TRANSPOSE /HLIMITS/ /VLIMITS
/XLIMITS /YLIMITS
Produces a shaded (rectangular raster) plot of a 2-D field. By default
a color key is drawn and contour lines are not drawn.
SHADE[/qualifiers] expression
Parameters
The expression may be any valid expression. See the chapter "Variables
and Expressions", section "Expressions" (p. 53) for a definition of valid
expressions. The expression will be inferred from the current context if
omitted from the command line. Multiple expressions are not permitted in
a single SHADE command.
Command qualifiers for SHADE:
SHADE/I=/J=/K=/L=/X=/Y=/Z=/T=
SHADE/D=
SHADE/FRAME
SHADE/KEY
SHADE/LEVELS
See the chapter "Customizing Plots", section "Contouring" (p. 156) for examples
and more documentation on /LEVELS and color_thickness indices, and also
the demonstration "custom_contour_demo.jnl".
SHADE/LINE
SHADE/NOKEY
SHADE/NOAXIS
SHADE/NOLABELS
SHADE/OVERLAY
Note (SHADE/OVERLAY with time axes):
SHADE/PALLETTE=
Yes? SHADE/PALETTE=land_sea rose
The /PALETTE qualifier changes the current palette for the duration of
the plotting command and then restores the previous palette. This behavior
is not immediately compatible with the /SET_UP qualifier. See the PALETTE
(p. 278) command for further discussion.
SHADE/PATTERN=
SHADE/SET_UP
SHADE/TITLE=
yes? SHADE/TITLE="title string" expression
SHADE/TRANSPOSE
Note that plots in the YT and ZT planes have /TRANSFORM applied by default
in order to achieve a horizontal T axis. See /XLIMITS (below) for further
details. Use /TRANSPOSE manually to reverse this effect.
SHADE/HLIMITS=
yes? SHADE/HLIMITS=lo:hi:increment
The optional "increment" parameter determines tic mark spacing on the axis.
If the increment is negative, the axis will be reversed.
SHADE/VLIMITS=
SHADE/XLIMITS=
Specifies the X axis range and tic interval (otherwise, Ferret selects
reasonable values).
yes? SHADE/XLIMITS=lo:hi:increment
The optional "increment" parameter determines tic mark spacing on the axis.
If the increment is negative, the axis will be reversed.
Note that the "X" in /XLIMITS refers to the horizontal axis of the plot
rather than to the X axis of the grid. This can lead to confusion, especially
on plots in the YT or ZT plane. Plots in these planes are automatically
transposed to place the Y or Z axis, respectively, on the vertical axis
of the plot. Plots may also be transposed manually with the /TRANSPOSE
qualifier. On transposed plots /XLIMITS will refer to the vertical axis
of the plot.
SHADE/YLIMITS=
/ALL
Displays program states and stored values.
Command qualifiers for SHOW:
SHOW/ALL
yes? SHOW/ALL
Arguments:
The names of variables, data sets, or other definitions can be specified
using wildcards. The * wildcard matches any number of characters in the
name; the question wildcard matches exactly one character.
Lists all command aliases and the full command names for which they stand,
or, with an argument, shows a specified command alias.
yes? SHOW ALIAS [alias_name]
Shows a basic description of the named axis.
SHOW AXIS[/qualifiers] axis_name
A typical output appears below. The columns are:
name
name of axis (used also in DEFINE AXIS and DEFINE GRID)
axis
the orientation of the axis; "(-)" on a depth axis indicates increasing
downward
# pts
number of points on axis; "r" or "i" for regular or irregular spacing,
"m" if the axis is "modulo" (repeating)
start
position of first point on the axis
end
position of last point on the axis
yes? SHOW AXIS PSXT
name axis # pts start end
Command qualifiers for SHOW AXIS:
SHOW AXIS/I=/J=/K=/L=/X=/Y=/Z=/T=
yes? SHOW AXIS/X[=lo:hi:delta] axis-name
Example:
yes? SHOW AXIS/L=1:12:3 my_custom_time_axis
SHOW/ALL
yes? SHOW AXIS/ALL
Displays commands, subcommands, and qualifiers recognized by program Ferret.
This command does not display aliases; use SHOW ALIAS.
SHOW COMMAND [command_name or partial_command]
Note: This is the most reliable way to view command qualifiers. The output
of this command will be current even when this manual is out of date.
Examples:
yes? SHOW COMMAND S ! show all commands beginning with "S"
yes? SHOW COMMAND ! show all commands
yes? SHOW COMMAND PLOT ! shows command PLOT and all its qualifiers
/ALL /BRIEF /FILES /FULL /VARIABLE
Shows information about the data sets which have been SET and indicates
the current default data set. By default the variables and their subscript
ranges are also listed.
yes? SHOW DATA[/qualifiers] [set_name_or_number1,set2,...]
If no data set name or number is specified then all SET data sets are shown.
Command qualifiers for SHOW DATA_SET:
SHOW DATA/ALL
SHOW DATA/BRIEF
SHOW DATA/FILES
SHOW DATA/FULL
SHOW DATA/VARIABLES
Example: SHOW DATA
SHOW DATA produces a listing similar to the one below. The output begins
with the descriptor file name (for TMAP-formatted data) and data set title.
The columns I, J, K, and L give the subscript limits for each variable
with respect to its defining grid (use SHOW DATA/FULL and SHOW GRID variable_name
for more information).
yes? SET DATA levitus_climatology
yes? SHOW DATA
currently SET data sets:
1> /home/e1/tmap/fer_dsets/descr/levitus_climatology.des (default)
name title I J K L
TEMP TEMPERATURE 1:360 1:180 1:20 1:1
SALT SALINITY 1:360 1:180 1:20 1:1
Shows the current expression(s) implied or set with SET EXPRESSION. If
not explicitly set with this command, the default current context expression
is the argument of the most recent "action" command (PLOT, SHADE, CONTOUR,
VECTOR, WIRE, etc.) See the chapter "Variables and Expressions", section
"Expressions" (p. 53) for an explanation and list of action commands.
yes? SHOW EXPRESSION
/ALL /BRIEF /EXTERNAL /INTERNAL /DETAILS
Shows a complete list of the functions defined in Ferret including descriptions
of the function arguments.
yes? SHOW FUNCTION[/qualifiers] [function_name]
If no qualifier or function name is given then all functions are listed.
SHOW FUNCTION will accept name templates such as
yes? SHOW FUNCTION *day*
Parameters
The parameter(s) may be the name of a function, with * replacing part of
the string as above.
Command qualifiers for SHOW FUNCTION:
SHOW FUNCTION/ALL
SHOW FUNCTION/BRIEF
SHOSHOW FUNCTION/EXTERNAL
SHOW FUNCTION/INTERNAL
SHOW FUNCTION/DETAILS
Example:.SHOW FUNCTION/DETAILS
yes? SHOW FUNCTION/DETAILS SAMPLEXY
/I/J/K/L /X/Y/Z/T /ALL /DYNAMIC
Shows the name and axis limits of a grid.
yes? SHOW GRID[/qualifiers] [var_or_grid1 var_or_grid2 ...]
Example:
(See command SHOW AXIS, p. 319, for an explanation of the columns.)
yes? SET DATA levitus_climatology
yes? SHOW GRID salt
GRID GLEVITR1
name axis # pts start end
XAXLEVITR LONGITUDE 360mr 20.5E 19.5E(379.5)
YAXLEVITR LATITUDE 180 r 89.5S 89.5N
ZAXLEVITR DEPTH(-) 20 i 0m 5000m
Parameters
The parameter(s) may be the name of one or more grid(s) or variable(s).
If no parameter is given SHOW GRID displays the grid of the last variable
accessed. This is the only mechanism to display the grid of an algebraic
expression.
Note: To apply SHOW GRID to an algebraic expression it is necessary for
Ferret to have evaluated the expression in a previous command. The command
LOAD is useful for this purpose in some circumstances.
Command qualifiers for SHOW GRID:
SHOW GRID/I=/J=/K=/L=/X=/Y=/Z=/T=
yes? SHOW GRID/X[=lo:hi:delta] [variable_or_grid]
Example:
yes? SHOW GRID/L=1:12:3 sst[coads_climatology]
SHOW GRID/ALL
yes? SHOW GRID/ALL
SHOW GRID/DYNAMIC
yes? SHOW GRID/DYNAMIC
Shows the current states of the LIST command.
yes? SHOW LIST
The qualifier /ALL may be used with this command but exists merely for
compatibility reasons and has no effect.
/ALL/FREE/PERMANENT/TEMPORARY
Shows the state of the memory cache.
yes? SHOW MEMORY
Shows the current size of the cache.
yes? SHOW MEMORY[/qualifiers]
Command qualifiers for SHOW MEMORY:
SHOW MEMORY/ALL
SHOW MEMORY/FREE
Cache memory is organized into "blocks." One block is the smallest unit
that any variable stored in memory may allocate. The total number of variables
that may be stored in memory cannot exceed the size of the memory table.
The "largest free region" gives an indication of memory fragmentation.
A typical SHOW MEMORY/FREE output looks as below:
total memory table slots: 150
total memory blocks: 500
memory block size:1600
number of free memory blocks: 439
largest free region: 439
number of free regions: 1
free memory table slots: 149
SHOW MEMORY/PERMANENT
SHOW MEMORY/TEMPORARY
Shows the names, states and arguments of the Ferret SET MODE command.
SHOW MODE [partial_mode_name1,name2,...]
Example:
yes? SHOW MODE VERIFY,META
The qualifier /ALL may be used with this command but exists merely for
compatibility reasons and has no effect.
Shows the current state of SET MOVIE. This state affects FRAME and graphics
commands specified with the /FRAME qualifier.
yes? SHOW MOVIE
The qualifier /ALL can be used with this command, but it exists for compatibility
purposes only and has no effect.
Queries are a vehicle for communication between Ferret and a stand-alone
interface program. They are not supported for general use.
Shows the current default region or the named region.
yes? SHOW REGION[/ALL] [region_name]
The region displayed is formatted appropriately for the axes of the last
data accessed. For example, suppose the region along the Y axis was specified
as Y=5S:5N. Then if the Y axis of the last data accessed is in units of
degrees-latitude the Y location is shown as Y=5S:5N but if the Y axis of
the last data accessed is "ABSTRACT" then the Y location is shown as Y=-5:5.
/ALL
Shows the value of one or more symbols (string variables).
yes? SHOW SYMBOL[/qualifier] [symbol_name]
If no qualifier or symbol name is given then all defined symbols are listed.
SHOW SYMBOL will accept partial names such as
yes? SHOW SYMBOL *lab*
Parameters
The parameter may be the name of a symbol, with * replacing part of the
string as above.
Command qualifiers for SHOW SYMBOL:
SHOW SYMBOL/ALL
Lists all symbols that are defined.
Shows the available transformations, including regridding transformations.
yes? SHOW TRANSFORM
Note: This is the most reliable way to view transformations. The output
of this command will be current even when this manual is out of date.
The qualifier /ALL may be used with this command but exists merely for
compatibility reasons and has no effect.
/ALL /DATASET /DIAGNOSTIC /USER
Lists diagnostic or user-defined variables.
SHOW VARIABLES[/qualifier] [partial_name]
Examples:
yes? SHOW VARIABLES !all user-defined variables
yes? SHOW VAR/DIAG Q !all diagnostic vars beginning with Q
Command qualifiers for SHOW VARIABLES:
SHOW VARIABLES/ALL
SHOW VARIABLES/DATA_SET
SHOW VARIABLES/DIAGNOSTIC
SHOW VARIABLES/USER
Shows one or more of the currently defined viewports. Omitting an argument
gives information on all viewports.
yes? SHOW VIEWPORT [view_name1,view_name2,...]
The qualifier /ALL may be used with this command but exists merely for
compatibility reasons and has no effect.
Lists open window numbers and indicates which is the active one.
yes? SHOW WINDOWS
The qualifier /ALL may be used with this command but exists merely for
compatibility reasons and has no effect.
Executes a command line (Unix shell) command from within Ferret.
yes? SPAWN unix_shell_command
Example:
yes? SPAWN rm -f file.dat
Also, "SPAWN shell_name" allows the user to fork into an interactive shell.
For example:
yes? SPAWN csh
enters the user into a c-shell. Use EXIT to return to Ferret.
/I/J/K/L X/Y/Z/T /D /BRIEF
Computes summary statistics about the data specified.
yes? STATISTICS[/qualifiers] expression_1 , expression_2 , ...
The statistics include:
All values are reported to 5 significant digits.
STATISTICS interacts with the current context exactly as the commands CONTOUR,
PLOT and LIST do.
Parameters
Expressions may be anything described under Expressions. If multiple variables
or expressions are specified they are treated in sequence. The expression(s)
are inferred from the current context if omitted from the command line.
Command qualifiers for STATISTICS:
STATISTICS/I=/J=/K=/L=/X=/Y=/Z=/T=
STATISTICS/D=
STATISTICS/BRIEF
Alias for CANCEL ALIAS.
The USE command is an alias for SET DATA/FORMAT=cdf. (p. 292)
All qualifiers and restrictions are identical to SET DATA/FORMAT=cdf. If
no filename extension is given, ".cdf" is assumed.
Example:
yes? USE test
is equivalent to
yes? SET DATA/FORMAT=cdf test
Executes a user-written extension to the Ferret program.
yes? USER[/COMMAND=] expression_1 , expression_2, ...
The USER command is a means of incorporating custom changes in Ferret.
It is currently supported only by special request to the Ferret developers
(ferret@pmel.noaa.gov). Two special features are currently accessible through
the USER command—objective analysis and scattered sampling of grids. These
commands are superceded with Version 5.0 by the functionality available
through the external functions.
We recommend the user access objective analysis via the script objective.jnl.
The scattered sampling feature is used in the polar plotting GO tools (try
"GO polar_demo" at the Ferret prompt).
Ref Sec36.1.
Objective analysis
(Note: see the version 4.4 documentation for an older way of gridding (X,Y,
value) triples onto a grid)
To grid a set of (X, Y, value) triples onto a grid of specified resolution,
sometimes called Objective analysis, use one of the family of "scat2grid"
external functions. See the description of these functions in Appendix
A starting at p. 68.
yes? SHOW FUNCTION/EXTERNAL scatter*
The X, Y, and F(X,Y) are lists of locations and a value associated with
each location. Define X and Y axes of the desired the grid and call the
function to interpolate these points to the grid. Say you have a set of
latitudes, longitudes, and samples of a quantity N03 at those points, and
that these are in the variables my_lat, my_lon, and n03.
yes? DEFINE AXIS/X=170W:120W:5 xax5
See also the example in the demo script,
yes? go objective_analysis_demo
Ref Sec36.2.
Scattered sampling
Note: there was an older way of doing scattered sampling; see section 33.2
in the version 4.4 documentation)
Ferret functions are available for sampling a gridded data field. See
yes? SHOW FUNCTION sample*
Examples of the use of some of these functions are in ef_sort_demo.jnl
/I/J/K/L /X/Y/Z/T /D /ASPECT /FRAME /LENGTH /NOAXIS /NOLABELS /OVERLAY
/PEN /SET_UP /TITLE /COLOR /TRANSPOSE /XLIMITS /XSKIP /YLIMITS /YSKIP
Produces a vector arrow plot.
VECTOR[/qualifiers] x_expr,y_expr
Parameters
x_expr, y_expr
Command qualifiers for VECTOR:
VECTOR/I=/J=/K=/L=/X=/Y=/Z=/T=
VECTOR/D=
VECTOR/ASPECT
yes? VECTOR/ASPECT[=aspect_ratio] x_expr, y_expr...
The size of vectors is unchanged—only the direction is modified. Under
most circumstances /ASPECT should be specified. The aspect ratio is (Y-scale/X-scale).
If the plot lies in the latitude/longitude plane the aspect ratio correction
will be adjusted as a function of COS(LATITUDE) on the plot.
For example, in a typical oceanographic XZ plane plot the vertical (Z)
axis is in tens of meters while the horizontal (X) axis is in hundreds
of kilometers. This means the vertical scale is greatly magnified in comparison
to the horizontal. The /ASPECT qualifier correspondingly magnifies the
vertical component of the vector relative to the horizontal while preserving
the length of the vector. The magnification factor is documented on the
plot.
If no aspect ratio is specified by the user (e.g. VECTOR/ASP with no value),
then Ferret will plot the vectors so that the two components' relative
sizes shows their ratio. (In an XZ plane, then, ocean velocity vectors
will nearly always appear horizontal) .
VECTOR/FRAME
VECTOR/LENGTH=
yes? VECTOR/LENGTH[=value_of_standard]
If the /LENGTH qualifier is omitted Ferret automatically selects reasonable
vector lengths. To reuse the vector length from the last VECTOR plot use
VECTOR/LENGTH.
To specify the vector lengths manually use the value_of_standard argument.
This associates the value "val" with the standard vector length, normally
½ inch. Note that the PPLUS command VECSET can be used to modify the length
of the standard vector. This is also the length that is displayed in the
vector key.
Example:
yes? VECTOR/LENGTH=100 U,V
Creates a vector arrow plot of velocities with ½ inch vectors for speeds
of 100.
VECTOR/NOAXIS
VECTOR/NOLABELS
VECTOR/OVERLAY
VECTOR/COLOR=
yes? VECTOR/PEN=green x_expr, y_expr
VECTOR/PEN=
yes? VECTOR/PEN=n x_expr, y_expr
VECTOR/SET_UP
VECTOR/TITLE=
yes? VECTOR/TITLE="title_string" x_expr, y_expr
VECTOR/TRANSPOSE
VECTOR/XLIMITS=
yes? VECTOR/XLIMITS=lo:hi:increment x_expr, y_expr
The optional "increment" parameter determines tic mark spacing on the axis.
If the increment is negative, the axis will be reversed.
VECTOR/XSKIP=/YSKIP=
yes? VECTOR/XSKIP=nx/YSKIP=ny u,v
By default, Ferret "thins" vectors to achieve a clear plot. These qualifiers
allow control over thinning.
Note that when the /SETUP qualifier is used the /XSKIP and /YSKIP qualifiers
are ignored. In this case, use arguments to the PPL VECTOR command to achieve
the thinning.
PPL VECTOR/qualifiers,xskip,yskip
VECTOR/YLIMITS=
The command (alias) WHERE requests mouse input from the user, using the
indicated click position to define the symbols XMOUSE and YMOUSE in units
of the plotted data. Comments that include the digitized position are also
written to the current journal file (if open). The WHERE command can be
embedded into scripts to allow interactive positioning of color keys, boxes,
lines, and other annotations.
/I/J/K/L /X/Y/Z/T /D /FRAME /NOLABEL /OVERLAY/SET_UP /TITLE /TRANSPOSE
/VIEWPOINT /ZLIMITS /ZSCALE
Produces a wire frame representation of a two-dimensional field.
yes? WIRE[/qualifiers] expression
Parameters
The expression may be anything described in the chapter "Variables and
Expressions", section "Expressions" (p. 53). The expression will be inferred
from the current context if omitted from the command line. Multiple expressions
are not permitted in a single WIRE command. The indicated region should
denote a plane (2D) of data.
Command qualifiers for WIRE:
WIRE/I=/J=/K=/L=/X=/Y=/Z=/T=
The following commands will create a wire frame representation of a simple
mathematical function in two dimensions.
yes? SET REGION/I=1:80/J=1:80
yes? WIRE/VIEWPOINT=-4,-10,2 exp(-1*(((I-40)/20)^2 + ((J-40)/20)^2))
WIRE/D=
WIRE/FRAME
WIRE/NOLABEL
WIRE/OVERLAY
WIRE/SET_UP
WIRE/TITLE=
WIRE/TRANSPOSE
WIRE/VIEWPOINT=
yes? WIRE/VIEWPOINT=x,y,z expression
The x,y values are specified as coordinates on the X and Y axes (though
they may exceed the axis limits). The z value is in units of the requested
variable.
WIRE/ZLIMITS=
yes? WIRE/ZLIMITS=zmin,zmax,delta expression
The values given are in units of the requested variable. (The string given
as an argument to /ZLIMITS= is passed unmodified to the PPLUS command WIRE
as the zmin and zmax parameters.)
WIRE/ZSCALE=
yes? WIRE/ZSCALE=s expression
The default value is equivalent to (ymax-ymin)/(zmax-zmin) (i.e., the
aspect ratio of the Z axis to the Y axis). This qualifier is identical
to the PPLUS VIEW command parameter of the same name.
yes? define axis/x=0:1:1/edges/units=feet
xtest ! 1 point, cell width=1 unit
yes? let vx = 0*X[gx=xtest]+1
! vx = 1
yes? list/prec=7 vx[x=@din]
0*X[GX=XTEST]+1
X (FEET): 0 to 1 (integrated)
0.3048000
yes? ! query
conversion factor to seconds
yes? define axis/t=0:1:1/edges/units=month
ttest ! 1 point, cell width=1 unit
*** NOTE: /UNIT=MONTHS is ambiguous
... using 1/12 of 365 days.
yes? let vt = 0*T[gt=ttest]+1
! vt = 1
yes? list/prec=7 vt[t=@din]
0*T[GT=TTEST]+1
T (MONTH): 0 to 1 (integrated)
2628000.
yes? DEFINE GRID/LIKE=temp/T=axday
gday
Define grid gday to be like the defining grid for temp but with a 4-year,
daily-interval time axis.
Define grid gnmc3d
like temp from data set ba022 but with the same time axis as sst from data
set nmc.
yes? DEFINE AXIS/Y=5S:5N:.2 ynew
yes?
DEFINE AXIS/T="15-FEB-1982":"15-FEB-1984":48 tnew
yes? DEFINE GRID/X=xnew/Y=ynew/T=tnew
gnew
Define grid gnew from new axes. The grid, gnew, will be normal (perpendicular)
to Z.
Stores the current default region under
the name "save". The region may be restored at a later time by the command
yes? SET REGION save.
Stores the current default X axis limits,
only, as region xonly.
Stores the current default X axis limits
minus 5 as region xonly.
Stores the given limits from the
Y axis and the default Z axis limits.
Stores the current default region
with the modification that L, the time step, is stored as 5.
Stores an L region beginning 1 time step
earlier and ending 1 time step later than the current default region as
region lp2.
or equivalently
yes? LET sum = a+b
Defines
velocity in m/sec from position, pos, in cm.
yes? list gap_3
I[I=1:5]
1
/ 1: 1.000
2 / 2: 2.000
3 / 3: ....
4 / 4: 4.000
5 / 5:
5.000
yes? let new_var = gap_3 + 5
yes? list new_var
GAP_3 +
5
1 / 1: 6.00
2 / 2: 7.00
3 / 3: ....
4 / 4: 9.00
5 /
5: 10.00
yes? list/form=(1PG15.3) new_var
GAP_3 + 5
X: 0.5 to 5.5
6.00
7.00
-1.000E+34
9.00
10.0
! Always reread the most recent
version from the file.
! We will call
our edited file "new_etopo.cdf"
yes? SET DATA etopo60
yes? LET/D=etopo60
depth = rose
yes? SET VARIABLE/TITLE="edited etopo depth"/UNITS=meters depth
yes?
SAVE/FILE=new_etopo.cdf depth
yes? USE new_etopo.cdf
! "rose[d=etopo60]"
is the original.
! "depth[d=new_etopo]" is the edited version.
! Redefine "depth[d=etopo60]" as a tool for for selective editing.
yes?
LET/D=etopo60 depth = rose[D=etopo60]-rose[D=etopo60] + correction
! An example edit: replace a small region with the value 500
yes? LET correction
= 500
yes? SAVE/APPEND/FILE=new_etopo.cdf depth[D=etopo60,X=180:175w,Y=0:2n]
yes?
PLOT/X=160e:160w/Y=1n rose[D=etopo60], depth[D=new_etopo]
is equivalent to
yes? SET DATA/EZ/VARIABLES="u,v"
velocities.dat
is equivalent to
yes? CONTOUR/FILL/PAL=land_sea
etopo60
writes message if the value of
I is greater than 5
executes yes_script
or no_script according to the value of the symbol yes_or_no
executes the script my_plot.jnl
only if the symbol dset contains "coads"
GO option_1
ELIF `i LT 6` THEN
GO option_2
ELSE
GO option_3
ENDIF
uses the multi-line IF syntax to select among GO scripts.
GO cscript
ELSE
GO lscript
ENDIF
IF condition THEN clause_1 ENDIF
IF condition
THEN clause_1 ELSE clause_2
IF condition THEN clause_1 ELSE clause_2 ENDIF
is equivalent to
yes? DEFINE VARIABLE A = B
or
yes? SET LIST/FORMAT (use format
set by SET LIST/FORMAT)
Simple syntax for plots using symbols. For
symbol (scatter) plots (PLOT/VS or PLOT/SYMBOL), control the color, size,
and line thickness of the symbols with commands such as:
yes? LET YTRIANGLE = YSEQUENCE({-1,1,-1})
yes?
LET XPTS = 180+30*RANDU(I[i=1:10])
yes? LET YPTS = 30*RANDU(1+I[i=1:10])
yes?
POLYGON XTRIANGLE+XPTS, YTRIANGLE+YPTS, I[I=1:10]
Note: XLIMITS and YLIMITS have been denigrated. Please
use HLIMITS and VLIMITS instead.
Specifies the Y axis range and tic interval. See /XLIMITS
(above).
or
or
Produces
a 240-frame movie of sea surface temperature.
Executes the command file compz.jnl at
Z=300, Z=270, ..., Z=0.
Repeats three commands—execution
of a GO script, CONTOUR, and FRAME—for each timestep specified.
To use the format "free" a file must consist
entirely of numerical data separated by commas, blanks or tabs.
If SET DATA/FORMAT=cdf (alias USE) is used, the data file must be
in CDF format. The default filename extension is ".cdf".
To use the format "unformatted" the data must be floating
point, binary, FORTRAN-style records with all of the desired data beginning
on 4-byte boundaries. This option expects 4 bytes of record length information
at the beginning and again at the end of each record. The "-" designator
( /VARIABLES) can be used to skip over unwanted 4-byte quantities (variables)
in each record. See the chapter "Data Set Basics", section "Binary data"
(p. 33).
FORTRAN format specifications should be surrounded
by parentheses and enclosed in quotation marks.
/FORMAT=stream is used to indicate that
a file contains either unstructured binary output (typical of C program
output) or fixed-length records suitable for direct access (all records
of equal length, no record length information embedded in the file). With
caution it is also possible to read FORTRAN variable-length record output.
This sort of file is typically created by "quick and dirty" FORTRAN code
which uses the simplest FORTRAN OPEN statement and outputs entire variables
with a single WRITE statement.
Sets the current expression to "temp".
Set the current expressions to "u
, v , u^2 + v^2"
Specifies a FORTRAN format (without row
or column headings).
Specifies binary output. (FORTRAN variable
record length record structure.)
Mode
Description
State
yes? SET MOVIE/FILE=filename
yes? SET
MOVIE/FILE
Sets X axis position in the default context.
Sets only X
and Y in the default context (since X and Y are defined in region N but
Z and T are not).
Sets ALL AXES in the default region to be exactly the
same as region N. Since Z and T are undefined in region N they will be
set undefined in the default context.
Sets X and Y in the default region to be exactly
the same as region N and then sets Z to the range 50 to 250.
Set the region along the Z axis to be 5 units less
than its current value.
Increases the current vertical axis range by
10 units on either end of the axis.
Sets region bounds for specified axis
subscript (I, J, K, or L) or axis coordinates (X, Y, Z, or T). See examples
above.
Modifies current region information
by the specified increment of an axis subscript (I, J, K, or L) or axis
coordinate (X, Y, Z, or T). See examples above. Syntax: /D*=val, or /D*=lo:hi.
Designates a value to be used as the missing data flag.
The qualifier is applicable to EZ data set variables and to NetCDF data
sets. The bad value which is specified will be used in subsequent outputs
and calculations involving this variable. It applies only for the duration
of the current Ferret session. It does not alter the data files. It is
not applicable to variables defined with DEFINE VARIABLE.
Sets the defining grid for a variable in an EZ data
set.
Associates a title with the variable. This title appears
on plotted outputs and listings. The qualifier is applicable to all variables.
Associates units with the variable. The units appear
on plotted outputs and listings. The qualifier is applicable to all variables.
Creates a new output window and sends subsequent graphics
to it.
Sends subsequent graphics to window 3.
Resizes current window to ½ of full.
Reshapes current window with Y/X equal to 1:2.
Puts the lower left corner of the current
window at the left border of the display and half way up it.
Sets the aspect ratio of the output window and hard copy.
Sets the overall aspect ratio of window
n.
Sets the overall aspect ratio of the current
window.
Sets the axis length aspect ratio
of the current window.
Clears the image(s) in the current or specified window.
Useful with viewports.
Sets the location for the lower left corner of named
(or current) window. The coordinates x and y must be values between 0 and
1 and refer to distances from the lower left corner of the display screen
(total length and width of which are each 1).
Causes future graphical output to be directed to a new window.
The window will be created at the next graphics output.
Resizes a window to r times the size of the standard window.
If the window number is omitted the command will resize the currently active
window. (The default window size is 0.7.)
Specifies value or range of axis subscripts
(I, J, K, or L), or axis coordinates (X, Y, Z, or T) to be used when evaluating
the expression being plotted.
Specifies the default data set to be used when evaluating the expression
being plotted.
Causes the graphic image produced by the command to be captured
as an animation frame in the file specified by SET MOVIE. In general the
FRAME command (p. 267) is more flexible and we recommend its use rather than
this qualifier.
Displays a color key for the palette used in the shaded plot.
By default a key is drawn unless the /LINE or /NOKEY qualifier is specified.
Specifies the SHADE levels or how the levels will be determined.
If the /LEVELS qualifier is omitted Ferret automatically selects reasonable
SHADE levels.
Overlays contour lines on a shaded plot. When /LINE is specified
the color key is omitted unless specifically requested via /KEY.
Suppresses the drawing of a color key for the palette used in
the plot.
Suppresses all axis lines, tics and labeling so that no box
appears surrounding the contour plot. This is especially useful for map
projection plots.
Suppresses all plot labels except axis labels.
Causes the indicated shaded plot to be overlaid on the existing
plot.
A restriction in PPLUS requires that
if time is an axis of the shaded plot, the overlaid variable must share
the same time axis encoding as the base plot variable. If this condition
is not met, you may find that the overlaid shaded plot fails to be drawn.
The solution is to use the Ferret regridding capability to regrid the base
plot variable and the overlaid plot variable onto the same time axis.
Specifies a color palette (otherwise, a default rainbow
palette is used). Try the Unix command % Fpalette '*' to see available
palettes. The file suffix *.spk is not necessary when specifying a palette.
See command PALETTE (p. 278) for more information.
Specifies a pattern file (otherwise, the current default
pattern specification is used). The file suffix *.pat is not necessary
when specifying a pattern. Try the Unix command % Fpattern '*' to see available
patterns. See command PATTERN (p. 279) for more information.
Performs all the internal preparations required by program
Ferret for a shaded plot but does not actually render output. The command
PPL can then be used to make changes to the plot prior to producing output
with the PPL SHADE command. This permits plot customizations that are not
possible with Ferret command qualifiers. See the chapter "Customizing Plots"
(p. 131).
Allows user to specify a plot title (enclosed in quotation
marks). Without this qualifier Ferret selects a title based on information
about the expression(s). To include font change and color_thickness specifications
(e.g., @TI@C002) in the title string, it is necessary either to CANCEL
MODE ASCII or to include a leading ESC (escape) character. See the chapter
"Customizing Plots", section "Fonts" (p. 151).
Causes the horizontal and vertical axes to be interchanged.
By default the X axis is drawn horizontally on the plot and the Y and Z
axes are drawn vertically. For Y-Z plots the Z data axis is vertical.
Specifies the horizontal axis range and tic interval (otherwise,
Ferret selects reasonable values).
Specifies the vertical axis range and tic interval. See /HLIMITS
(above)
Note: XLIMITS and YLIMITS have been denigrated. Please use
HLIMITS and VLIMITS instead.
Specifies the Y axis range and tic interval. See /XLIMITS
(above).
Executes all SHOW options. This command gives a complete description
of the current state, including information about region, grids, axes,
variables, and the state of various modes (default or set with SET MODE).
PSXT
LONGITUDE 160 r 130.5E 70.5W
Displays the coordinates and grid box
sizes for the specified axis. Optionally, low and high limits and a delta
value may be specified to restrict the range of values displayed.
Show a brief summary of all axes defined.
This qualifier has no effect on this command; it exists for
compatibility reasons.
Shows only the names of the data sets; does not describe
the data contained in them.
Displays the names of the data files for this data set and
the ranges of time steps contained in each. Output is formatted as date
strings or as time step values depending on the state of MODE CALENDAR.
Equivalent to /VARIABLES and /FILES used together.
In addition to the information given by the SHOW DATA
command with no qualifiers, this query also provides the grid name and
world coordinate limits for each variable in the data set.
DAYS1900 (day, month, year)
days elapsed
since Jan. 1, 1900
List all functions defined
List the functions and their arguments in brief form;
no function or argument descriptions.
List only the available Ferret external functions
(p. 195).
List only the internally defined Ferret functions.
Lists the axis inheritance for grid-changing functions
SAMPLEXY(DAT_TO_SAMPLE,XPTS,YPTS)
Returns data sampled at a set of (X,Y) points, using linear interpolation
Grid of result:
X: ABSTRACT (result will occupy indices
1...N)
Y: NORMAL (no axis)
Z: inherited from argument(s)
T: inherited from argument(s)
DAT_TO_SAMPLE: variable (x,y,z,t)
to sample
Influence on output grid:
X: no influence (indicate
argument limits with "[]")
Y: no influence (indicate argument
limits with "[]")
Z: passed to result grid
T: passed
to result grid
XPTS: X indices of sample points
Influence on
output grid:
X: no influence (indicate argument limits with "[]")
Y: no influence (indicate argument limits with "[]")
Z: no influence (indicate argument limits with "[]")
T: no influence
(indicate argument limits with "[]")
YPTS: Y indices of sample points
Influence on output grid:
X: no influence (indicate argument
limits with "[]")
Y: no influence (indicate argument limits with
"[]")
Z: no influence (indicate argument limits with "[]")
T: no influence (indicate argument limits with "[]")
Displays the coordinates and grid box
sizes for the specified axis. Optionally, low and high limits and a delta
value may be specified to restrict the range of values displayed.
Shows the names only of all grids defined.
Shows the names of dynamic grids that are defined.
Shows all variables currently cached in memory—permanent
and temporary.
Shows cache memory and memory table space that remains
unused.
Lists the variables cached in memory and cataloged
as permanent. These variables will not be deleted even when memory space
is needed. They become cataloged in memory as permanent when the LOAD/PERMANENT
command is used.
Lists the variables cached in memory and cataloged
as temporary (they may be deleted when memory capacity is needed).
MY_X_LABEL = "Sample Number"
LABEL_2 = "Station
at 23N"
Lists both diagnostic variables (available for the COX/PHILANDER
model) and user-defined variables.
Lists variables associated with the named dataset
by DEFINE VARIABLE/DATA_SET=
This is an unsupported (obsolete) qualifier. It
lists "diagnostic" variables available for the COX/PHILANDER model.
Lists expressions that have been defined by the user
as new variables. This is the default behavior of SHOW VARIABLES with no
qualifier.
Specifies value or range of axis subscripts
(I, J, K, or L), or axis coordinates (X, Y, Z, or T) to be used when computing
statistics about the expression(s).
Specifies the default data set to be used when computing statistics
about the expression(s).
Produces a shorter listing involving less computation.
SCAT2GRIDGAUSS_XY(X,Y,Z,XAX,YAX,CUTOFF)
Use Gaussian weighting to grid scattered data to an XY grid.
X:
X coordinates of scattered input triples
Y: Y coordinates of scattered
input triples
Z: Z = F(X,Y) Z component of scattered input triples
XAX: X axis of output grid
YAX: Y axis of output grid
CUTOFF:
Interpolation parameter: cutoff limit
SCAT2GRIDGAUSS_XZ(X,Z,F,XAX,ZAX,CUTOFF)
...
yes? DEFINE AXIS/Y=0:40N:5 yax5
yes?
LET n03_reg = scat2gridgauss_xy(my_lat, my_lon, n03, xax5, yax5, 2.)
yes?
SHADE n03_reg
SAMPLEI(DAT_TO_SAMPLE,I_INDICES)
SAMPLEJ(DAT_TO_SAMPLE,J_INDICES)
! These sample a gridded field, returning
SAMPLEK(DAT_TO_SAMPLE,K_INDICES)
! data at a set of grid points along an
SAMPLEL(DAT_TO_SAMPLE,L_INDICES)
! axis
SAMPLEIJ(DAT_TO_SAMPLE,XPTS,YPTS) ! Returns data sampled at a 2-dimensional
! subset of its grid points
SAMPLET_DATE(DAT_TO_SAMPLE,YR,MO,DAY,HR,MIN,SEC)
! Returns data sampled by
! interpolating
to one or more times
SAMPLEXY(DAT_TO_SAMPLE,XPTS,YPTS) ! Returns data sampled
at a set of (X,Y)
! points, i.e., a ship
track or some
! other path, using linear
interpolation
Algebraic expressions (or simple variables) specifying the
x components and y components of the vector arrows. The expression pair
will be inferred from the current context if omitted from the command line.
Specifies value or range of axis subscripts
(I, J, K, or L), or axis coordinates (X, Y, Z, or T) to be used when evaluating
the expression being plotted.
Specifies the default data set to be used when evaluating the
expression pair being plotted.
Adjusts the direction of the vectors to compensate for differing
axis scaling.
Causes the graphic image produced to be captured as an animation
frame in the file specified by SET MOVIE. In general the FRAME command
(p. 267) is more flexible and we recommend its use rather than this qualifier.
Controls the size of vectors.
Suppresses all axis lines, tics, and labeling so that no box
appears surrounding the contour plot. This is especially useful for map
projection plots.
Suppresses all plot labels except axis labels.
Causes the indicated vector field to be overlaid on the existing
plot.
Specifies the line color for the vectors. The available color
names are Black, Red, Green, Blue, LightBlue, Purple, and White (not case
sensitive), corresponding to the /PEN values 1-6, respectively. (/COLOR
also accepts numerical values.). Note that White is only available for
the default THICKNESS=1.
Specifies the line style for the vectors. /PEN= takes the same
arguments as the /LINE= qualifier for command PLOT. See command PLOT/LINE=
(p. 282). "n" ranges from 1 to 18.
Performs all the internal preparations required by program
Ferret for vector plots but does not actually render output. The command
PPL can then be used to make changes to the plot prior to producing output
with the PPL VECTOR command. This permits plot customizations that are
not possible with Ferret command qualifiers. See the chapter "Customizing
Plots" (p. 131).
Allows user to specify a plot title (enclosed in quotation
marks). Without this qualifier Ferret selects a title based on information
about x_expr and y_expr. To include font change and color_thickness specifications
(e.g., @TI@C002) in the title string, it is necessary either to CANCEL
MODE ASCII or to include a leading ESC (escape) character. See the chapter
"Customizing Plots", section "Fonts" (p. 151).
Causes the horizontal and vertical axes to be interchanged.
By default the X axis is always drawn horizontal and the Y and Z axes are
drawn vertical. For Y-Z plots the Z data axis is vertical.
Specifies X axis limits and tic interval. Without this qualifier,
Ferret selects reasonable values.
Draws every nth vector along the requested axis beginning
with the first vector requested.
Specifies Y axis limits and tic interval. See /XLIMITS=
(above).
Specifies value or range of axis subscripts
(I, J, K, or L), or axis coordinates (X, Y, Z, or T) to be used when evaluating
the expression being plotted.
Specifies the default data set to be used when evaluating the expression
being plotted.
Causes the graphic image produced to be captured as an animation
frame in the file specified by SET MOVIE. In general the FRAME command
(p. 267) is more flexible and we recommend its use rather than this qualifier.
Suppresses all plot labels except axis labels.
Causes the indicated wire frame plot to be overlaid on the
existing plot.
Performs all the internal preparations required by program Ferret
for wire frame graphics but does not actually render output. The command
PPL can then be used to make changes to the plot prior to producing output
with the PPL WIRE command. This permits plot customizations that are not
possible with Ferret command qualifiers. See the chapter "Customizing Plots"
(p. 131).
Allows user to specify a plot title (enclosed in quotation marks).
Without this qualifier Ferret selects a title based on information about
the expression. To include font change and color_thickness specifications
(e.g., @TI@C002) in the title string, it is necessary either to CANCEL
MODE ASCII or to include a leading ESC (escape) character. See the chapter
"Customizing Plots", section "Fonts" (p. 151).
Causes the X and Y axes to be interchanged.
Specifies a viewpoint for viewing the wire frame.
Specifies limits of Z axis for wire frame.
Controls Z axis scaling of the 3-D plot.
Last modified: September 27, 2000
