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


by Catherine Nunkai — last modified 2015-11-19 12:08

6.8.1 Ferret contour controls

The following qualifiers to the Ferret 2-D graphics commands (CONTOUR, CONTOUR/FILL (alias FILL),  SHADE, and POLYGON) allow customization of a contour plot.

Qualfier Function


(CONTOUR/FILL only) Produces a color-filled contour plot (command FILL is an alias for CONTOUR/FILL)


specifies contour levels, dash patterns, line thickness and color


turns on display of color key for color-filled contour plots (default)


turns off display of color key for color-filled plots


turns off display of X and Y axes (useful for map projections)


adds contour lines to a color-filled plot (lines replace key)


specifies a color palette for color-filled contour plot


sets line style for contour lines (same arguments as PLOT/LINE=. See the section in this chapter, "Text and Line Colors".


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


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.


sets the number of significant digits for contour labels; default is 2


sets the size of characters in the contour labels; default is 0.08


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. /LEVELS qualifier

The /LEVELS qualifier for CONTOUR, SHADE and FILL commands 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=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)



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

/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
-3 to omit numerical labels

Open-ended levels:

(-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:


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


minimum level used; if (-inf) given, then the value of LEV_MIN is the minimum in the data field


maximum level used; if (inf) given, then the value of LEV_MIN is the maximum in the data field


number of levels used


Delta between values, if the levels were uniform, or "irregular"


The argument to the levels qualifier


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.


! basic low,high,delta


! a single level at 5


! suppress numerical contour labels


! approximately 40 automatically selected levels


! approximately 40 automatic levels centered equally about zero


! automatic levels with a delta value of 0.2


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


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


! 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
LEV_MIN = "-5"
LEV_MAX = "35"
LEV_NUM = "9"
LEV_DEL = "5"

yes? SHADE/L=5/LEV=(($LEV_MIN), ($LEV_MAX), 2) airt
LEV_TEXT = "(-5, 35, 5)"
LEV_MIN = "-5"
LEV_MAX = "35"
LEV_NUM = "21"

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.


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:


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.



The /thickness qualifier sets the line thickness.  Its value is 1, 2, or 3


PyFerret Only:

CONTOUR/THICKNESS=  may take any positive values.

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.


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.


Controls the size of characters in the contour labels; default is 0.08". See the example under CONTOUR/SPACING below.


Sets the number of significant digits for contour labels; cefault is 2. See example under CONTOUR/SPACING below.


Sets spacing for contour labels; default spacing is 5".  For fine grids, the labels may not show up. Try specifying smaller values for /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 significant digit 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=ariel
yes? set text/color=red contour
yes? contour/color=blue my_var


6.8.2 PPLUS contour commands

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.



sets prefix for contour labels (usually a font, e.g., "@TR") See also FONTS


sets suffix for contour labels (usually units, e.g., "cm")


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.


! Contour a variable, enlarging the size of the contour label:
yes? CONTOUR/SET var
yes? PPL CONSET 0.15

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? 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:


color-filled contour plot (alias for CONTOUR/FILL)


specifies color palette for fill colors


specifies that contour lines be overlaid on the filled plot (in lieu of a key)


first arg specifies contour levels without numerical labels, next requests solid lines (dashed lines are the default for negative contour values)


assigns line style 4 (blue) to contour lines

Powered by Plone CMS, the Open Source Content Management System

This site conforms to the following standards: