CONTOUR
/I/J/K/L/M/N /X/Y/Z/T/E/F /D /FILL /FRAME /KEY /LEVELS /LINE /NOAXIS /NOKEY /NOLABEL /OVERLAY /PALETTE /PATTERN /SIZE /SPACING /SIGDIG /PEN /SET_UP /TITLE /COLOR /THICKNESS /TRANSPOSE /HLIMITS /VLIMITS /AXES /HGRATICULE /VGRATICULE /GRATICULE /MODULO /DEGMINSEC /HALFSPACE
Produces a contour plot.
yes? CONTOUR[/qualifiers] [expression]
In a curvilinear coordinate system (map projections or curvilinear grids) use a 3-argument contour command
yes? CONTOUR[/qualifiers] expression, xcoords, ycoords
Example:
yes? CONTOUR var1 ! draw a contour plot of variable var1 yes? CONTOUR var1, xcoords, ycoords ! draw a contour plot of variable var1 ! using curvilinear coordinates
For examples in customizing the contour lines, try the script:
yes? go custom_contour_demo
Parameters
Expressions may be any valid expression. See the chapter "Variables and Expressions", section "Expressions" , for a definition of valid expressions. The expression will be inferred from the current context if omitted from the command line.
Command qualifiers for CONTOUR:
CONTOUR/I/J/K/L/M/N /X/Y/Z/T/E/F /OVERLAY /SET_UP /FRAME /D /TRANPOSE /FILL /LINE /NOLABEL /LEVELS /KEY /NOKEY /PALETTE /HLIMITS /VLIMITS /TITLE /COLOR /THICKNESS /NOAXES /PATTERN /SIZE /SPACING /SIGDIG /PEN /AXES /OPACITY
CONTOUR/I/J=/K=/L=/M=/N=/X=/Y=/Z=/T=/E=/F=
Specifies value or range of axis subscripts (I, J, K, L, M, or N), or axis coordinates (X, Y, Z, T, E or F) to be used when evaluating the expression being plotted.
Specifies the default data set to use when evaluating the expression being contoured.
CONTOUR/FILL (alias FILL)
Creates a color filled contour image.
Causes the graphic image produced by the command to be captured as an animation frame in the file specified by SET MOVIE. In general the FRAME command is more flexible and we recommend its use rather than this qualifier. (note that HDF movies are discontinued with Ferret V6.6).
Displays a color key for the palette used in a color-filled contour plot. Only valid in conjunction with /FILL (The key is displayed by default with CONTOUR/FILL or alias FILL). To control the color key position and labeling, see the command SHAKEY in the appendix, Ferret Enhancements to PPLUS). Note in particular that the Ferret Alias command, KEYMARK,1 turns on the annotation of the ends of the key with the minimum and maximum data values from the data that was plotted. KEYMARK,0 turns this capability off.
PyFerret offers an option to customize the text style of the colorbar labels. The text-group "CBAR" specifies a change to the colorbar label text.
/KEY options further customize the key. Multiple options may be given, stringing them together with commas, e.g. /KEY=CONT,HORIZ
Draws a continuous color key for the palette used in a color-filled contour plot, without lines separating the colors. This option is particularly good for fill plots having many levels. Only valid in conjunction with /FILL.
Draws a horizontal key just above a color fill plot. Only valid in conjunction with /FILL.
Labels the color key in the colors of the key rather than at the line dividing one color from the next. The contour levels used, whether specified with a /LEVELS qualifier or computed by Ferret, correspond to the labeled color blocks along the colorbar. In other colorbar styles, the levels correspond to the contour lines between colors.
Only valid in conjunction with /FILL.
Specifies the contour levels or how the levels will be determined. If the /LEVELS qualifier is omitted Ferret automatically selects reasonable contour levels.
See the chapter "Customizing Plots", section "Contouring" for examples and more documentation on /LEVELS and color_thickness indices. See also the demonstration "custom_contour_demo.jnl". Note that individual contour lines or sets of lines within a plot can be given different settings for color and dashed-line drawing using /LEVELS settings.
Overlays contour lines on a color-filled plot. Valid only with /FILL (or as a qualifier to alias FILL). When /LINE is specified the color key, by default, is omitted. Use FILL/LINE/KEY to obtain both contour lines and a color key. The /SET_UP qualifier disables the action of /LINE. When using /SET_UP, follow the PPL CONTOUR (or PPL FILL) command with a CONTOUR/OVERLAY command to draw contour lines on the plot. In fact, CONTOUR/OVERLAY offers all the functionality of FILL/LINE and gives better control over the plot appearance.
Turns off display of a color key for the palette used in a color-filled contour plot. Only valid in conjunction with /FILL (or with alias FILL).
Suppresses all axis lines, tics and labeling so that no box appears surrounding the contour plot. This is especially useful for map projection plots.
Suppresses all plot labels.
Causes the indicated expression to be overlaid on the existing plot.
Note (CONTOUR/OVERLAY with time axes):
Prior to Ferret v6.97, a restriction in PPLUS requires that if time is an axis of the contour plot, the overlaid variable must share the same time axis encoding as the base plot variable. If this condition is not met, you may find that the overlaid contour fails to be drawn. The solution is to use the Ferret regridding capability to regrid the base plot variable and the overlaid plot variable onto the same time axis. In versions after v6.97, this is no longer a problem, and overlays involving 2-D plots with a time axis work correctly.
To overlay symbols or text at particular times on a time plot, See the section on overlaying with a time axis, and the FAQ about locating labels on plots with time axes.
To overlay a time series on a 2-D time plot, see this FAQ.
Specifies a color palette (otherwise, the current default palette is used). Valid only with CONTOUR/FILL (or as a qualifier to the alias FILL). The file suffix *.spk is not necessary when specifying a palette. Try the Unix command % Fpalette '*' to see available palettes. See command PALETTE for more information.
Example:
yes? CONTOUR/FILL/PALETTE=land_sea world_relief
The /PALETTE qualifier changes the current palette for the duration of the plotting command and then restores the previous palette. This behavior is not immediately compatible with the /SET_UP qualifier. See the PALETTE command for further discussion.
Specifies a pattern file (otherwise, the current default pattern specification is used). Valid only with CONTOUR/FILL (or as a qualifier to the alias FILL). The file suffix *.pat is not necessary when specifying a pattern. Try the Unix command % Fpattern '*' to see available patterns. See the PATTERN command for more information.
The Pattern plot style is not available in PyFerret. However pattern-style plots may be drawn using PLOT/VS/OVER and a well-chosen symbol. For instance, in PyFerret, the named symbols such as chevleft, chevright, plustall, and so forth are worth experimenting with.
Example:
yes? use coads_climatology yes? shade /L=1 sst; go fland yes? ! Define a mask to pick out a range of SST between 13 and 19 Deg C yes? let mask_sst = if ( SST[L=1] ge 13.0 and SST[L=1] le 19.0 ) then 1 yes? define lists of points to make a mark at the locations where the mask is 1 yes? let sstteensx = mask_sst * X yes? let sstteensy = mask_sst * Y yes? let ptsx = xsequence(sstteensx) yes? let ptsy = xsequence(sstteensy) yes? plot /over /vs /sym=chevleft /size=0.09 /thick/ nolabel ptsx, ptsy
Sets line color (replaces the /PEN qualifier). The available color names are Black, Red, Green, Blue, LightBlue, and , Purple, and White (not case sensitive), corresponding to the /PEN values 1-6, respectively. (/COLOR also accepts numerical values.)
/THICKNESS takes a value between 1 and 3, so that for instance, /COLOR=RED/THICK=2 is equivalent to the older syntax /PEN=8
Example:
yes? CONTOUR/COLOR=red sst
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.
CONTOUR/COLOR=(100,100,50) temp
/THICKNESS=
In PyFerret, the value given to /THICKNESS may be any positive real number.
/OPACITY=
In PyFerret, the /OPACITY qualifier can be used to specify the opacity (alpha channel value) of the colors used in the plot. The values range from 0 to 100. The opacity given by this option will be used even if a color definition includes an opacity. This may also be set as a fourth argument to the /COLOR qualifier: CONTOUR/COLOR=(RGBA)
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
Controls the size of characters in the contour labels, using PLOT+ definition of "inches" .Default is 0.8' See example under CONTOUR/SPACING below. (See also the PPLUS CONSET command.)
Sets the number of significant digits for contour labels. Default is 2. See example under CONTOUR/SPACING below. (See also the PPLUS CONSET command.)
Sets spacing for contour labels, using PLOT+ definition of "inches". The default spacing is 5.0. This is a nominal value, the algorithm for drawing contour lines sets the actual location of labels. (See also the PPLUS CONSET command.)
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 significant digit using characters of height 0.15 "inches" at a nominal spacing of 3 "inches", consistent with the PLOT+ usage 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.) Note that the PLOT+ CONPRE and CONPST commands are also useful, giving control over the text font and color used in the labels and adding units to the labels. For example, the commands
yes? PPL CONPRE @C002@CR yes? PPL CONPST cm/sec
will transform the labels in the above CONTOUR example to red (002), Complex Roman font with a units label of "cm/sec".
CONTOUR/SET_UP
Performs all the internal preparations required by program Ferret for contouring but does not actually render output. The command PPL can then be used to make changes to the plot prior to producing output with the PPL CONTOUR command. This permits plot customizations that are not possible with Ferret command qualifiers. See the chapter "Customizing Plots", section "Contouring". Please note that /SET_UP disables the /LINE qualifier. When using /SET_UP certain plotting states may have to be reset manually.
Allows user to specify a plot title (enclosed in quotation marks). Without this qualifier Ferret selects a title based on information about the expression.
Causes the horizontal and vertical axes to be interchanged. By default the X and T axes of the data are drawn horizontally on the plot and the Y and Z axes of the data are drawn vertically. For Y-Z plots the Z data axis is vertical by default.
Note that plots in the YT and ZT planes have /TRANSFORM applied by default in order to achieve a horizontal T axis. See /HLIMITS (below) for further details. Use /TRANSPOSE manually to reverse this effect.
Specifies axis range and tic interval for the horizontal axis. Without this qualifier, Ferret selects reasonable values.
yes? CONTOUR/HLIMITS=lo_val:hi_val[:increment] [expression]
The optional "increment" parameter determines tic mark spacing on the axis. If the increment is negative, the axis will be reversed.
This qualifier does not have any impact on the context of the expression being plotted. If data is on a modulo x axis but the arguments of the /HLIMITS qualifier represent a region outside the actual coordinates of the data, only the range including the actual coordinates is shown. Use /X=lo:hi or SET REGION or a context on the variable itself, var[X=lo:hi], to set the context for the expression.
The /HLIMITS and /VLIMITS qualifiers will retain their "horizontal" and "vertical" interpretations in the presence of the /TRANSPOSE qualifier. Thus, the addition of /TRANSPOSE to a plotting command mandates the interchange of "H" and "V" on the limits qualifiers.
Specifies the axis range and tic interval for the vertical axis. See /HLIMITS (above)
CONTOUR/XLIMITS=/YLIMITS=
Note: XLIMITS and YLIMITS have been deprecated. Please use HLIMITS and VLIMITS instead.
CONTOUR/AXES[=top,bottom,left,right]
Turns plotting of individual axes off and on. This replaces the use of the "PPL AXSET" command. The syntax is
yes? CONTOUR/AXES[=top,bottom,left,right] var
where the arguments are 1 to turn the axis on and 0 to turn it off. For example:
yes? CONTOUR/AXES=0,1,1,0 sst ! Draws the bottom and left axes only
Note that contour plots with log axes can be drawn as explained in the FAQ, How can I make a 2D log (or log-log) plot?
Beginning with Ferret v5.81 the argument /MODULO for CONTOUR plots will draw modulo replications in longitude for curvilinear data in order to fill out the specified extent in the longitude direction. For instance, if the xcoords variable contains longitudes in the range -270:90 we can draw a plot with longitudes 0:360 with the command
yes? CONTOUR/HLIMITS=0:360/MODULO values, xcoords, ycoords
CONTOUR/GRATICULE[=line specifiers]
(Introduced in Ferret version 5.6) Turns on graticule lines for the horizontal and vertical axes. These are lines across the plot at the tic marks. /GRATICULE sets both horizontal and vertical lines; to set each separately see /HGRATICULE and /VGRATICULE, below. The syntax is
yes? CONTOUR/GRATICULE[=line or dash,COLOR=,THICKNESS=] var
where the default is a thin, solid black line. The line colors available are Black, Red, Green, Blue, LightBlue, Purple, and White. The thickness codes are 1, 2, or 3 and as for plot lines, thickness=1 is a thin line, thickness=3 is the thickest, and THICK specified with no value defaults to thickness=2. For clarity the arguments to GRAT may be placed in parentheses
yes? CONTOUR/GRAT sst ! default graticules yes? CONTOUR/GRAT=(LINE,COLOR=red,THICK=3) sst yes? CONTOUR/GRAT=(DASH,COLOR=lightblue) sst yes? CONTOUR/FILL/GRAT=(DASH,COLOR=white) sst
The above commands make settings for the large tic marks. If small tic marks are being plotted on the axes, we can make settings for them as well using keywords SMALL and LARGE. Place all of the arguments for the /GRAT qualifier in double quotes. Note that the PPL AXNMTC command sets the plotting of small tics, and that small tics are used by default for many time axes.
yes? ppl axnmtc 2,2 yes? CONTOUR/GRAT="LARGE(COLOR=blue,thick),SMALL(COLOR=lightblue)" sst
CONTOUR/HGRATICULE[=line specifiers]/VGRATICULE[=line specifiers]
Turns on graticule lines and sets the line characteristics of the graticule for the horizontal or vertical axis separately. You may specify only one of /HGRAT or /VGRAT if desired. These are lines across the plot at the tic marks. The syntax is
yes? CONTOUR/HGRATICULE[=line or dash,COLOR=,THICKNESS=] /VGRATICULE=line or dash,COLOR=,THICKNESS=] var
where the default is a thin, solid black line. The line colors available are Black, Red, Green, Blue, LightBlue, Purple, and White. The thickness codes are 1, 2, or 3 and as for plot lines, thickness=1 is a thin line, thickness=3 is the thickest, and THICK specified with no value defaults to thickness=2. For clarity the arguments to HGRAT may be placed in parentheses
yes? CONTOUR/HGRAT/VGRAT sst !this is equivalent to PLOT/GRAT yes? CONTOUR/HGRAT=(LINE,COLOR=red,THIICK=3)/VGRAT=(color=green) sst yes? CONTOUR/HGRAT=(DASH,COLOR=lightblue) sst ! horizontal only
The above commands make settings for the large tic marks. If small tic marks are being plotted on the axes, we can make settings for them as well using keywords SMALL and LARGE. Place all of the arguments for the /HGRAT qualifier in double quotes. Note that the PPL AXNMTC command sets the plotting of small tics, and that small tics are used by default for many time axes. (Note continuation lines in this example, with \ being the continuation character.)
yes? ppl axnmtc 2,2 yes? CONTOUR\ /HGRAT="LARGE(COLOR=blue,thick),SMALL(COLOR=lightblue)"\ /VGRAT="LARGE(COLOR=blue,thick) sst
Label any plot axes that represent longitude or latitude with Degrees-Minutes-Seconds instead of degrees and fractions of degrees. The argument is 1 for Degrees-Minutes (which is the default), or 2 for Degrees-Minutes-Seconds.
For any plot axes that labeled with longitude or latitude units, add a half-space between the degree sign and the E/W or N/S.