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:

Ch6 Sec2. GRAPHICAL OUTPUT

Ch6 Sec2.1. Ferret graphical output controls

Ch6 Sec2.2. PPLUS graphical output commands

Whenever a plot is customized using /SET_UP to delay display, 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.

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 controls

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

    /XLIMITS,  /YLIMITS, /NOAXIS

The /XLIMITS and /YLIMITS qualifiers use the syntax /XLIMITS=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 Commands Reference section of this manual (p. 243) for more information.

Ch6 Sec3.2. PPLUS axis commands

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 (Figure 6_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

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 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, but not the axis labels of independent axes; PPLUS commands XLAB, YLAB, and AXLABP control axis labels.

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

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. 143). At the end of this line is the text of the movable label.

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

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

Example

yes? PLOT/I=1:100  sin(i/6)
yes? LABEL 50, 1.2, 0, 0, .2  @P2MY SIN PLOT

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

!upper viewport has a "signature"
yes? PPL BOX on
yes? SET VIEW upper
yes? PLOT/I=1:100 sin(i/6)

!in the lower viewport
!the signature has been removed
yes? SET VIEW lower
yes? GO unlabel 1
yes? GO unlabel 2
yes? GO unlabel 3
yes? PPL PLOT
yes? CANCEL VIEWPORT

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.

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

Ch6 Sec4.5. Ferret label controls

In addition to LABEL (discussed above),  Ferret controls include the /NOLABELS qualifier, which suppresses default plot title, documentation and signature, 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

    ASCII_FONT

    CALENDAR

    LATIT_LABEL

    LONG_LABEL

Ch6 Sec4.6. PPLUS label commands

Ferret stores the text strings of the following labels in PPLUS symbols. The symbol names are:

As stated above, PPLUS commands regarding movable labels are largely superceded by the Ferret command LABEL and "GO unlabel n".

Example

This example customizes a plot using PPLUS label controls.

yes? PLOT/Z=20/I=1:100/SET_UP   z * sin(i/6)
yes? PPL LABS 4,48,0,0 @p2'lab4'
yes? PPL HLABS 4,.25
yes? PPL LABS/NOUSER 5,0,6.3,-1  *** Magnified SIN function ***
yes? PPL LABSET ,,,.35
yes? PPL PLOT

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

Line and text colors are regulated by use of storage indices 1–6, each index associated with a default color. 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.

See also the newer command qualifiers PLOT/COLOR= and PLOT/THICKNESS=  in the Command Reference section (p. 282)

Ch6 Sec5.1.1. Ferret color controls for lines

Plotted line colors can be set using

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

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

Ch6 Sec5.1.2. PPLUS text and line color commands

The PPLUS command PEN assigns a color and thickness index to a specified pen.  (Note that as of Version 5.2 color and thickness can be assigned directly with qualifiers to  the PLOT (p. 281), VECTOR, CONTOUR, or POLYGON commands with, for example, PLOT/COLOR=red/THICK=2  See the discussion of /COLOR and /THICKNESS in the Command Reference section, p. 281).  The PPL  command takes the form:

yes? PPL PEN pen_#, color_thickness

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.

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.

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

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.

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 a line is the percentage distance along the path in color space, and the following numbers are the percents of red, green, and blue, respectively. 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; for example the bluescale palette saved with Ferret 5.0 will look like this:

RGB_Mapping Percent

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.

The new 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. For example with the following palette, ocean_temp.spk:

RGB_Mapping By_value

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 second new 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. In the following palette, by_level_rainbow.spk,

RGB_Mapping By_level

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. 156, 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 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.

Examples

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

yes? SET DATA etopo120
yes? SHADE rose                 !Ferret's default behavior
yes? SHADE/PAL=land_sea rose    !emphasize land and sea with palette

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, you can issue PPL SHASET RESET after the first plot and plot the second picture 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 controls

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 commands

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.2. PPLUS layout commands

Ch6 Sec7.3. Controlling the white space around plots

The location and size of the axis rectangle within the viewport or window determines the amount of white space surrounding a plot. Complete control over this is possible using low level controls, DEFINE VIEWPORT/TEXT_PROMINENCE, PPL ORIGIN, and PPL AXLEN, but these commands are sometimes awkward to work with. A simpler strategy is to use the GO tool

yes? GO margins

When given without arguments this command will report the amount of white space surrounding a plot. With arguments it will adjust the axis origins and lengths according to the requested margins. Try the Unix command

> Fgo -more margins

for further documentation.

Ch6 Sec8. CONTOURING

Ch6 Sec8.1. Ferret contour controls

The following qualifiers to the Ferret command CONTOUR allow customization of a contour plot.

Ch6 Sec8.1.1. /LEVELS qualifier

The /LEVELS qualifier is a powerful and multi-functional tool.  It takes the form /LEVELS=levels_descriptor

/LEVELS  without an argument /LEVELS instructs Ferret to reuse CONTOUR or SHADE levels from the last CONTOUR or SHADE plot

/LEVELS=n  specifying a simple numerical argument such as /LEVELS=25 instructs Ferret to select approximately 25 levels automatically, based upon the limits of the data to be plotted

/LEVELS=nC (centered levels)  appending a "C" to the suggested number of levels instructs Ferret to select levels which are centered about the zero level. Such levels are suitable for zero-symmetric quantities such as anomalies and velocity components.

/LEVELS=x.xD (delta levels)  Use of "D" as a suffix instructs Ferret to use the preceding value as the delta value between contour levels. Thus /LEVELS=0.25D will cause Ferret to select contour levels that span the range of the data to be contoured with a delta value of 0.25 between contour levels. The "D" and "C" notations can be combined. For example, /LEVELS=0.25DC instructs Ferret to create zero-centered levels with a delta of 0.25 spanning the range of the data.

/LEVELS=(lo, hi, delta)
or
/LEVELS=(lo, hi, delta, ndigits)
or
/LEVELS=(value)

where ndigits is the number of decimal places to use on contour levels as
-1   for integer format
    or
-3   to omit numerical labels

Examples

 Note that by default the contour lines of negative values will be dashed and the zero contour will be a heavy (DARK) line. See also (p. )  for selecting color and thickness with the PEN option, below.

Refinements to the basic levels may be applied using the syntaxes below. If blanks are included, surround the entire levels descriptor in double quotation marks.

To request additional levels, simply append additional (lo, hi, delta) and/or (value) specifiers.

To specify the line type as dark (heavy line), append DARK(lo, hi, delta) or DARK(value). Similar syntax can be applied to LINE (solid, thin) or DASH.

To remove selected levels, append the specifier DEL(lo, hi, delta) or DEL(value).

To specify the color_thickness index of contour lines (see the section in this chapter, "Color, " p. 145, for a discussion of color_thickness indices), append PEN(lo, hi, delta, index).

Ch6 Sec8.2. PPLUS contour commands

CONSET is a modified version of the PPLUS command. Two new parameters have been added—"spline_tension" and "draftsman". "spline_tension" controls a spline fitting routine for contour lines, and is primarily used in conjunction with the narc parameter. The new parameter "draftsman" enables the user to specify horizontally oriented contour labels (draftsman style) or the default, labels oriented along contour lines. Arguments for CONSET are as follows:

CONSET hgt,nsig,narc,dashln,spacln,cay,nrng,dslab,spline_tension,draftsman

hgt = height of contour labels.  default=.08 inches

nsig = no. of significant digits in contour labels.   default=2

narc = number of line segments to use to connect contour points.   default=1

dashln = dash length of dashes mode.   default=.04 inches

spacln = space length of dashes mode.   default=.04 inches

cay  This argument has no effect on gridded data. It is documented in PLOT PLUS for Ferret User's Guide and also in the discussion of objective analysis under command USER in the Commands Reference section of this manual.

nrng   This argument has no effect on gridded data. It is documented in PLOT PLUS for Ferret User's Guide and also (as parameter "rng") in the discussion of objective analysis under command USER in the Commands Reference section of this manual.

dslab= nominal distance between labels on a contour line. default=5.0 inches.

spline_tension = a real value that affects the fit of the contour line. default=0. This parameter is only applied if narc is greater than 1. Otherwise, straight lines are drawn between data points and no interpolated points are contoured. This value indicates the curviness desired.

abs(spline_tension) is nearly zero (e.g.,  .01). The resulting curve is approximately a cubic spline.

abs(spline_tension) is large (e.g., 10.). The resulting curve is nearly a polygonal line.

spline_tension = 0. The resulting curve is a cubic spline (the default algorithm in ppl).

A typical value for spline_tension is 1, and the typical useful range of values is .01 to 10.

draftsman = a real value that controls the label format. default = 0.

    0. = original label style—labels oriented along contour arcs

    > 0. = draftsman label style—labels oriented horizontally on the page

    < 0. = reserved for future use

Examples

Run the demonstration on custom contouring for many examples of label styles, contour line styles (color, thickness dash pattern), and contour intervals— yes? GO custom_contour

1) Color-filled contour plot of sea surface temperature

yes? SET DATA coads_climatology
yes? SET REGION/@t/l=6          !specify tropical Pacific, month 6
yes? SET VIEWPORT upper
yes? FILL sst                   !filled contour plot
yes? SET VIEWPORT lower
yes? FILL/LINE sst              !make the plot with contour lines

2) Let's improve on the earlier example (5.2.2) of shaded bathymetry with blue palette

yes? SET DATA ETOPO60
yes? LET/TITLE="Surface relief x1000 (meters)" r1000 rose/1000
yes? FILL/PAL=ocean_blue/LINE/LEV=(-8,-1,1,-3)LINE(-8,-1,1,-3)/PEN=4 r1000

Here is a breakdown of the final command line:

Ch6 Sec9. PPLUS SPECIAL SYMBOLS

PPLUS defines a number of global symbols which are available to the user with SHOW SYMBOL They are documented in the PPLUS Users Guide, section 7.3, and listed here.  These are not defined until  associated plot commands have been issured.  Also note that the user cannot redefine the value of these symbols.

Example: draw a plot and examine  some of the symbols

yes? plot/i=1:10 1./i

yes? SHOW SYMBOL ppl$xlen
PPL$XLEN = "8.000"
   ! Try to show an undefined variable (no response)
yes? SHOW SYMBOL ppl$lf_var

yes? SHOW SYMBOL ppl$line_count
PPL$LINE_COUNT = " 1"

Ch6 Sec10. MAP PROJECTIONS AND CURVILINEAR COORDINATES

Ch6 Sec10.1. Three-argument (curvilinear) version of SHADE, FILL, CONTOUR, and  VECTOR

The SHADE, FILL, CONTOUR and VECTOR commands now have a 3-argument mode which allows them to create output in "curvilinear" coordinates. This allows for easy generation of output plots using sigma coordinates as well as the application of various map projections. A typical command line entry will look like:

yes? SHADE sst, x_page, y_page

where the second and third arguments, x_page(i,j) and y_page(i,j), must be (at least) 2-dimensional grids which specify the X page (horizontal) position and Y page (vertical) position for each (i,j) index pair. The page positions may be in any units; Ferret will scale the plot according to the ranges of values in the position fields.

Note: The default axis labeling for the 3-argument commands will be the ranges of the position fields: inappropriate when map projections are being used. The /NOAXIS qualifier is provided for this purpose.

The /NOAXIS qualifier causes the axes and axis labels to be omitted from the plot. (See the AXSET command in the PLOT+ Users Guide). The qualifier has been added to support the curvilinear coordinate and map projection capabilities of the 3-argument versions of SHADE, FILL, CONTOUR and VECTOR in which linear axes are inappropriate.

Note that if the /SET_UP qualifier is used in conjunction with /NOAXIS a Ferret state is altered such that future plots will be drawn without axes. Ferret will warn you of this and coach you to use PPL AXSET 1, 1, 1, 1 to restore normal axis drawing.

Ch6 Sec10.2. Gridded data sets on curvilinear coordinates

If a given gridded variable is defined on a curvilinear coordinate system, then one need only provide the X and Y coordinate fields in the 3-argument SHADE or FILL command to accurately depict the field. For example, if a data set contained a variable TEMP, which was Nx x Ny in the longitude-latitude plane, and the data set also contained variables LON_POSITION and LAT_POSITION of the same size, then the command:

yes? SHADE TEMP, LON_POSITION, LAT_POSITION

would render the curvilinear plot.

Ch6 Sec10.3. Layered (sigma) coordinates

The capability to render curvilinear coordinates allows Ferret to display sigma coordinate fields without interpolating or regridding the variable to be displayed.

In this example the variable flow is defined on the gg grid where the Z axis is in layers. To display the field we need only create multidimensional fields specifying the relative positions of (i,j) pairs and use the new curvilinear coordinate commands (Figure 6_10):

yes? let depth = h[k=@rsum]-h/2
yes? set variable/title="DEPTH function"/unit=meters depth
yes? ! regrid 'Y' to the data grid
yes? let ygg = y[g=gg]
yes? set variable/title="Y"/unit=kilometers ygg
yes? shade flow[x=0,l=1], ygg, depth[x=0,i=1]

For a detailed example illustrating the use of curvilinear coordinates to analyze sigma-coordinate fields see the Ferret FAQ entry, How to handle sigma coordinate output in Ferret.

Ch6 Sec10.4. Map Projections

Along with general capabilities for curvilinear coordinates, version 4.9 of Ferret and later provide a series of scripts for many common map projections.

Each map projection script will create the following variables:

Ch6 Sec10.4.1. Using Map Projection scripts

To create output with a particular map projection you must do the following:

1.    set grid for the variable you wish to plot

2.    run the map projection script

3.    adjust the window aspect ratio (if desired)

4.    multiply the variable of interest by mp_mask (required for "3-D" projections)

5.    give the three-argument plotting command

Example: (Figure 6_11)

yes? use coads_climatology
yes? set region/l=1
yes? set grid sst
yes? go mp_hammer
yes? go mp_aspect
yes? shade/noaxis sst*mp_mask, x_page, y_page

Ch6 Sec10.4.2. Overlays with Map Projections

Overlays can be drawn once a map projection script has been run. To add a filled land mask, sea level pressure and wind vectors onto our SST map we would issue the following commands (Figure 6_12):

yes? set grid uwnd
yes? go mp_fland
yes? vector/over/pen=1 uwnd*mp_mask, vwnd*mp_mask, x_page, y_page
yes? set grid slp
yes? contour/over/pen=5 slp*mp_mask, x_page, y_page

Note that the 4-argument (curvilinear) VECTOR command is unsupported (as of Version 5.2) and is known not to work for irregular grids.  The command is provided to help give a qualitative feel for vectors in various map projections but the vector lengths are not correct.  There are also some problems with vectors at region boundaries.

If, instead, we wished to overlay sea level pressure for the South Atlantic only, we would need to take advantage of the mp_central_meridian and mp_standard_parallel variables. Normally, the map projection scripts calculate the central meridian and standard parallel from the currently set region and generate the x_page and y_page coordinate transformations accordingly. When we overlay a subregion, we need to rerun the map projection script and pass in values for mp_central_meridian and mp_standard_parallel so that they are match the previous values and are not calculated from the subregion associated with the overlay. (Figure 6_13)

yes? use coads_climatology
yes? set region/l=1
yes? set grid sst
yes? go mp_hammer
yes? go mp_aspect
yes? shade/noaxis sst*mp_mask, x_page, y_page
yes? go mp_fland
yes? list mp_central_meridian, mp_standard_parallel
       LONGITUDE: 20E to 20E(380)
       LATITUDE: 90S to 90N
Column  1: MP_CENTRAL_MERIDIAN is (MP_X[I=@MAX] + MP_X[I=@MIN])/2
Column  2: MP_STANDARD_PARALLEL is (MP_Y[J=@MAX] + MP_Y[J=@MIN])/2
       MP_CENTRMP_STAND
I / *:     200.0  0.0000
yes? go mp_hammer 200 0
yes? set region/x=60w:20e/y=45s:0n
yes? set grid slp
yes? contour/over slp, x_page, y_page

Note: Had we used go mp_hammer 200 0 in the beginning we would not have had to rerun mp_hammer.

Ch6 Sec10.4.3. Map Projection scripts

Here is the list of map projection scripts delivered with Ferret. (The techniques used are quite general and can be applied to most map projections.)

Here is the list of utility scripts to support curvilinear coordinates