Personal tools
You are here: Home Documentation Users Guide 6. Customizing Plots 6.4 LABELS
Document Actions

6.4 LABELS

by rohan — last modified 2012-05-18 10:06

Ferret, by default, produces labeled axes, a plot title, documentation about the data set, the plot axes normal to the plot, nd 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

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

Ch6_fig06

For most plots there are labels that indicate axes normal to the plot, the dataset name, DODS URL, and so forth.  For control of these labels, after the plot is set up, the labels and their label numbers are defined.

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



Axis 6.4.4 labels and title

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.


6.4.5 Ferret label controls

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


6.4.6 PPLUS label commands

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

Example

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,\
"@CRFerret is an interactive computer visualization and analysis<NL>\
environment designed to meet the needs of oceanographers and<NL>\
meteorologists analyzing large and complex gridded data sets. It<NL>\
runs on most Unix systems, and on Windows NT/9x using X<NL>\
windows for display. It can be installed to run from a Web<NL>\
browser (WebFerret) for use while away from your desk or<NL>\
from a system lacking X windows software. It can transparently<NL>\
access extensive remote Internet data bases using OPeNDAP,<NL>\
formerly known as DODS."

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



Powered by Plone CMS, the Open Source Content Management System

This site conforms to the following standards: