6.8.1 Ferret contour controls
The following qualifiers to the Ferret 2-D graphics commands (CONTOUR, CONTOUR/FILL (alias FILL), SHADE, POLYGON and PLOT/RIBBON (alias RIBBON) ) allow customization of a the color levels for these plot types. Not all of these qualifers apply to all of the plot styles; several apply only to contour plots. These are noted below.
|
|
|
| Qualfier | Function |
|
/FILL |
(CONTOUR/FILL only) Produces a color-filled contour plot (command FILL is an alias for CONTOUR/FILL) |
|
/LEVELS |
specifies contour levels, dash patterns, line thickness and color |
|
turns on display of color key for color plots. (default) |
|
|
/NOKEY |
turns off display of color key for color-filled plots |
|
/NOAXIS |
turns off display of X and Y axes (useful for map projections) |
|
adds contour lines to a color-filled contour plot (lines replace key) |
|
|
/PALETTE= |
specifies a color palette for color plot |
|
/PEN= |
sets line style for contour lines (same arguments as PLOT/LINE=. See the section in this chapter, "Text and Line Colors". |
|
/COLOR= |
sets line color for contour lines. Color can be specified by number as in /PEN=, or with a name. The available names are black, red, green, blue, lightblue, purple, and white |
|
/THICKNESS= |
sets line thickness for contour lines. The argument can take the values 1,2, or 3. 1 is the default thicness, a thin pen; 2 and 3 are thicker. |
|
/SIGDIG= |
sets the number of digits after the decimal point for contour labels; default is 2 |
|
/SIZE= |
sets the size of characters in the contour labels; default is 0.08 |
|
/SPACING= |
sets spacing for the contour labels, using PLOT+ definition of "inches"; default spacing is 5.0. This is a nominal value; the algorithm will determine actual spacing. |
The /LEVELS qualifier for FILL , SHADE, POLYGON and RIBBON commands is a powerful and multi-functional tool. It takes the form /LEVELS=levels_descriptor
/LEVELS without an argument /LEVELS instructs Ferret to reuse the color levels from the last color plot
/LEVELS=n specifying a simple numerical argument such as /LEVELS=60 instructs Ferret to select approximately 60 levels automatically, based upon the limits of the data to be plotted. MODE NLEVELS sets the default value for this; its initial value is 30.
/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=nV (variance-based levels) Automatic open-ended levels. Ferret finds the mean and standard deviation of the data to be color-filled or contoured. Within the range mean-minus 1 std to mean-plus 1 std, fine levels are chosen, and between 1 std and 2 std on each end, coarser levels are used. An open-ended level is used to represent values outside 2 std. The number of levels n is used as an approximate number of levels; the actual number is adjusted to select round numbers for the color levels. The default for n is 30. If the minimum or maximum of the data is inside the range (mean-2STD, mean+2STD), then the color bar will end with the last level that contains the min or max. Thus the levels may not be open-ended, or may be open-ended only on one end. See the discussion below for more options that may be used with variance-based levels.
/LEVELS=ncV (variance-based levels) Automatic centered open-ended levels. The levels will be centered about zero, and if there is an open-ended level on either end of the spectrum, there will be an open-ended level on the other end, even if it is not needed to cover the range of the data. This ensures an equal number of levels on each side of the center.
/LEVELS=nH (histogram-based levels) Ferret sorts the observations and computes the color levels so that each color band contains approximately equal numbers of data points. This form of color management best brings out the fine structure of the data. Here the number of levels n is the exact number of bins used in the histogram calculation. This levels specifier does not combine with other levels descriptors.
/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=(value)
or
/LEVELS=(lo, hi, delta, ndigits)
or
/LEVELS=(-inf)(lo, hi, delta)(inf)
ndigits (applies to CONTOUR command only) is the number of decimal places to use when labeling the level on individual contour lines as:
-1 for integer format
or
-3 to omit numerical labels
(-inf) and (inf) are available starting with Ferret v5.81. When (-inf) or (inf) is specified for FILL or SHADE plots, the variable is filled in with a color on the end of the spectrum for all values below (-inf) or above (inf) the lo and hi values given in the levels specification. These specifiers have no effect on a CONTOUR command. Note that annotating the minimum and maximum on the color key with the KEYMARK alias is useful in combination with variance-based levels or any open-ended levels, see the example in the section on variance-based levels just below.
More options for variance-based levels:
The basic computation for /LEVELS=nV is to find the mean of the data being plotted and base the computation on that mean and the variance. To use a different center location instead of the data mean use
/LEVELS=nV,x.xMEAN where x.x is a value to use as the center
To use a different value for the spread, specify
/LEVELS=nV,x.xSTD where x.x is a value to use in place of the standard deviation from the data.
To stop the levels at a particular value
/LEVELS=nV,x.xMIN where x.x is the lowest value to use. For instance if the data are never going to be negative, /LEVELS=20v,0min would compute the variance-based levels but not use any below 0.
/LEVELS=nV,x.xMAX where x.x is the lowest value to use. For instance if the data are never going to be larger than 100, /LEVELS=20v,100max will compute the variance-based levels but not use any larger than 100.
Note that annotating the minimum and maximum on the color key with the KEYMARK alias is useful in combination with variance-based levels or any open-ended levels:
Example:
yes? USE etopo20 yes? KEYMARK,1 ! turn on annotation for color keys yes? SHADE/LEV=50v rose
Symbols with Levels settings
When a CONTOUR or SHADE plot is finished, the levels that were used are stored in a set of symbols so the settings can be used again or modified for subsequent plots. These symbols are
|
LEV_MIN |
minimum level used; if (-inf) given, then the value of LEV_MIN is the minimum in the data field |
|
LEV_MAX |
maximum level used; if (inf) given, then the value of LEV_MIN is the maximum in the data field |
|
LEV_NUM |
number of levels used |
|
LEV_DEL |
Delta between values, if the levels were uniform, or "irregular" |
|
LEV_TXT |
The argument to the levels qualifier |
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 below for selecting color and thickness with the PEN option.
|
/LEVELS=(-20,10,2) |
! basic low,high,delta |
|
/LEVELS=(5) |
! a single level at 5 |
|
/LEVELS=(-20,10,2,-3) |
! suppress numerical contour labels |
|
/LEVELS=40 |
! approximately 40 automatically selected levels |
|
/LEVELS=40C |
! approximately 40 automatic levels centered equally about zero |
|
/LEVELS=0.2D |
! automatic levels with a delta value of 0.2 |
|
/LEVELS=0.2DC |
! automatic zero-centered levels with a delta value of 0.2 |
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.
|
/LEVELS="(-100)(-10,10,2)(100)" |
! focus on -10 to10 range, but catch outliers |
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. The range of levels must first be specified before
customizing them with DARK or DASH.
|
/LEVELS="(-100,100,5)DARK(-100,100,25)" |
! heavy line on multiples of 25 |
|
/LEVELS="(0,10,2) DASH(2,10,2)" |
! use dashed lines for positive values |
|
/LEVELS="(0,10,2) LINE(0) DARK(6)" |
! a regular thin line for 0 and a dark line on level 6 |
To remove selected levels, append the specifier DEL(lo, hi, delta) or DEL(value).
|
/LEVELS="(-10,10,2) DEL(0)" |
! -10 to 10 by 2's with the zero contour removed |
To specify the color_thickness index of contour lines (see the section in this chapter, "Color", for a discussion of color_thickness indices), append PEN(lo, hi, delta, index). PEN does not change the default line styles: thick at 0, dashed for negative. Those settings are made with DASH, LINE, and DARK as listed above.
|
/LEVELS=(0,1,.2) PEN(.6,1,.2,2) |
! use pen #2 (red) for the upper contour levels |
|
/LEVELS="(-100,100,10) PEN(-100,-10,10,2) PEN(10,100,10,4)" |
! Use Pen 2 (red) for negative levels and pen 4 (blue) for positive levels. |
To apply the previous levels to a new plot, use the /LEVELS qualifier alone. To do more, the levels symbols let you apply the settings in new ways:
yes? USE coads_climatology yes? CONTOUR/L=1 sst yes? SHOW SYM LEV* LEV_MIN = "-5" LEV_MAX = "35" LEV_NUM = "9" LEV_DEL = "5" yes? SHADE/L=5/LEV=(($LEV_MIN), ($LEV_MAX), 2) airt yes? SHOW SYM LEV* LEV_TEXT = "(-5, 35, 5)" LEV_MIN = "-5" LEV_MAX = "35" LEV_NUM = "21" LEV_DEL = "2"
6.8.1.2 /COLOR /PEN, /THICKNESS /SIZE, /SIGDIG, /SPACING qualifiers
For contouring, the qualifiers /COLOR /PEN, /THICKNESS/ /SIZE, /SIGDIG, and /SPACING allow simple control over the contours: their color, the size and significant digits in the labels, and the spacing between contours.
CONTOUR/COLOR=
Sets the color of the contour lines. Color can be specified by number as in /PEN=, or with a name. The available names are black, red, green, blue, lightblue, purple, and white
PyFerret Only:
/COLOR=
In PyFerret, the value for the /COLOR= may be specified as a color name or number, as in classic Ferret; or may be of the form (R,G,B) or (R,G,B,A). The values of R, G, B, and A range from zero to 100 and are the percent of red, green, blue, and opacity (alpha channel) for the color. If only R, G, and B are given, an opacity of 100 (opaque) is used. In addition CONTOUR/OPACITY may be used to set the opacity of the contour lines.
CONTOUR/THICKNESS=
The /thickness qualifier sets the line thickness. Its value is 1, 2, or 3
PyFerret Only: CONTOUR/THICKNESS= may take any positive values.
CONTOUR/PEN=
Sets line style for contour lines (same arguments as PLOT/LINE=). Argument can be an integer between 1 and 18; run
GO line_samples to see the styles for color devices.
Example
yes? CONTOUR/PEN=2 sst
CONTOUR/SIZE, CONTOUR/SIGDIG, and CONTOUR/SPACING are alternative implementations of the PPL CONSET command. /SIZE is equivalent to hgt, /SIGDIG is nsig, and /SPACINGis dslab. They make some of the same settings, but in a more convenient way. For details see the CONSET command. The "inches" used in these commands is the PPLUS definition of inches. These are the same units as in, say, "ppl axlen 8,6", to specify plot axes of lengths 8 and 6 inches for horizontal and vertical axes, respectively. They are scaled within the plot window.
Note that to remove the labels from the contour lines, use the fourth argument on the /LEVELS qualifier: CONTOUR/LEVELS=(lo, hi, delta, ndigits), where ndigits is the number of decimal places to use when labeling the level on individual contour lines and we can set ndigit= -3 to omit numerical labels along the contour lines.
CONTOUR/SIZE=
Controls the size of characters in the contour labels; default is 0.08". See the example under CONTOUR/SPACING below.
CONTOUR/SIGDIG=
Sets the number of digits after the decimal point for contour labels; default is 2. See example under CONTOUR/SPACING below.
CONTOUR/SPACING=
Sets spacing for contour labels; default spacing is 5". For fine grids, the labels may not show up. Try specifying smaller values for /SPACING.
Example of CONTOUR/SIZE/SIGDIG/SPACING
yes? LET my_field = SIN(X[x=1:6:.1])*COS(Y[y=1:6:0.1]) yes? CONTOUR/SIGDIG=1/SIZE=0.15/SPACING=3 my_field
Specifies contour labels with a single digit after the decimal point using characters of height 0.15 "inches" at a nominal spacing of 3 "inches", consistent with the PLOT+ usage of "inches".
PyFerret only: The SET TEXT command can customize the style of the numerical labels on the contour lines. The numbers may have a different color than the contours or be set to match it. Use the text-group "contour" to customize contour labels.
yes? set text/font=arial yes? set text/color=red contour yes? contour/color=blue my_var
PPLUS commands can be used to customize contouring settings. Note that Ferret makes settings for all of these automatically; you will only need to make PPLUS calls to change the properties of the plot. See the examples below, and the section on PPLUS graphical commands for more on the syntax to make PPLUS calls.
|
|
|
| Command | Function |
|
CONPRE |
sets prefix for contour labels (usually a font, e.g., "@TR") See also FONTS |
|
CONPST |
sets suffix for contour labels (usually units, e.g., "cm") |
|
CONSET |
controls various aspects of contour labels and curves (see below) |
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.
Examples
! Contour a variable, enlarging the size of the contour label: yes? CONTOUR/SET var yes? PPL CONSET 0.15 yes? PPL CONTOUR
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 the section on CONSET.
nrng This argument has no effect on gridded data. It is documented in the section on CONSET.
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
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_demo
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:
|
FILL |
color-filled contour plot (alias for CONTOUR/FILL) |
|
PAL |
specifies color palette for fill colors |
|
LINE |
specifies that contour lines be overlaid on the filled plot (in lieu of a key) |
|
LEV |
first arg specifies contour levels without numerical labels, next requests solid lines (dashed lines are the default for negative contour values) |
|
PEN |
assigns line style 4 (blue) to contour lines |