Ref Sec32.
/I/J/K/L/M/N /X/Y/Z/T/E/F /D /FRAME /KEY /LEVELS /LINE /NOAXIS /NOKEY /NOLABELS /OVERLAY /PALETTE /PATTERN /SET_UP /TITLE /TRANSPOSE /MODULO /HLIMITS /VLIMITS /AXES /TRIM /HGRATICULE /VGRATICULE /GRATICULE /OPACITY /DEGMINSEC /HALFSPACE
Produces a shaded (rectangular raster) plot of a 2-D field. By default a color key is drawn and contour lines are not drawn.
SHADE[/qualifiers] expression
In a curvilinear coordinate system (map projections)
SHADE [/qualifiers] expression, xcoords, ycoords
Parameters
The expression 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. Multiple expressions are not permitted in a single SHADE command.
Command qualifiers for SHADE:
SHADE/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.
SHADE/D=
Specifies the default data set to be used when evaluating the expression being plotted.
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.
SHADE/FRAME
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).
SHADE/KEY
Displays a color key for the palette used in the shaded plot. By default a key is drawn unless the /LINE or /NOKEY qualifier is specified. 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
SHADE/KEY=CONTINUOUS
Chooses a continous color key for the palette used in a shade plot, without lines separating the colors. This option is particularly good for plots having many levels.
SHADE/KEY=HORIZONTAL
Draws a horizontal key just above a color fill plot.
SHADE/KEY=CENTERLAB
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 equivalent of contour lines between colors.
SHADE/LEVELS
Specifies the SHADE levels or how the levels will be determined. If the /LEVELS qualifier is omitted Ferret automatically selects reasonable SHADE levels.
See the chapter "Customizing Plots", section "Contouring" for examples and more documentation on /LEVELS, and also try the demonstration script custom_contour_demo.jnl.
SHADE/LINE
Overlays contour lines on a shaded plot. When /LINE is specified the color key is omitted unless specifically requested via /KEY. The /SET_UP qualifier disables the action of /LINE. When using /SET_UP,follow the PPL SHADE command with a CONTOUR/OVERLAYcommand to draw contour lines on the plot. In fact, CONTOUR/OVERLAYoffers all the functionality of SHADE/LINE and gives better control overthe plot appearance.
SHADE/NOKEY
Suppresses the drawing of a color key for the palette used in the plot.
SHADE/NOAXIS
Suppresses all axis lines, tics and labeling so that no box appears surrounding the contour plot. This is especially useful for map projection plots.
SHADE/NOLABELS
Suppresses all plot labels.
SHADE/OVERLAY
Causes the indicated shaded plot to be overlaid on the existing plot.
Note (SHADE/OVERLAY with time axes):
Previous to Ferret v6.97, A restriction in PPLUS requires that if time is an axis of the shaded 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 shaded plot 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.
SHADE/PALETTE=
Specifies a color palette (otherwise, a default rainbow palette is used). Try the Unix command % Fpalette '*' to see available palettes. The file suffix *.spk is not necessary when specifying a palette.
Yes? SHADE/PALETTE=land_sea rose
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.
SHADE/PATTERN=
Specifies a pattern file (otherwise, the current default pattern specification is used). 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.
SHADE/SET_UP
Performs all the internal preparations required by program Ferret for a shaded plot 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 SHADE command. This permits plot customizations that are not possible with Ferret command qualifiers. See the chapter "Customizing Plots".
Example: Customize the colorbar key for a shade plot. By default the color key is positioned to the right of the plot, oriented vertically. PPL SHAKEY offers a means to change its location and size, and to customize the labels. Note that the position of the shade key colorbar is in units of inches from the page origin. These commands put the color key at the top of the plot.
Starting with Ferret v6.86, the horizontal color key is located by default so that it minimally interferes with the labels in the upper margin of the plot.
Starting with Ferret v6.93, the color plot commands have a new key option, /KEY=HORIZONTAL which places the color key immediately above the plot.
yes? use coads_climatology yes? shade/title="shakey labels above"/lev=(0,32,1)/set sst[l=1] yes? ppl shakey ,0 yes? ppl shade yes? ppl list shakey ! To make the color key shorter, set some or all of the location arguments to SHAKEY ! If any of the location arguments are left blank, the default values will be used. yes? use coads_climatology yes? shade/title="shakey labels above"/lev=(0,32,1)/set sst[l=1] yes? let x1 = `($ppl$xorg) + 0.4` yes? let x2 = `($ppl$xorg)+($ppl$xlen) - 0.4` yes? let y1 = `($ppl$yorg)+($ppl$ylen)` yes? let y2 = `($ppl$yorg)+($ppl$ylen)+0.2` yes? ppl shakey ,0,,,,,`x1`,`x2`,`y1`,`y2` yes? ppl shade
SHADE/TITLE=
Allows user to specify a plot title (enclosed in quotation marks). Without this qualifier Ferret selects a title based on information about the expression(s).
yes? SHADE/TITLE="title string" expression
SHADE/TRANSPOSE
Causes the horizontal and vertical axes to be interchanged. By default the X axis is drawn horizontally on the plot and the Y and Z axes are drawn vertically. For Y-Z plots the Z data axis is vertical.
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.
SHADE/HLIMITS=
Specifies the horizontal axis range and tic interval (otherwise, Ferret selects reasonable values).
yes? SHADE/HLIMITS=lo:hi:increment
The optional "increment" parameter determines tic mark spacing on the axis. If the increment is negative, the axis will be reversed.
SHADE/VLIMITS=
Specifies the vertical axis range and tic interval. See /HLIMITS (above)
SHADE/XLIMITS=/YLIMITS=
Note: XLIMITS and YLIMITS have been deprecated. Please use HLIMITS and VLIMITS instead.
SHADE/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? SHADE/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? SHADE/AXES=0,1,1,0 sst ! Draws the bottom and left axes only
For curvilinear (3-argument) shade plots only. Beginning with Ferret v5.81 the qualifier /MODULO for SHADE 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? SHADE/HLIMITS=0:360/MODULO values, xcoords, ycoords
SHADE/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? SHADE/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? SHADE/GRAT sst ! default graticules yes? SHADE/GRAT=(LINE,COLOR=red,THICK=3) sst yes? SHADE/GRAT=(DASH,COLOR=lightblue) sst yes? SHADE/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? SHADE/GRAT="LARGE(COLOR=blue,thick),SMALL(COLOR=lightblue)" sst
SHADE/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? SHADE/HGRAT[=line or dash,COLOR=,THICKNESS=] /VGRAT=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? SHADE/HGRAT/VGRAT sst !this is equivalent to PLOT/GRAT yes? SHADE/HGRAT=(LINE,COLOR=red,THIICK=3)/VGRAT=(color=green) sst yes? SHADE/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.
yes? ppl axnmtc 2,2 yes? SHADE/HGRAT="LARGE(COLOR=blue,thick),SMALL(COLOR=lightblue)" /VGRAT="LARGE(COLOR=blue,thick) sst
SHADE/TRIM
Causes the horizontal andvertical axes to be trimmed to the same locations as they are for a FILL or CONTOUR plot. The Contouring algorithm can interpolate only between coordinate locations and so it trims around the edges of the plot area to show only the data that has been filled in. By contrast, the SHADE plot fills each entire grid cell with color. If we want to overlay a FILL or CONTOUR plot over a SHADE plot, the parts of the grid cells around the edges that are not covered by the fill will show, creating an odd effect.
SHADE/TRIM causes Ferret to trim the SHADE plot around the edges to match what FILL or CONTOUR would do.
Example:
yes? SET MODE nlevels 40 yes? USE coads_climatology ! Here is a simple FILL plot yes? FILL/LINE/L=5/X=-50:-20/Y=-65:-25 sst ! A shade plot shows there is more data towards the south ! that is too sparse to be FILLed with the contouring algorithm. yes? pause yes? SHADE/L=5/X=-50:-20/Y=-65:-25 sst ! We could overlay a FILL plot on the SHADE plot to show all ! of the available data yes? pause yes? FILL/LINE/OVER/LEV/NOLAB/L=5/x=-50:-20/y=-65:-25 sst ! But look around the edges of this. Standard SHADE puts color ! out to the edges of the grid cells but FILL cannot extrapolate there. ! SHADE/TRIM shades only to the coordinate locations, matching the ! region where FILL operates, and overlaying FILL shows all the data ! using FILL contours where that is possible yes? pause yes? SHADE/TRIM/L=5/x=-50:-20/y=-65:-25 sst yes? FILL/LINE/OVER/LEV/NOLAB/L=5/X=-50:-20/Y=-65:-25 sst
/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.
SHADE/DEGMINSEC[=n]
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.
SHADE/HALFSPACE
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.