The GCONTOUR Procedure |
Requirements: | A plot request is required. |
Global statements: | AXIS, FOOTNOTE, GOPTIONS, LEGEND, NOTES, PATTERN, SYMBOL, TITLE |
The PLOT statement specifies the three variables to plot. It can also control the contour levels, label the plot lines, and modify the axes as well as the general appearance of the graph. Only one plot request can be specified in a PLOT statement.
To specify multiple plots for a single PROC GCONTOUR statement, use multiple PLOT statements. If a global statement is specified more than once, the last occurrence is applied to all PLOT statements in that PROC step.
The PLOT statement does the following actions:
plots the contour lines as levels using the values of the z variable
scales the axes to include the minimum data values and the maximum values of x and y
generates a labeled legend representing the values of the z variable's contour levels
Global statements enable you to modify the axes, the legend, the contour lines and contour line labels, the fill patterns and pattern colors for contour areas. You can also add titles, footnotes, and notes to the plot. You can use an Annotate data set and set GOPTIONS to enhance the appearance of the plot. Additionally, you can filter your data with a WHERE clause, format your data values, add labels to the variables, and generate multiple plots with a BY statement or multiple plot statements.
PLOT y*x=z </option(s)>; |
option(s) can be one or more options in the following categories:
JOIN | |
LJOIN | |
SMOOTH |
AUTOLABEL | AUTOLABEL=(autolabel-suboptions)
|
catalog entry description options:
Required Arguments |
Options |
Options in a PLOT statement affect all graphs that are produced by that statement. You can specify as many options as you want and list them in any order. If you use a BY statement on the procedure, the options in each PLOT statement affect all graphs produced by that BY statement.
specifies an Annotate data set to enhance the charts produced by the PLOT statement.
Alias: | ANNO= |
Restriction: | Partially supported by Java and ActiveX |
See also: | The GANNO Procedure and Annotate Dictionary |
displays reference lines originating at the major tick marks on the horizontal axis.
Restriction: | Not supported by Java |
labels the contour lines. Autolabel suboptions enable you to control the appearance of these labels.
The label for each contour line is the value of the z variable for that contour level. The labels are displayed in BEST format. The FORMAT statement enables you to change the display format.
You can also use the SYMBOL statement to control the appearance and text of contour labels and lines.
When AUTOLABEL is used with the LLEVELS= option, LLEVELS is ignored.
When AUTOLABEL is used with the CLEVELS= option, AUTOLABEL is ignored.
Featured in: | Labeling Contour Lines, Modifying the Horizontal Axis, Modifying the Legend |
Restriction: | Not supported by Java and ActiveX |
See also: | Autolabel Suboptions |
displays reference lines originating at the major tick marks on the vertical axis.
Restriction: | Not supported by Java |
specifies a color for all the reference lines displayed by the AUTOHREF option. The default color is retrieved from the current style or from the device's color list if the NOGSTYLE option is specified.
Style reference: | Color attribute of the GraphGridLines element |
Restriction: | Not supported by Java |
specifies a color for all the reference lines displayed by the AUTOVREF option. The default color is retrieved from the current style or from the device's color list if the NOGSTYLE option is specified
Restriction: | Not supported by Java |
specifies a color for axis lines, axis tick marks, and the frame around the plot. The default color is retrieved from the current style or from the device's color list if the NOGSTYLE option is specified.
Style reference: | Color attribute of GraphAxisLines element |
Restriction: | Partially supported by Java |
fills the axis area with the specified color. The default color is retrieved from the current style or from the device's color list if the NOGSTYLE option is specified.
Alias: | CFR= |
Style reference: | Color attribute of the GraphWalls element |
specifies a color or colors for reference lines drawn with the HREF= option and the AUTOHREF option as follows:
specifying a single color without parentheses applies that color to all reference lines drawn with the HREF= option and the AUTOHREF option
specifying a single color within parentheses applies the color to the first reference line drawn with the HREF= option only
specifying a list of colors within parentheses applies the colors sequentially to the reference lines drawn with the HREF= option only
The default color is retrieved from the current style or from the device's color list if the NOGSTYLE option is specified.
Alias: | CH= |
Style reference: | ContrastColor attribute of the GraphReference element |
Restriction: | Not supported by Java |
specifies a color or list of colors for the contour levels. GCONTOUR substitutes user-defined colors in the ODS style. If more colors are needed, GCONTOUR uses the next color in the ODS style until all lines have an associated color. The default color is retrieved from the current style or from the device's color list if the NOGSTYLE option is specified.
Style reference: | Color attribute of the GraphData element |
Restriction: | Not supported by Java and partially supported by ActiveX |
specifies a color for outlining filled areas. This option is ignored unless the PATTERN option is also used. COUTLINE=SAME creates a plot with outlines that are the same color as the adjacent fill color.
Note: The outline color is the only distinction between empty patterns. Use of this option makes the patterns look the same when VALUE=EMPTY in PATTERN definitions.
Restriction: | Not supported by Java and ActiveX |
Featured in: | Using Patterns and Joins |
specifies a color for the axis labels, axis tick mark values, legend labels, and legend value descriptions. GCONTOUR uses the first color it finds from the following list:
colors specified for labels and values on assigned AXIS and LEGEND statements.
the color specified by the CTEXT= option in the PLOT statement.
the color specified by the CTEXT= option in a GOPTIONS statement.
the color specified in the current style, or if the NOGSTYLE system option is specified, the default color is the first color in the color list for each device.
The LEGEND statement's VALUE= color is used for legend values, and its LABEL= color is used for legend labels.
The AXIS statement's VALUE= color is used for legend values, and its LABEL= color is used for legend labels. However, if the AXIS statement specifies only general axis colors with its COLOR= option, the CTEXT= color overrides the general COLOR= specification and is used for axis labels and values; the COLOR= color is still used for all other axis colors, such as tick marks.
Note: If you use a BY statement in the procedure, the color of the BY variables' labels is controlled by the CBY= option in the GOPTIONS statement.
Featured in: | Using Patterns and Joins |
specifies a color or colors for reference lines drawn with the VREF= option and the AUTOVREF option as follows:
specifying a single color without parentheses applies that color to all reference lines drawn with the VREF= option and the AUTOVREF option
specifying a single color within parentheses applies the color to the first reference line drawn with the VREF= option only
specifying a list of colors within parentheses applies the colors sequentially to the reference lines drawn with the VREF= option only
Alias: | CV= |
Style reference: | ContrastColor attribute of the GraphReference element |
Restriction: | Not supported by Java |
specifies the description of the catalog entry for the chart. The maximum length for entry-description is 256 characters. This description does not appear on the chart. The GCONTOUR procedure assigns a description of the form PLOT OF y*x=z, where y*x=z is the request specified in the PLOT statement.
Alias: | DES= |
draws reference lines at all major tick marks on both axes. This is the same as specifying both the AUTOHREF and AUTOVREF options.
Restriction: | Not supported by Java |
assigns axis characteristics from the corresponding axis definition to the horizontal x axis. If the AXIS statement specifies the REFLABEL= option, labels are applied in sequence to all reference lines generated with the HREF= option.
Featured in: | Labeling Contour Lines, Modifying the Horizontal Axis, Modifying the Legend |
Restriction: | Partially supported by Java and ActiveX |
See also: | AXIS Statement |
specifies the number of minor tick marks to draw between each major tick mark on the horizontal x axis. The HMINOR= option overrides the MINOR= option in an AXIS definition assigned to the horizontal axis.
Alias: | HM= |
Featured in: | Specifying Contour Levels |
displays up to 100 reference lines originating on the horizontal x axis at specified values within the x axis range. Any values specified beyond the axis range are not drawn, and a warning is issued to the log. To specify labels for this option, use the HAXIS= option. The value-listcan be an explicit list of values, a starting value and an ending value with an interval increment, or a combination of both forms:
n <... n>.
n TO n <BY increment >.
n <... n > TO n <BY increment > n <... n >.
Restriction: | Not supported by Java |
specifies that the order of the values on the horizontal x axis be reversed.
Restriction: | Not supported by Java |
combines adjacent grid cells with the same pattern to form a single pattern area. This option is ignored unless the PATTERN option is also used.
Note: | Java and ActiveX support the JOIN option without the pattern option. |
specifies a line type for reference lines specified by the AUTOHREF option. The reference-line-type value is any integer from 1 to 46. 1 specifies a solid line; values 2 through 46 specify dashed lines.
Default: | 1 (solid) |
Style reference: | LineStyle attribute of the GraphGridLines element |
Restriction: | Not supported by Java |
See also: | Specifying Line Types for available line types |
specifies a line type for reference lines specified by the AUTOVREF option. The reference-line-type value is any integer from 1 to 46. 1 specifies a solid line; values 2 through 46 specify dashed lines.
Style reference: | LineStyle attribute of the GraphGridLines element |
Restriction: | Not supported by Java |
See also: | Specifying Line Types for available line types |
assigns legend characteristics from the corresponding legend definition to the plot's legend. To suppress the legend, use the NOLEGEND option. The LEGEND= option is ignored if the specified LEGEND definition is not currently in effect.
If you use the SHAPE= option in a LEGEND statement, the value LINE is valid. If you use the PATTERN option, SHAPE=BAR is also valid.
Restriction: | Partially supported by Java (always displayed on the right side of plot) and ActiveX |
See also: | LEGEND Statement |
Featured in: | Labeling Contour Lines, Modifying the Horizontal Axis, Modifying the Legend |
specifies up to 100 values for the z variable. Because GCONTOUR uses the z variable to calculate plot contour levels, you can use the LEVELS= option to change the number of contour levels plotted.
The value-list can be an explicit list of values, a starting and an ending value with an interval increment, or a combination of both forms:
If a variable has an associated format, the specified values must be the unformatted values.
The contour lines on the plot represent the intersection of a plane formed by the (x,y) variables, and the surface that is formed by the values of the z variable.
specifies line types for reference lines originating on the horizontal axis. The reference-line-type value is any integer from 1 to 46. 1 specifies a solid line; values 2 through 46 specify dashed lines. When using this option, the following is true:
specifying a single line type without parentheses applies that line type to all reference lines drawn with the HREF= option and the AUTOHREF option
specifying a single line type within parentheses applies the line type to the first reference line drawn with the HREF= option only
specifying a list of line types within parentheses applies the line types sequentially to the reference lines drawn with the HREF= option only
the LAUTOHREF= option overrides the LHREF= (reference-line-type) for lines drawn with the AUTOHREF option
Alias: | LH= |
Style reference: | LineStyle attribute of the GraphReference element |
Restriction: | Not supported by Java and partially supported by ActiveX |
See also: | Specifying Line Types for available line types |
displays filled contour areas with contour lines.
Restriction: | Supported by Java and ActiveX only |
lists line types for plot contour lines. Each line type represents one contour level. If fewer line types are specified than the number of levels in the plot, GCONTOUR provides additional line types. Valid values for line-type-list are integers from 1 to 46. 1 specifies a solid line; values 2 through 46 specify dashed lines.
Default: | 1 (solid) |
Restriction: | Not supported by Java and partially supported by ActiveX |
See also: | Specifying Line Types for the line types represented by each number. |
Featured in: | Specifying Contour Levels. |
specifies line types for reference lines originating on the vertical axis. Valid values for line-type-list are integers from 1 to 46. 1 specifies a solid line; values 2 through 46 specify dashed lines. When using this option the following is true:
specifying a single line type without parentheses applies that line type to all reference lines drawn with the VREF= option and the AUTOVREF option
specifying a single line type within parentheses applies the line type to the first reference line drawn with the VREF= option only
specifying a list of line types within parentheses applies the line types sequentially to the reference lines drawn with the VREF= option only
the LAUTOVREF= option overrides the LVREF= (reference-line-type) for lines drawn with the AUTOVREF option
Alias: | LV= |
Style reference: | LineStyle attribute of the GraphReference element |
Restriction: | Partially supported by Java and ActiveX |
See also: | Specifying Line Types for the line types represented by each number |
specifies the name of the GRSEG catalog entry and the name of the graphics output file, if one is created. The name can be up to 256 characters long, but the GRSEG name is truncated to eight characters. Uppercase characters are converted to lowercase. Periods are converted to underscores. If you specify DEVICE=ACTIXIMG or DEVICE=JAVAIMG, then the name that you specify is used for the graphics output file even if the file exists. If the name duplicates an existing GRSEG name, then SAS/GRAPH adds a number to the name to create a unique entry name--for example, GCONTOU1.
Default: | GCONTOUR |
See also: | About Filename Indexing |
Featured in: | Specifying Contour Levels |
specifies the number of contour levels to plot. Valid values are integers from 1 to 100.
Restriction | Partially supported by Java and ActiveX |
Featured in: | Specifying Contour Levels |
specifies that a plot have no axis values, axis labels, or axis tick marks. The frame is displayed around the plot unless you use the NOFRAME option.
Alias: | NOAXES |
Restriction | Partially supported by Java |
suppresses the frame that is drawn around the plot area.
Restriction: | Not supported by Java |
suppresses the legend that describes the plot by displaying the z variable name or label, the legend values, and legend value descriptions.
Default: | LEGEND |
specifies that the plot contour levels are represented by rectangles filled with patterns. The pattern for each rectangle is determined by calculating the mean of the values of the z variable for the four corners of the rectangle and assigning the pattern for the level closest to the mean.
To explicitly define patterns, use PATTERN definitions for map or plot patterns.
Featured in: | Using Patterns and Joins |
See also: | PATTERN Statement |
produces smooth gradient areas between levels.
Restriction: | Supported by Java and ActiveX only |
assigns axis characteristics from the corresponding axis definition to the vertical yaxis. If the AXIS statement specifies the REFLABEL= option, labels are applied in sequence to all reference lines generated with the VREF= option.
Restriction: | Partially supported by Java and ActiveX |
See also: | AXIS Statement |
Featured in: | Specifying Contour Levels |
specifies the number of minor tick marks located between each major tick mark on the vertical y axis. Value labels are not displayed for minor tick marks. The VMINOR= option overrides the MINOR= option in an AXIS definition that is assigned to the vertical axis.
Alias: | VM= |
Featured in: | Specifying Contour Levels |
displays up to 100 reference lines originating on the vertical y axis at specified values within the y axis range. Any values specified beyond the axis range are not drawn, and a warning is issued to the log. To specify labels for these reference lines, use the VAXIS= option. The value-listcan be an explicit list of values, a starting value and an ending value with an interval increment, or a combination of both forms:
n <... n>.
n TO n <BY increment >.
n <... n > TO n <BY increment > n <... n >.
Restriction: | Not supported by Java |
specifies that the order of the values on the vertical axis be reversed.
Restriction | Not supported by Java |
specifies a line width for reference lines specified by the AUTOHREF option. The reference-line-width can be any number greater than zero, and does not need to be an integer.
Default: | Current style setting, 1 if NOGSTYLE |
Style reference: | LineThickness attribute of the GraphGridLines element |
Restriction: | Not supported by Java and ActiveX |
specifies a line width for reference lines specified by the AUTOVREF option. The reference-line-widthcan be any number greater than zero, and does not need to be an integer.
Default: | Current style setting, 1 if NOGSTYLE |
Style reference: | LineThickness attribute of the GraphGridLines element |
Restriction: | Not supported by Java and ActiveX |
specifies a line width for reference lines specified by the HREF= option. The reference-line-width can be any number greater than zero, and does not need to be an integer.
Default: | Current style setting, 1 if NOGSTYLE |
Style reference: | LineThickness attribute of the GraphReference element |
Restriction: | Not supported by Java and ActiveX |
specifies a line width for reference lines specified by the VREF= option. The reference-line-width can be any number greater than zero, and does not need to be an integer.
Default: | Current style setting, 1 if NOGSTYLE |
Style reference: | LineThickness attribute of the GraphReference element |
Restrictions: | Not supported by Java and ActiveX |
specifies the number of major tick marks on the horizontal x axis. The value of number-of-major-tick-marks must be greater than or equal to 2. The MAJOR= and ORDER= options in an AXIS definition that is assigned to the horizontal x axis overrides the XTICKNUM= option.
specifies the number of major tick marks on the vertical y axis. The value of number-of-major-tick-marks must be greater than or equal to 2. The MAJOR= and ORDER= options in an AXIS definition that is assigned to the vertical y axis overrides the YTICKNUM= option.
Autolabel Suboptions |
The AUTOLABEL= option accepts the following autolabel suboptions.
specifies a collision checking factor that controls collisions between contour label text and other contour lines or other labels. Values can be integers from 0 to 100, inclusive, where 0 provides minimal collision checking and 100 provides maximal collision checking. Fractional values are permitted.
CHECK=NONE suppresses contour label collision checking and can lessen the time needed to compute the contour plot.
Default: | 75 |
specifies the maximum amount of the contour line that can be hidden by contour labels. The value of amountmust be greater than zero.
Valid units are CELLS (horizontal character cell positions), CM (centimeters), IN (inches), or PCT (percentage of the width of the graphics output area). If you omit units , a unit specification is searched for in this order:
For units that you specify as PCT or CELLS, the MAXHIDE= suboption calculates the amount of contour line that can be hidden based on the width of the graphics output area. For example, if you specify MAXHIDE=50 PCT, and if the graphics output area is 9 inches wide, the maximum amount of the contour line that can be hidden by labels is 4.5 inches.
This option maintains data integrity. It provides a check for overly small increments in the STEP= option in the SYMBOL statement. Additionally, the MAXHIDE= option can prevent small contours from being significantly hidden even when the value of the STEP= option is sufficiently large.
Default: | MAXHIDE=100 |
specifies that the contour lines are visible through the label text as dashed lines. Line style 33 is used. This option provides a simple way to see all portions of labeled contours, and can be used to inspect the label positions with respect to the contour lines. The REVEAL option is primarily used for debugging. Occasionally, single-character contour labels can be placed off center from the clipped portion of the contour line when the contour line is irregular or jagged.
specifies the maximum angle (the tolerance angle) between any two adjacent characters of a contour label. The value of angle must be between 1 and 85 degrees. To force contour labels to fall on very smooth sections, specify a small tolerance angle.
Default: | 30 |
Selecting Contour Levels |
The LEVEL= option enables you to customize your plot, by specifying values for the contour levels.
The LEVELS= option represents the z variable values as a third dimension, using uniquely colored contour lines.
Using the PATTERN option with the LEVELS= option generates a plot with contour levels that are displayed as solid filled rectangles. The rectangles are formed by points in the (x, y)grid. The contour pattern of a rectangle, or grid cell, is determined by average value of the z variable for the four corners of the rectangle. The grid cell is assigned the pattern for the level closest to the calculated mean. For example, if you have specified contour levels of 0, 5, and 10, and the plot contains a grid cell with a mean of 100, it is assigned the pattern for the nearest level: 10. A grid cell with a mean of 7.6 is also assigned the pattern for the 10 level. The same data used with the following PLOT statement in the GCONTOUR procedure produces a similar contour plot:
plot y*x=z / levels=-7.5 to 7.5 by 2.5/ pattern; run;
The following contour plot with the PATTERN option uses the same data and contour levels as Using Patterns and Joins. Contour plots using the same contour levels can present your data differently, if one plot uses a pattern and the other does not. The contour pattern boundaries do not correspond to the contour lines shown in Using Patterns and Joins.
Contour Plot with the PATTERN Option
Using the data to create a surface plot with the G3D procedure, the contour lines in a GCONTOUR procedure plot represent the intersection of the plane and the surface.
For example, suppose that you use the G3D procedure, and your data produces a surface plot like the one shown below.
The contour lines represent the intersection of the surface lines with the plane parallel to the plane formed by the variables x and y and located at z values of -7.5, -5.0, -2.5, and so on.
Specifying Axis Order |
You can use AXIS statements to modify the text and appearance of plot axes, and then you can assign the axes to the contour plot with the PLOT statement's HAXIS= and VAXIS= options. If the AXIS statement uses an ORDER= option, there are special considerations for using that AXIS definition with the GCONTOUR procedure.
A list of variable values that are specified with the AXIS statement's ORDER= option must contain numbers listed in ascending or descending order; these numbers are treated as a continuous data range for an axis. Thus, for a contour line or pattern to span the entire specified range, it is not necessary for the maximum and minimum values of the list to match exactly with the maximum and minimum data values of the corresponding x or y variable. For example, suppose that you assign this AXIS definition to the horizontal (x) axis:
axis1 order=-2.5 to 2.5 by .5
Suppose also that the horizontal axis variable has these values: -5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5. Depending on the data, contours could extend through the full range of the ORDER= list rather than from -2 to 2, which are the actual values of the variable assigned to the horizontal (x) axis. In this case, values are interpolated for the x variable at any point where the y variable intersects the minimum axis value (-2.5) or the maximum axis value (2.5). Data values that are outside of the axis range (in this case, -5, -4, -3, 3, 4, and 5) are clipped from the plot.
When ORDER= lists cause data clipping, internal plotting grids are modified according to these rules:
If an ORDER= list causes data clipping on a single axis, linear interpolation generates the z values of the starting or ending column, or both columns of the plotting grid. For example, in the previous example, the value of z is interpolated for -2.5 and 2.5 on the horizontal (x) axis.
If ORDER= lists cause data clipping on both axes, the response variable values of the new corners are derived by fitting the new x, y location on a plane formed by three of the original four points of the corresponding grid square.
When assigning the following AXIS definition to a plot of the same data, the contour levels on the plot do not extend beyond the range of the data:
axis1 order=-10 to 10 by 1;
The ORDER= option, values match the range of the data values
The ORDER= option, values clip the range of data values
The ORDER= option, values extend beyond the range of the data values
Modifying Contour Lines and Labels with the SYMBOL Statement |
When you use the AUTOLABEL option, the LLEVELS= and CLEVELS= options are ignored, and contour-line and label attributes are controlled by the SYMBOL statement. Defaults are used if not enough SYMBOL statements are specified to match the number of contour levels.
If a SYMBOL statement does not include a color option, the SYMBOL statement can be applied to more than one contour level. In this case, the SYMBOL statement is used once with every color in the color list and generates more than one SYMBOL definition. See SYMBOL Statement for details.
The Effect of SYMBOL Statement Options on Contour Lines and Labels describes how SYMBOL statement options affect contour plot lines and labels.
SYMBOL Statement Option | Contour Line or Label Element Affected |
---|---|
LINE=line-type | Contour line style |
WIDTH=n | Contour line thickness |
CI=line-color or COLOR=color | Contour line color |
FONT=font | Contour label font |
HEIGHT=height | Contour label height |
CV=color or COLOR=color | Contour label color |
STEP=distance<units> | Minimum distance between labels on the same contour line |
VALUE='text' | Contour label text |
VALUE=NONE | Suppresses the contour label text |
The SYMBOL statement option INTERPOL= is not supported by the GCONTOUR procedure.
The STEP= option specifies the minimum distance between contour labels. The lower the value, the more labels the procedure uses. A STEP= value of less than 10 percent is ignored by the GCONTOUR procedure and a value of 10 percent is substituted.
For more information, see SYMBOL Statement.
To override the default labels that are displayed by the AUTOLABEL option, you can specify label text for one or more contour lines. To do so, use both the FONT= and VALUE= options on the SYMBOL statement that is assigned to the contour level. Default labels are used for contour levels that you do not label.
For example, this SYMBOL1 statement displays the text string DEEP in the Arial font on the contour line that it modifies:
symbol1 font="Arial Rounded MT Bold" value="DEEP";
You must specify both FONT= and VALUE= options or the text is not used. For an example, see Labeling Contour Lines, Modifying the Horizontal Axis, Modifying the Legend.
Copyright © 2010 by SAS Institute Inc., Cary, NC, USA. All rights reserved.