Chapter 6: CUSTOMIZING PLOTS 

Ch6 Sec1.  OVERVIEW 

Detailed control is possible over most aspects of Ferret graphical outputs. A custom modification will require the user to either add a qualifier to a Ferret command  or communicate directly with the graphical package PPLUS, which is contained inside of Ferret. The most commonly used PPLUS commands are listed in the following sections of this chapter. Consult the PLOT PLUS for Ferret manual for complete command lists and the specifics of command syntax. 

Ferret communicates with PPLUS by sending a sequence of commands to PPLUS  (the command PPL ECHO ON causes the sequence of commands that Ferret sends to PPLUS to be logged in the file fort.41.). The user can give further commands to PPLUS directly using the Ferret command PPL (e.g., yes? PPL AXLEN 10,7). Some results can be attained in two ways—with either Ferret or PPLUS commands. However, the interaction of the two is complex and the inexperienced user may get unexpected results, so when possible, use only Ferret commands.^note1 

PPLUS uses a deferred mode of output—various commands are given to PPLUS which describe the plot state but produce no immediate output; the entire plot is then rendered by a single command. Some plot states (e.g., axis labels) are set by Ferret with every plotted output; to customize these states it is necessary to use the /SET_UP qualifier (which sets up the plot inside of PPLUS) and then modify the state with direct PPL commands. Other plot states are never set by Ferret and, if modified at any time, remain in their specified state for all subsequent plots. Still other states are modified by Ferret only under special circumstances. Here is a very simple customization (Figure 6_1): 

yes? PLOT/X=1:100/TITLE="My SIN Plot"/SET_UP sin(x/6)   !use /SET_UP
yes? PPL YLAB "SIN value"
yes? PPL PLOT 

The examples throughout this chapter show how the /SET_UP qualifier on graphics commands can be used to delay rendering of a plot while the user modifies plot appearance with PPLUS commands. 

Below is a list of PPLUS commands which are reset by Ferret. Please see the the PPLUS Users Guide for details of PPLUS syntax. (p. 487) 

Ch6 Sec2.  GRAPHICAL OUTPUT 

Ch6 Sec2.1.  Ferret graphical output controls 

Ch6 Sec2.2.  PPLUS graphical output commands 

The plot commands, in the table below, can be  customized using /SET_UP to delay display. The PLOT/SET_UP is followed by PPLUS commands which customize the settings for axes, labels, plot layout, and so on. Then the plot will ultimately be rendered using a PPLUS graphical output command (not the Ferret counterpart). A customized contour or filled-contour plot is rendered with PPL CONTOUR, a wire frame plot with PPL VIEW and so on. Please see the overview of this chapter (p. 183) and also the discussion in the Commands Reference section about PPLUS (p. 387). 

In the following sections, there is a "PPLUS commands" subsection detailing which PPLUS commands are used for each type of customization. See the examples in those sections, and cross-references to the PPLUS command syntax in the PPLUS manual (Appendix B). 

The graphical output command PLOTUV can be used to make stick plots easily, as the following time series example shows. 

yes? SET DATA coads; SET REGION/X=180/Y=0/L=400:500
yes? PLOT/SET uwnd, vwnd
yes? PPL PLOTUV 

Ch6 Sec3.  AXES 

By default, Ferret displays X- and Y-axes with tics and numeric labels at reasonable intervals and a label for each axis. Time axes are also automatically formatted and used as needed. These axis features can be modified or suppressed using the following Ferret direct controls and PPLUS commands. 

Ch6 Sec3.1.  Ferret axis formatting 

The following qualifiers are used with graphical output commands PLOT, VECTOR, SHADE, and CONTOUR to specify axis limits, tic spacing, and possible axis reversal: 

    Ferret qualifers
    /HLIMITS,  /VLIMITS, /NOAXIS 

The /HLIMITS and /VLIMITS qualifiers use the syntax /HLIMITS=lo:hi:delta. Tic marks are placed every "delta" units, starting at "lo" and ending at "hi". Every other tic mark is labeled. "delta" may be negative, in which case the axis is reversed. 

The /NOAXIS qualifier removes both X and Y axes from the plot. This is particularly useful for plots using curvilinear coordinates (map projections) where the final axis values represent transformed axis values rather than world coordinates. 

The following arguments to SET MODE and CANCEL MODE determine axis style (e.g., SET MODE CALENDAR:days) : 

    Ferret arguments

    CALENDAR 

    LATIT_LABEL 

    LONG_LABEL 

See the next section for more about customizing axes, tic marks, labels and coordinate labels. 

See the Commands Reference section of this manual (p. 323) for more information. 

Ch6 Sec3.2.  PPLUS axis commands 

PPLUS commands can be used to customize axis settings. Note that Ferret makes settings for all of these automatically; you will only need to make PPLUS calls to change the axis properties. See the examples below, and the section on PPLUS graphical commands (p. 185) for more on the syntax to make PPLUS calls. 

Examples 

1) Plot with no axis labels (character or numeric) and no tics (Figure 6_2). (Equivalent to 

     yes? GO box_plot PLOT/I=1:10/NOLABEL 1/i) 

yes? PLOT/i=1:30/NOLABEL/SET 1/i
yes? PPL AXLABP 0,0                   !turn off numeric labels
yes? PPL TICS 0,0,0,0                 !suppress small and large tics
yes? PPL PLOT                         !render plot
yes? PPL TICS .125,.25,.125,.25       !reset tics to default
yes? PPL AXLABP -1,-1                 !reset numeric labels 

2)  customize x-axis label (Figure6_3); XLAB always reset by Ferret) 

yes? PLOT/SET/i=1:100 sin(x/6)
yes? PPL XLAB My Custom Axis Label
yes? PPL PLOT 

3) specify tic frequency for y axis 

yes? PLOT/i=1:30/YLIM=0:1:.2 1/i 

4) Specify the size and location of tic marks on the axes. The PPLUS tics command is 

ppl tics,smx,lgx,smy,lgy,IX,IY 

IX and IY are 1 for tics inside the plot box, 0 to straddle the axis line, and -1 for tics outside the axis with -1 as default. These commands put large tics inside the axes. 

yes? SHADE/SET/i=1:100/j=1:15 sin(x/6)*10./j
yes? PPL TICS .0,.35,.0,.35,1,1 

yes? PPL SHADE 

See also the /GRATICULE qualifer available on all plotting commands (PLOT/GRATICULE, CONTOUR/GRATICULE, etc.) 

The PPLUS commands XFOR and YFOR control the format of the labels for coordinates along the axes. These apply FORTRAN format syntax to override the automatic formatting. 

Starting with Ferret v6.0, the PPL XFOR (p. 554) and PPL YFOR commands may be used with longitude and latitude axes to specify that the coordinates that are labeled along the axis should be shown as degrees minutes (and optionally seconds) instead of the default labels of degrees and decimal fractions of degrees. 

    Example: 

yes? use coads_climatology 

yes? SET VIEW upper 

yes? SHADE  airt  ! Default axis formatting 

yes? SET VIEW lower 

yes? SHADE/SET airt   ! Showing XFOR (fortran format) and YFOR (dm) 

yes? PPL XFOR (F7.2) 

yes? PPL YFOR (dm) 

yes? PPL SHADE 

Ch6 Sec3.3.  Overlaying symbols on a time axis 

To overlay symbols or mark-up on a plot which has a formatted  time axis (dates and times) it is necessary to specify  positions using the internal time encoding of that axis. Typically, the easiest way to achieve this is to define a  variable, say TT, which is the time encoding. This example illustrates. 

Example: 

 demonstrate PLOT/VS and POLYGON over time axes (Figure 6_4) 

USE coads_climatology 

LET xsqr = {-1,1,1,-1}                 ! coordinates of a unit square
LET ysqr = {-1,-1,1,1}

LET xcircle = COS(6.3*i[i=1:42]/40)    ! coordinates of unit circle
LET ycircle = SIN(6.3*i[i=1:42]/40) ! Notice the units of the time axis
SHOW GRID/L=1:3 sst
 

PLOT/X=180/Y=0 sst     !  draw a  time series plot 

LET tt = T[GT=sst]         ! tt is the coordinates along the T axis 

! place an "X" at the value exactly at 7-aug
! "@ITP" causes interpolation to exact location 

LET t0   = tt[T="7-aug-0000"@itp]
LET val0 = sst[X=180,Y=0,T="7-aug-0000"@itp]
PLOT/VS/OVER/NOLAB/SYM=2/LINE=8 t0,val0 

! put a box around the "X"
POLYGON/OVER/LINE=8/TITLE="Special region" t0+500*xsqr, 0.05*ysqr+val0

! place an "X" on the data point nearest to 15-may
! Note that @ITP is absent, so behavior is set by MODE INTERPOLATE 

LET t1   = tt[t="15-may-0000"]
LET val1 = sst[x=180,y=0,t="15-may-0000"]
PLOT/VS/OVER/NOLAB/SYM=2/LINE=10 t1,val1 

! put a circle around the "X"
PLOT/VS/OVER/LINE=10/nolab t1+500*xcircle,0.05*ycircle+val1 

Example (continued): 

 mark-up over a Hofmuller diagram (Figure 6_5) 

SHADE/X=180 sst                             !  latitude vs time plot
LET tlo = tt[T="1-jul-0000"@itp]
LET thi = tt[T="1-aug-0000"@itp]
POLYGON/OVER/LINE=7/PAL=gray/PAT=lite_up_left_to_right {`tlo`, `thi`,` thi`, `tlo`},  {20, 20, 40, 40} 

Ch6 Sec4.  LABELS 

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. 

Ch6 Sec4.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 (p. 196). 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. 

Beginning with Ferret v5.53, 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 examples on pages 197 and 197. 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  

Ch6 Sec4.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," p. 207). 

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," p. 198). 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 

Ch6 Sec4.3.  Removing movable labels 

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. (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 Sec4.4.  Axis 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 (see p. 195). 

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, p. 442, and SHOW DATA/VARIABLE, p. 435) 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 (see SHOW VARIABLE, p. 442, and SHOW DATA/VARIABLE, p. 435) each modified by its units and comments about transformations in parentheses.  

Ch6 Sec4.5.  Ferret label controls 

In addition to LABEL (discussed above, page 191),  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 (p. 410) and CANCEL MODE (p. 327): 

    Ferret arguments

    SET MODE ASCII_FONT 

    SET MODE CALENDAR 

    SET MODE LATIT_LABEL 

    SET MODE LONG_LABEL 

Ch6 Sec4.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 (p. 185) 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 (p. 185) 

Example 

This example customizes a plot using PPLUS label controls. The LABSET command  (See p.  536) 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" 

Beginning with Ferret v5.53, 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 

Ch6 Sec4.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. (p. 219) 

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"  

Beginning with Ferret v5.53, 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." 

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

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

Ch6 Sec5.  COLOR 

Ferret and PPLUS use colors stored by index. Storage indices 0 and 1 are used as window background and foreground colors. Indices 1–6 are reserved for lines. As the user makes SHADE and FILL requests, each color is assigned to the next available storage index beginning at 7, and that assignment is automatically "protected" when viewports or color overlays are added.  

If your SHADE and FILL commands request more colors than there are storage indices (256), you will be informed with an error message and the color behavior may become unpredictable. For example, if you have multiple viewports defined within a window you may run out of color storage indices. If you are using the same color palette(s) in each viewport, you can free up indices by canceling the color protections with PPL SHASET RESET. See the examples later in this section for details on removing color protection. Currently, there is no way to ask PPLUS how many colors it is using in a plot. 

The following discussion is divided into a treatment of text and line colors, and a discussion of shade and fill color. 

Ch6 Sec5.1.  Text and line colors^note2 

By default the background color is white and the text color is black. To reverse these, so the background is black, call the script "black.jnl". And to restorethe white background, call "white.jnl". Black and white are the only colors that can be used for the background. 

yes? go black
yes? ! ...plot commands...
yes? go white
yes? ! ...more plot commands.. 

Line type and color for plot commands are most easliy controlled by the command qualifiers PLOT/COLOR=,  PLOT/THICKNESS=, and PLOT/DASH  in the Command Reference section (p. 375) 

For text, and optionally for plot lines, line type text colors are regulated by use of storage indices 1–6, each index associated with a default color. These are listed in the table in the section "PPLUS text and line color commands" below (p. 200) It is possible to change the six available line colors with the PPLUS enhancements command COLOR. (See Plotplus Plus: Enhancements to Plotplus.)  When you create a plot with multiple data lines, Ferret automatically draws each line in a different color. By default, axes, labels, and the first data line are all drawn in the same color. You can modify this behavior with the following Ferret and PPLUS commands. 

Ch6 Sec5.1.1.  Ferret color controls for lines 

Plotted line colors can be set using the /COLOR=  qualifier on PLOT, CONTOUR, VECTOR, or POLYGON commands. The available colors are black, red, green, blue, lightblue, purple, and white. In addition, starting with Ferret version 5.4, the user has direct control over dashed lines, and can combine them with choices of colors and thickness. 

Plotted colors and line type may also be set with the older syntax 

yes? PLOT/LINE=n
yes? VECTOR/PEN=n
yes? CONTOUR/PEN=n 

where "n" is an integer between 1 and 18. 

More direct control over line color and thickness is available with the qualifiers /COLOR and /THICKNESS and the line type is controlled with /DASH, /SYMBOL=, and /SIZE= 

Examples 

1) Overlay three lines 

yes? PLOT/i=1:10  1/i 

yes? PLOT/OVER/COLOR=green/i=1:10 1/(i+3) 

yes? PLOT/OVER/i=1:10/COLOR=purple/THICK=3 1/i+1/(10-i) 

2) dashed lines with color and thickness settings 

yes? PLOT/DASH/I=1:100 sin(i/5)
yes? PLOT/OVER/DASH=(0.3,0.1,0.3,0.1)/COLOR=RED/THICK/I=1:100 sin(i/7)
yes? PLOT/OVER/DASH=(0.6,0.2,0.1,0.2)/COLOR=RED/THICK/I=1:100 sin(i/9) 

3) Symbols with color and thickness settings 

yes? PLOT/THICK=2/I=1:100 sin(i/5) 

yes? PLOT/OVER/COLOR=red/THICK=3/SYM=4/SIZ=0.10/i=1:100 sin(i/7) 

yes? PLOT/OVER/COLOR=green/LINE/SYM=20/SIZ=0.15/i=1:100 sin(i/9) 

Ch6 Sec5.1.2.  PPLUS text and line color commands 

Older syntax uses the PPLUS command PEN (p. 542) to assign a color and thickness index to a specified pen. The pen colors are also used to set pen colors for labels (see p. 207). The PPL  PEN command takes the form: 

yes? PLOT/SETUP var 

yes? PPL PEN pen_#, color_thickness 

yes? PPL PLOT 

where pen_# is the PPLUS pen number and color_thickness is a color and thickness index. PPLUS uses different pens for different tasks. By default, color_thickness index 1 is assigned to pen 0. The following chart may be helpful. 

Note: Whether you plot several data lines simultaneously, or use the /OVERLAY qualifier on your Ferret commands, the color/thickness result will be the same. But the Ferret/PPLUS interaction is different. When Ferret plots multiple data lines simultaneously, PPLUS automatically cycles through pen numbers 1 through 6 combined with symbols. Type GO line_samples in Ferret to see the 36 different line styles. However, if you are using /OVERLAY for additional data lines, Ferret controls the color_thickness assigned to pen 1 and PPLUS draws each overlay line with pen 1. 

Pen numbers range from 0 to 6, and color_thickness indices range from 0 to 18. The values 1 to 18 follow the formula: 

    color_thickness = 6 * (thickness - 1) + color 

where thickness ranges from 1 to 3 and color from 1 to 6. Type "GO line_thickness" in Ferret to see actual colors and thicknesses. Further information is in the appendix, "Ferret Enhancements to PlotPlus, (p. 565) 

The special color_thickness index 0 refers to the background color, which produces "invisible" lines that can be used as "white-out" for special purposes. Pen 19 is a thin, white line which can be used to draw in white over a colored area. Thicker white lines are not available. 

The following PPLUS commands use the color_thickness index. 

Examples 

1) Ferret's default behavior—these two plots will look identical 

yes? PLOT/i=1:10  1/i, 1/(i+3), 1/i + 1/(10-i)  !3 curves with 3 pens
yes? PLOT/i=1:10 1/i                            !first curve with pen 1
yes? PLOT/OVER/i=1:10 1/(i+3)         !overlay with pen 1 (next index)
yes? PLOT/OVER/i=1:10 1/i+1/(10-i)    !overlay with pen 1 (next index) 

2) select different colors for pens 0 and 1 

yes? PLOT/i=1:10/SET 1/i
yes? PPL PEN 1 4         !assign color_thickness 4 to pen 1 (plot curve)
yes? PPL PEN 0 3         !assign color_thickness 3 to pen 0 (axes & labels)
yes? PPL PLOT            !render the plot
yes? PPL PEN 0 1         !reset pen 0 to default color_thickness (not\
                         reset by Ferret as is pen 1) 

3) better way to do above plot: 

yes? PLOT/i=1:10/LINE=4/SET 1/i  !include line style with qualifer /LINE
yes? PPL PEN 0 3 ; PPL PLOT
yes? PPL PEN 0 1 

4) To make a white label 

yes? SHADE/L=1 sst
yes? LABEL/NOUSER 4,4,0,0,0.14 "@C019White Text"l 

Ch6 Sec5.2.  Shade and fill colors 

Colors specified with the PPLUS SHASET command or in pallette files (also called spectrum files) contain pre-defined color palettes. With Ferret 5.0 there are now three ways to specify how colors are set in SHADE, FILL, and POLYGON plots: the earlier Percent RGB mapping, and also By_value and By_level. 

For examples of these palettes, try the demo script, 

yes? go palette_demo 

There is also an FAQ about choosing palettes, 

How can I choose a good color palette for my plot? at http://ferret.pmel.noaa.gov/FERRET_17sep07/FAQ/graphics/colorpalettes.html 

The Percent method defines points along an abstract path in RGB color space that runs from 0 to 100 percent. The pallette file bluescale.spk, for example, contains these lines. 

      0  0  0 95 

    100 95 95 95 

The first number on each line is the percentage distance along the path in color space, and the following numbers are the percents of red, green, and blue, respectively. In this simple two-line file, the percentage runs from 0 to 100 % and the colors represent a range of blues from dark to light. The percents in the first column must be in ascending order. The actual colors used by SHADE or FILL are determined by dividing this abstract color scale into N equal increments, where N is the number of colors, and linearly interpolating between the red, green, and blue values from the neighboring SHASET percentage points. 

For compatibility with older palette files, the Percent RGB mapping method is the default, and pre-5.0 palette files will be interpreted correctly. Palette files using Percent RGB mapping written out with Ferret 5.0 will have a slightly different format. A starting line is optional, specifying "RGB_Mapping_Percent". Any line starting with a ! will be ignored as a comment line. Blank lines are ignored. for example the bluescale palette saved with Ferret 5.0 will look like this: 

The first line informs Ferret that the RGB mapping method is Percent. Lines beginning with an exclamation point are comments and ignored when read in—palette files created or modified using a text editor can contain comment lines as documentation. Note that palette files need to be unix-formatted files; values separated by tabs may not be read correctly. 

The RGB mapping method By_value uses color interpolation similar to the Percent method, with the significant difference that colors are based on the values of the variable being plotted rather than an abstract zero to 100 percent axis. When you use the same By_value palette in several plots, identical values of one variable will be represented by the same color in each plot. Specify "RGB_Mapping_By_value" as the first line in the palette file. A line starting with a ! will be ignored as a comment line. Blank lines are ignored. The values in column 1 must be in ascending order. For example with the following palette, ocean_temp.spk: 

a particular temperature, say 25 degrees, will have the same color on a SHADE or FILL plot with levels ranging from 0 to 30, and on a plot with levels between 20 and 30 degrees. 

The third RGB mapping method By_level allows the user to select the precise color to be used at each level in SHADE and FILL plots. Unlike the other methods, no interpolation of RGB values is done. Colors specified in the palette will be used exactly as defined. If there are more SHADE or FILL levels than colors specified, the color palette will repeat. Specify "RGB_Mapping_By_level" as the first line in the palette file. A line starting with a ! will be ignored as a comment line. Blank lines are ignored. The levels listedin column 1 must be in ascending order.In the following palette, by_level_rainbow.spk, 

for example, with 6 colors defined and used in a plot with 10 levels, the colors used at each plot level will be as follows: 

Ch6 Sec5.2.1.  Ferret shade and fill color controls 

By default, Ferret will use the PPLUS spectrum file default.spk for shades and fills (normally default.spk is a Unix soft link to rnb.spk). Ferret comes with many color palettes. The UNIX command "Fenv" lists the environment variable $FER_PALETTE which is a list of paths to be searched for palette files (the palette file names all end in .spk). The UNIX command "Fpalette" allows you to find and examine these files (type "Fpalette -help" at the Unix prompt). You can easily create your own palette files with a text editor. 

Use the Ferret qualifier /PALETTE= with Ferret graphical output commands CONTOUR/FILL and SHADE to specify a color palette. See the section in this chapter, "Contouring," p. 213, for details on the CONTOUR qualifier /LEV, which controls colors and dash patterns, as well as sets contour levels. 

    Ferret qualifiers

    /PALETTE=        (alias for PPL SHASET SPECTRUM=) 

    /LEV= 

PALETTE is also a stand-alone command alias; it sets a new default color palette. 

Be aware that when you use /PALETTE= in conjunction with /SET_UP, the color spectrum you specify becomes the new default palette; to restore the default palette use command PALETTE with no argument. 

Ch6 Sec5.2.2.  PPLUS shade color commands 

SHASET is an enhancement of PPLUS designed for Ferret. You can specify a color spectrum, save a spectrum, change an individual color in the spectrum, or remove the protection (PPL SHASET RESET) for colors already on the screen. See Plotplus Plus: Enhancements to Plotplus (p. 564) for more information. 

If you need precise control over each individual RGB color on your plot, run "GO  exact_colors", which contains instructions on modifying individual colors in a palette using SHASET. 

The SHAKEY command (see p. 563) allows you to customize the location, size and labelling of the color key for SHADE and FILL plots. 

Examples 

1) look at the relief of the earth's surface 

yes? SET DATA etopo120
yes? SHADE rose                        !Ferret's default plot
yes?   ! Emphasize land and sea with palette,customize the color key 

yes? SHADE/PALETTE=land_sea/SET_UP rose palette 

yes? PPL SHAKEY 1,0,0.1,2, , ,1.2,7.2,7.5,8.2 

yes? PPL SHADE 

2)    Perhaps you would like to compare two topography resolutions. To illustrate what happens when you use more colors than are available, request an excessively large number of levels: 

yes? SET DATA etopo120
yes? SET REGION/Y=-20:20
yes? SET VIEWPORT UPPER                   !upper half
yes? SHADE/LEV=(-8000,8000,100) rose      !160 colors, default palette
yes? SET VIEWPORT LOWER                   !lower half
yes? SET DATA etopo20                     !high resolution
yes? SHADE/LEV rose[d=etopo20]            !another 160 colors (320 > 256!)
yes? CANCEL VIEWPORT

PPL+ error: You're attempting to use more colors than are available.
           Using SHASET RESET to re-use protected colors may help. 

If you reuse the same palette, as in this example, issue PPL SHASET RESET after the first plot. Now the second picture is made without error: 

yes? SET DATA etopo120
yes? SET REGION/Y=-20:20
yes? SET VIEWPORT UPPER
yes? SHADE/LEV=(-8000,8000,100) rose
yes? SET VIEWPORT LOWER
yes? PPL SHASET RESET                     !reuse color storage indices
yes? SET DATA etopo20
yes? SHADE/LEV rose[d=etopo20]
yes? CANCEL VIEWPORT 

Ch6 Sec6.  FONTS 

Ch6 Sec6.1.  Ferret font and text color 

By default, Ferret produces all plot labels using the fonts ASCII Simplex (code AS) and ASCII Complex (code AC). For upper and lower case letters these fonts are identical to the fonts Simplex Roman (SR) and Complex Roman (CR), respectively. In addition, however, fonts AS and AC include the complete set of ASCII punctuation characters and ignore the special PPLUS interpretations of the characters "^" (superscript), "_" (subscript), and "@" (change font or pen). Using a text editor, the ESCAPE character (decimal 27) may be inserted before the special characters to restore their special interpretation. 

The Ferret command CANCEL MODE ASCII causes Ferret to generate PPLUS labels which have the font unspecified. When the font is unspecified the PPLUS command DFLTFNT determines the default font and PPLUS  responds to the special characters "^", "_", and "@". SET MODE ASCII restores normal font behavior. 

Ch6 Sec6.2.  PPLUS font and text color commands 

PPLUS commands can be used to customize the font settings. See the examples below, and the section on PPLUS graphical commands (p. 185) for more on the syntax to make PPLUS calls. 

Note that many ASCII punctuation characters are printable only in ASCII simplex and complex fonts. In all other fonts these characters "@", "^", and "_" have special meanings: @ = font change; ^ = superscript; _ = subscript. 

Examples 

1) axis labels in custom fonts (Figure 6_7) 

yes? PLOT/SET/i=1:10/NOLAB 1/i
yes? PPL XLAB @CImy x-axis label
yes? PPL YLAB @GEmy y-axis label
yes? PPL PLOT 

2) set default font for all labeling (Figure 6_8)  

yes? CANCEL MODE ASCII
yes? PPL DFLTFNT CS      !complex script
yes? PLOT/I=1:100/TITLE="sin curve"  sin(i/6)
yes? SET MODE ASCII
yes? PPL DFLTFNT SR      !numeric axis labels unaffected by SET MODE ASCII 

Ch6 Sec7.  PLOT LAYOUT 

Ch6 Sec7.1.  Ferret layout controls 

Layout of plots can be controlled with commands which modify window size and aspect ratio, and viewports. 

    Ferret command

    SET WINDOW/SIZE=/NEW/ASPECT= 

    DEFINE VIEWPORT/XLIMITS=/YLIMITS=/TEXT=    view_name 

    SET VIEWPORT   view_name 

    CANCEL VIEWPORT 

Ch6 Sec7.1.1.  Viewports 

A viewport is a sub-rectangle of a full window. Viewports can be used to put multiple plots onto a single window. 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. A number of the most commonly desired viewports are pre-defined. 

Ch6 Sec7.1.2.  Pre-defined viewports 

Example:  Graphics Viewports 

Plot four variables from coads_climatology into the four quadrants of a single window (Figure 6_9). 

yes? SET DATA coads_climatology
yes? SET REGION/@W/L=8
yes? SET VIEWPORT LL
yes? CONTOUR sst                         !sea surface temperature
yes? SET VIEWPORT LR
yes? CONTOUR airt                        !air temperature
yes? SET VIEWPORT UL
yes? CONTOUR slp                         !sea level pressure
yes? SET VIEWPORT UR
yes? VECTOR/XSKIP=4/YSKIP=4 uwnd,vwnd    !zonal wind, meridional wind
yes? CANCEL VIEWPORT 

Ch6 Sec7.1.3.  Advanced usage of viewports 

For the purposes of defining viewports, a graphics window is considered to have length 1 and height 1. All viewport commands refer to positions relative to the current aspect ratio of the window. Thus, 

yes? DEFINE VIEWPORT/XLIM=.5,1/YLIM=.5,1  V5 

will locate the origin of viewport V5 in the upper right of the output window regardless of the shape of the window. 

yes? DEFINE VIEWPORT/XLIM=0.,1/YLIM= 0,.3 V1
yes? DEFINE VIEWPORT/XLIM=0.,1/YLIM=.3,.6 V2
yes? DEFINE VIEWPORT/XLIM=0.,1/YLIM=.6,.9 V3 

defines three viewports; each takes a third of the height of the page, and the entire width. 

The qualifiers /XLIMITS=x1,x2 and /YLIMITS=y1,y2 allow the user to specify a portion of the graphics window to be the defined viewport. The arguments must be values between [0,1] (NOT world coordinates). x1 and x2 indicate the lower and upper bounds for the length of the window to be defined as the viewport; y1 and y2 serve an analogous purpose for height. 

The /TEXT=n qualifier allows the user control over the shrinkage or enlargement of text on the plot. A value of /TEXT=1 indicates that the text size should be the same as it is on the full screen output. If a value less than 1 is specified the text will shrink. If a value is not specified Ferret chooses a value appropriate to the viewport size. Acceptable values are 0 < n < inf. but only values up to about 2 yield useful results. 

Ch6 Sec7.1.4.  Viewport Symbols 

When we "set viewport viewport_name" a number of Ferret symbols are set, giving access to the viewport size, scaling, the values given to XLIM and YLIM when defining the viewport, and the margins. See the Ferret Special Symbols section (p. 221) for a list of these symbols. 

Ch6 Sec7.2.  PPLUS layout commands 

The following PPLUS commands can be called to customize the plot layout. See the section on PPLUS graphical commands for how to call PPLUS plot commands (p. 185)