Ferret, by default, produces labeled axes, a plot title, documentation about the data set, the plot axes normal to the plot, and a signature (current date and Ferret version number) when a plot is rendered. The /NOLABELS qualifier suppresses the plot title, the documentation and signature, and the axis labels of independent axes. Note that you can use the LABEL command to add any labels that you need.
6.4.1 Adding labels
Beginning with ferret v6.95 the Ferret command ANNOTATE offers another alternative for adding a label to a plot.
Examples may be found in the demo script. The ANNOTATE/NORM qualifier gives easy control over the location of labels relative to plot axes.
yes? go annotate_demo
DEFINE ANNOTATION takes the same qualifiers as ANNOTATE, and defines a moveable label. It can be issued in a PLOT/SET sequence, to define one or more labels that are put onto the plot when the corresponding PPL PLOT command is given.
The Ferret command LABEL adds a label to a plot and takes the following arguments:
yes? LABEL xpos,ypos,center,angle,size text
where xpos and ypos are in user (axis) units, size is in inches, angle is in degrees (0 at 3 o'clock) and center is -1, 0, or +1 for left, center, or right justification. There is an example in the section below on PPLUS label commands. The label position will adjust itself automatically when the plot aspect ratio or the viewport is changed.
If you prefer to locate labels using inches rather than using data units issue the command
yes? LABEL/NOUSER xpos,ypos,...
Note, however, that the layout of a plot in inches‚ lengths of axes, label positions, etc.‚ shifts with changes in window aspect ratio (SET WINDOW/ASPECT) and with the use of viewports. Labels specified using LABEL/NOUSER will need to be adjusted if the aspect ratio or viewport is changed.
Very long labels may be specified, up to 2048 characters long. This applies to all kinds of labels: titles, axis labels, and moveable labels. To create multiple-line labels, use the separator <NL> to locate the line-breaks. If centered labels are requested, each line is centered separately. See example 1 and example 2. Also try the demo script multi_line_demo.jnl for examples of this usage.
Notes:
1) If you use the command PPL LABS instead of LABEL, be aware that when defining a new movable label, all lower-numbered labels must already be defined.
2) The Ferret command LABEL is an alias for PPL %LABEL. PPLUS does NOT consider a label created with %LABEL to be a movable label. Consequently, no label number is assigned and the label cannot be manipulated as a movable label.
3) %LABEL is an unusual command in that the label appears on the plot immediately after the command is given, rather than being deferred. This has ramifications for the user who has multiple plot windows open and is in MODE METAFILE, since a metafile is not closed until a new plot is begun. If the user produces a plot in window B, and then returns to a previous window A and adds a label with LABEL, that label will appear on the screen correctly, but will be in the metafile corresponding to window B.
4) The LABWID function (Ferret version 5.81 and higher) returns the width in plot inches of a label in a
given font and size. This can be used to position other plot elements relative to a label.
LABEL/NOUSER `xpos`, `ypos`, -1, 0, 0.15, "my label"
LET wid = LABWID ("my label", 0.15)
IF `next_label GT 0` THEN\
LABEL/NOUSER `xpos+wid+0.15`, `ypos`, -1, 0, 0.15, "second label"Example
yes? PLOT/I=1:100 sin(i/6) yes? LABEL 50, 1.2, 0, 0, .2 @P2MY SIN PLOT
6.4.2 Listing labels
The PPLUS command PPL LIST LABELS can be used to list the currently defined labels. For example,
yes? PPL LIST LABELS @ACSEA SURFACE TEMPERATURE (Deg C) @ASLONGITUDE @ASLATITUDE XPOS YPOS HGT ROT UNITS LAB 1 8.000E+00 7.200E+00 0.060 0 SYSTEM @ASFERRET Ver. 4.40 LINE PT: 0.000E+00 0.000E+00 NO LINE CENTER JUSTIFY LABEL LAB 2 8.000E+00 7.100E+00 0.060 0 SYSTEM @ASNOAA/PMEL TMAP LINE PT: 0.000E+00 0.000E+00 NO LINE CENTER JUSTIFY LABEL LAB 3 8.000E+00 7.000E+00 0.060 0 SYSTEM @ASOct 22 1996 09:24 LINE PT: 0.000E+00 0.000E+00 NO LINE CENTER JUSTIFY LABEL LAB 4 0.000E+00 6.600E+00 0.120 0 SYSTEM @ASTIME : 16-JAN LINE PT: 0.000E+00 0.000E+00 NO LINE LEFT JUSTIFY LABEL . . .
The first three lines of output show the plot title, the X axis label, and the Y axis label. These labels are controlled by the PPL TITLE, PPL XLAB, and PPL YLAB commands, respectively. The three characters "@AS" indicate the font of the label—in this case "ASCII Simplex" (see the section in this chapter, "Fonts").
Next is a table of "movable labels"‚ labels that were defined using the PPL LABS command. Labels are generally simpler to control with the GO unlabel and LABEL commands described in the following sections, rather than with the PPL LABS command.
Each label is described with two lines. The column headers refer to the first of the two. The coordinates of each label, (XPOS,YPOS), may be in units of "inches" or may be in the units of the axes. This is reflected in the UNITS field of the output, which will contain "SYSTEM" if the coordinates are in inches or "USER" if the coordinates are axis units. (The /NOUSER qualifier on the PPL LABS command is used to indicate that coordinates are being given in inches.) Coordinates are calculated relative to the axis origins. The PPL HLABS and PPL RLABS commands control label height and rotations, respectively.
The second line of the label description contains information about an optional line on the plot which can be used to point to the label (refer to the PPLUS command LLABS or see the section in this chapter, "Positioning labels using the mouse pointer". At the end of this line is the text of the movable label.
In addition to PPLUS LIST LABELS, you can also issue a SHOW SYMBOLS command; the labels that are automatically generated are available as symbols,
yes? SHOW SYMBOLS ! lists all symbols that have been defined yes? SHOW SYMBOLS LAB* ! lists symbols starting with LAB
6.4.3 Removing movable labels
To remove all labels from a plot (except the numbers that label the tic marks on axes) use the /NOLABEL qualifier on the plotting command. This removes the "logo" in the upper right with the Ferret version, etc. and all of the labels on the plot itself
yes? PLOT/I=1:100/NOLABEl sin(i/6)
To remove just the logo, use "MODE LOGO". Cancel that mode, then that block of labels will not be drawn on subsequent plots.
To remove labels selectively, we need PPL comands. Removing a movable label is a two step process: identifying the label number and then deleting the label. PPLUS internally refers to all movable labels with label reference numbers. The PPLUS command LIST LABELS will list the PPLUS labels and the text strings they contain. Then the user can use "GO unlabel n", where n is the reference number, to delete a label.
Example
In this example we plot the same figure in two viewports, one plot with the default "signature," and one plot with the signature removed (Figure 6_6). The SHOW SYMBOLS command lists all the Ferret symbols that are defined for the plot; LAB1, LAB2, and LAB3 are always the three lines of the signature. For additional moveable labels that may be on a plot, after the plot is set up, the label numbers are stored in symbols LABNUM*; see below. (Alternatively, PPL LIST LABELS will list all currently defined labels, or PPL LISTSYM will list all symbols.)
!upper viewport has a "signature" yes? PPL BOX on yes? SET VIEW upper yes? PLOT/I=1:100 sin(i/6) yes? SHOW SYM ... LAB1 = "FERRET Ver. 5.70" LAB2 = "NOAA/PMEL TMAP" LAB3 = "Jan 5 2005 08:54:22 " ... !in the lower viewport !the signature is removed as follows yes? SET VIEW lower yes? GO unlabel 1 yes? GO unlabel 2 yes? GO unlabel 3 yes? PPL PLOT
For most plots there are labels that indicate axes normal to the plot, the dataset name, OPeNDAP url, and so forth. For control of these labels, after the plot is set up, the labels and their label numbers are defined.
For any plot, the movable labels are generated with the region information for axes orthogonal to the plot, and the dataset name and title. Symbols are defined for all of the movable labels that are defined. These are listed in the section "Special Symbols". GO unlabel works only for the movable labels, which are numbered.
use coads_climatology plot/x=175/y=15/title="SST at x=175,y=15"/SET sst go unlabel ($labnum_x) go unlabel ($labnum_y) ppl plot
Special commands and special logic govern the labels of axes and titles. Use the PLOT+ commands XLAB, YLAB, and TITLE in conjunction with the Ferret plotting qualifier /SET_UP to modify the labeling choices that Ferret makes. These are discussed in the section below, PPLUS label commands.
For two-dimensional plots (CONTOUR, FILL) Ferret will label the plot axes with the titles and units from the appropriate axes of the grid. The command SHOW GRID can be used to see the labels that will be used. The title will be the title of the variable (see SHOW VARIABLE , and SHOW DATA/VARIABLE.) modified by the units and comments about transformations in parentheses.
For one-dimensional plots (PLOT) other than PLOT/VS the independent axis will be labeled using the title and units from the appropriate axis of the grid. The dependent axis will be labeled with the units of the variable being plotted. The title will be labeled as for two-dimensional plots.
For output of the PLOT/VS command the axes will be labeled with the titles of the variables, each modified by its units and comments about transformations in parentheses.
In addition to LABEL (discussed above), Ferret controls include the /NOLABELS qualifier, which suppresses default plot title, documentation and signature, axis labels, and /TITLE qualifier to graphical output commands PLOT, SHADE, CONTOUR, VECTOR, and WIRE:
Ferret qualifiers
/NOLABELS
/TITLE=
and arguments to SET MODE and CANCEL MODE :
Ferret arguments
SET MODE ASCII_FONT
SET MODE CALENDAR
SET MODE LATIT_LABEL
SET MODE LONG_LABEL
Ferret stores the text strings of the following labels in PPLUS symbols. The symbol names are:
PPLUS commands can be used to customize labels. See the example below, and the section on PPLUS graphical commands for more on the syntax to make PPLUS calls. As stated above, PPLUS commands regarding movable labels are largely superceded by the Ferret command LABEL and "GO unlabel n". However the /SETUP qualifier on a plot command in conjuction with PPLUS commands LABSET, TITLE, XLAB, and YLAB are used to modify the labels that Ferret automatically puts on plots. See the section on PPLUS graphical commands for more on calling PPLUS plot commands.
|
|
|
| Command | Function |
|
LIST LABELS |
shows the currently defined labels (PPL LIST) |
|
LABSET |
sets character heights for labels (PPL LABSET ) |
|
TITLE* |
sets and clears main plot label (PPL TITLE ) |
|
XLAB* |
sets label of X axis (PPL XLAB ) |
|
YLAB* |
sets label of Y axis (PPL YLAB) |
|
LABS* |
makes, removes, or alters a movable label (PPL LABS; redundant with Ferret LABEL command) |
|
HLABS |
sets height of each movable labe (PPL HLABS)l |
|
RLABS |
sets angle for each movable label (PPL RLABS) |
|
LLABS |
sets start position for and draws a line to a movable label (PPL LLABS) |
|
XFOR |
sets formatting of the coordinate labels along the x axis(PPL XFOR)
|
|
YFOR |
sets formatting of the coordinate labels along the y axis(PPL YFOR)
|
|
* issued by Ferret with every relevant plot |
|
This example customizes a plot using PPLUS label controls. The LABSET command is used here to control the size of the main label, x-label, and y-label. The Ferret LABEL command is used to add a label.
yes? PLOT/I=1:100/SET_UP i * sin(i/6) yes? PPL LABSET 0.3, 0.08, 0.3 yes? PPL TITLE yes? PPL YLAB "Modiified SIN function" yes? PPL PLOT yes? LABEL 10.,20,-1,30,0.2 "Angled label"
Very long labels may be specified, up to 2048 characters long. To create multiple-line labels, use the separator <NL> to locate the line-breaks. If centered labels are requested, each line is centered separately. See the demo script multi_line_demo.jnl for examples of this usage.
Example
Use of long axis labels. Use the backslash continuation character for better readability.
yes? PLOT/I=1:100/TITLE=" "/SET i*cos(i/8) yes? PPL YLAB "A four-line y label.<nl>second line\ <nl>third line<nl>fourth line" yes? PPL XLAB "a two-line X label. <nl>COSINE function" yes? PPL PLOT
6.4.7 Positioning labels relative to other plot elements
Once a plot has been made, we can use the location and size of plot elements such as axis lengths to position any labels we would like to add. A number of global symbols are defined when a plot is drawn. See the section on "special symbols" for a compete list of these.
Use the LABEL command to position a label. To position a label using page inches, use LABEL/NOUSER which takes the units to be inches from the origin. When plotting in a viewport, plot inches are measured from the origin of the viewport.
Example
yes? plot/i=1:100 (i/2)*sin(i/6) ! Put a label in the lower right, use user units yes? label/user `($xaxis_max)`, `($yaxis_min)`, 1, 0, .2, "@P2lower right" !-> PPL %LABEL/user 100, -50, 1, 0, .2, "@P2lower right" ! Use plot inches. Put a label just inside the plot area yes? label/nouser `($ppl$xlen)/2`, `($ppl$ylen) - 0.4`, 0, 0, 0.2, "@P2center top" !-> PPL %LABEL/nouser 4, 5.6, 0, 0, 0.2, "@P2center top" ! Put a label in the lower left, making sure it's not off the page. yes? let xpl = -1*MIN(1,`($ppl$xorg)`) yes? let ypl = -1*MIN(1,`($ppl$yorg)`) yes? label/nouser `xpl`, `ypl`, -1, 0, 0.2, "@P2lower left" !-> PPL %LABEL/nouser -1, -1, -1, 0, 0.2, "@P2lower left"
Very long labels may be specified, up to 2048 characters long. To create multiple-line labels, use the separator <NL> to locate the line-breaks. If centered labels are requested, each line is centered separately. See the demo script multi_line_demo.jnl for examples of this usage.
Example
This is one LABEL command, used to put a block of text on the page. Use the backslash continuation character for better readability.
yes? LABEL 3,95,-1,0,0.14,\ "Ferret is an interactive computer visualization and analysis environment<NL>\ designed to meet the needs of oceanographers and meteorologists <NL>\analyzing large and complex gridded data sets. It runs on recent Unix <NL>\and Mac systems, using X windows for display. PyFerret, introduced in<NL>\ 2012, is a Python module wrapping Ferret. The pyferret module <NL>\provides Python functions so Python users can easily take advantage of <NL>\Ferret's abilities to retrieve, manipulate, visualize, and save data "
6.4.8 Positioning labels using the mouse pointer
Often it is awkward precisely to position plot labels. Using the mouse pointer can simplify this as mouse clicks can be used to place labels and other annotations on plots. This command option works only in Window 1. It does not function in other windows that have been opened with SET WINDOW/NEW.
The full syntax of the LABEL command is
LABEL xpos, ypos, justify, rotate, height "text"
xpos,ypos are the (x,y) position of the label
justify = -1, 0, 1 for left, center, right justification — default = left
rotate is given in degrees counter-clockwise — default = 0
height is in "inches"
text to be plotted. This argument may include font and color specifications
Note that the LABEL /NOUSER qualifier is not relevant for mouse input.
If either of the first two arguments (label position) are omitted it is a signal that mouse input is desired. For example:
yes? GO ptest yes? LABEL "this is a test"
will wait for mouse input, using the indicated point as the lower left corner of the text string. Equivalent to this is
yes? LABEL ,,-1,0,.12 "this is a test"
Note that left justification will always be used in this mode, regardless of the value specified.
For mouse control over justification and/or to draw a line or arrow associating a label with a feature on the plot, explicitly omit the justification argument. Ferret will put up a menu requesting a selection of "Arrow", "Line", "Right", "Center", "Left". If Arrow or Line is selected two mouse inputs are required — the first indicating the feature to be marked, the second indicating the lower left corner of the text area. If "Right", "Center" or "Left" is specified the text will be justified accordingly.
Note that the mouse-driven LABEL command defines the symbols XMOUSE and YMOUSE and writes comments regarding their definitions into the current journal file (if any) as described under the WHERE alias.
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 which 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.
6.4.9 Labeling details with arrows and text
Using the technique described in section 4.7 it is also simple to create a label with a line or arrow indicating a detail of a plot. Follow the procedure outlined above but select "Line" or "Fancy line" (arrow) from the menu that appears in the plot window. Then click on the detail which is to be labeled. The menu will appear again—this time select the justification and click on the label position.
To see the precise numerical coordinates of the arrow and label use the PPL ECHO ON command prior to the PPLUS command which redraws the plot. The endpoint coordinates of the arrow will appear as a comment line which begins with "C LLABS" in the echo file, fort.41. The coordinates of the label will appear as a comment line which begins with "C LABS". (Easily viewed with "spawn tail -2 fort.41".)