GCHART Procedure

STAR Statement

Creates star charts in which the length of the spines represents the value of the chart statistic for each category of data or midpoint.
Restriction: Not supported by Java and ActiveX
Requirement: At least one chart variable is required.
Global statements: FOOTNOTE, PATTERN, TITLE
Supports: Drill-down functionality (slices only)

Syntax

STAR chart-variable(s) </ options>;

Summary of Optional Arguments

Appearance options
starts the first slice at the specified angle.
specifies a data set to annotate all graphs that are produced by the GCHART procedure.
arranges the bars in ascending order of the value of the chart statistic.
specifies one color for all slices in the chart, regardless of whether the fill is solid or hatch.
specifies the color for the circle that surrounds the star chart and for the slice outlines or spines.
arranges the bars in descending order of the value of the chart statistic.
specifies the fill pattern for all slices in the star chart.
assigns the specified LEGEND definition to the legend generated by the SUBGROUP= option.
draws only star spines without connecting lines.
suppresses the legend automatically generated by the SUBGROUP= option.
scales the chart so that the outside (or edge) of the circle represents the value that is specified by max-value.
scales the chart so that the center of the circle represents the value that is specified by min-value.
specifies the width of the outline in pixels.
Catalog entry description options
specifies a description of the output.
specifies the name of the GRSEG catalog entry and the name of the graphics output file, if one is created.
Grouping options
draws number-of-columns stars across the procedure output area.
draws number-of-rows stars vertically in the procedure output area.
organizes the data according to values of group-variable and produces a separate star chart for each unique value of group-variable.
Labeling options
specifies a color for all text on the axes and legend.
uses the slice pattern color for all slice labels.
suppresses the headings normally printed above each star when you use the GROUP= option.
suppresses the heading normally printed at the top of each page or display of star chart output.
prints the percentage represented by each slice using the specified labeling method.
controls the position and style of the slice name (midpoint value) for each slice.
controls the position and style of the slice value (chart statistic) for each slice.
Midpoint options
treats a numeric chart variable as a discrete variable rather than as a continuous variable.
specifies number of midpoints to be graphed for a chart variable.
generates default midpoints using the Nelder algorithm (Applied Statistics 25:94–7, 1976).
specifies the midpoint values for the slices.
accepts a missing value as a valid midpoint for the chart variable.
ODS options
identifies the variable in the input data set whose values create links.
identifies the variable in the input data set whose values create links or data tips or both.
specifies a character variable whose values are URLs.
Statistic options
specifies a variable whose values weight the contribution of each observation in the computation of the chart statistic.
specifies a numeric variable for sum or mean calculations.
specifies the chart statistic.

Required Argument

chart-variable(s)
specifies one or more variables that define the categories of data to chart. Each chart variable draws a separate chart. All variables must be in the input data set. Separate multiple chart variables with blanks.

Optional Arguments

Options in a STAR statement affect all of the graphs that are produced by that statement. You can specify as many options as you want and list them in any order. For details about specifying colors, see Using Colors in SAS/GRAPH Programs.

ACROSS=number-of-columns
draws number-of-columns stars across the procedure output area. The ACROSS= option is ignored unless you also use the GROUP= option. If number-of-columns calls for more stars than fit horizontally in the graphics area of the output device, no stars are drawn and an error message is written to the SAS log.
If you also use the DOWN= option, the star charts are drawn in left-to-right and top-to-bottom order.
ANGLE=degrees
starts the first slice at the specified angle. A value of 0 for degrees corresponds to the three o'clock position. Degrees can be either positive or negative. Positive values move the starting position counterclockwise; negative values move the starting position clockwise.
If the star chart uses spines instead of slices, degrees specifies the angle of the position halfway between the first spine and the last spine.
By default, ANGLE=0, which places the first spine or the center of the first slice of the star at the 0 degree position. Successive star spines or slices are drawn counterclockwise from the starting position.
ANNOTATE=Annotate-data-set
specifies a data set to annotate all graphs that are produced by the GCHART procedure. To annotate individual graphs, use the ANNOTATE= option in the action statement.
Alias:ANNO=
Note:Annotate coordinate systems 1, 2, 7, and 8 (data system coordinates) are not valid with block, pie, donut, or star charts.
ASCENDING
arranges the bars in ascending order of the value of the chart statistic. By default, bars are arranged in ascending order of midpoint value, without regard to the lengths of the bars. ASCENDING reorders the bars from shortest to longest. In horizontal bar charts the ordering is top to bottom; in vertical bar charts the ordering is left to right.
Interactions:If you also use the GROUP= option, the reordering is performed separately for each group, so the order of the midpoints might be different for each group.

The ASCENDING option overrides any midpoint order specified with the MIDPOINTS= option or specified in the ORDER= option in an AXIS statement assigned to the midpoint axis.

CFILL=fill-color
specifies one color for all slices in the chart, regardless of whether the fill is solid or hatch. For the PIE and DONUT statements, it is possible that no pattern is specified in the pattern statement or with the FILL= option. In this case the procedure starts with the default solid fill and then, beginning with P2N0, uses each default pie hatch pattern with the specified color. For the outline color, the procedure uses the default color, which is retrieved from the current style. However, if the NOGSTYLE option is specified, the procedure uses the first color in the device's color list. Use the COUTLINE= option to specify a different outline color. The CFILL= option overrides any other pattern color specification and controls the color of all slices.
Style reference:Color attribute of the GraphData1 element
COUTLINE=star-outline-color | SAME
specifies the color for the circle that surrounds the star chart and for the slice outlines or spines. SAME specifies that the outline color of a slice is the same as the interior pattern color. Specifying COUTLINE=SAME affects only slice outlines and has no effect on the color of the circle.
The default circle and outline color are both specified in the current style. However, if the NOGSTYLE option is specified, then the default circle color is the first color in the device's color list (the foreground color). In addition, the default slice outline color is determined as follows:
  • If you do not specify a PATTERN statement, the default outline color is the color defined in the current style.
  • If you specify the NOGSTYLE option and no PATTERN statement, the default outline color is black for the Java or ActiveX devices. Otherwise, the default outline color is the foreground color. If you specify an EMPTY PATTERN statement, then the default outline color is the same as the fill color.
Style reference:Color attribute of the GraphOutlines element

About Patterns

CTEXT=text-color
specifies a color for all text on the axes and legend. This includes axis labels, tick mark values, legend labels, and legend value descriptions. The GCHART procedure looks for the text color in the following order:
  1. colors specified for labels and values on assigned AXIS and LEGEND statements, which override the CTEXT= option specified in the STAR statement.
  2. the color specified by the CTEXT= option in the STAR statement.
  3. the color specified by the CTEXT= option in a GOPTIONS statement.
  4. the color specified in the current style. Or, if the NOGSTYLE option is specified, then the default color is black for the Java and ActiveX devices and the first color in the color list for all other devices.
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 axis values, and its LABEL= color is used for axis 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.
Style reference:Color attributes for the GraphLabelText and the GraphValueText elements
Note:If you use a BY statement in the procedure, the color of the BY variable labels is controlled by the CBY= option in the GOPTIONS statement.
DESCENDING
arranges the bars in descending order of the value of the chart statistic. By default, bars are arranged in ascending order of midpoint value, without regard to the lengths of the bars. DESCENDING reorders the bars from longest to shortest. In horizontal bar charts the ordering is top to bottom; in vertical bar charts the ordering is left to right. If you also use the GROUP= option, the reordering is performed separately for each group, so the order of the midpoints might be different for each group.
The DESCENDING option overrides any midpoint order that is specified either with the MIDPOINTS= option or the ORDER= option in an AXIS statement assigned to the midpoint axis.
DESCRIPTION=“description
specifies a description of the output. The maximum length for description is 256 characters. The description does not appear in the output. The descriptive text is shown in each of the following:
  • the chart description for Web output (depending on the device driver). See Chart Descriptions for Web Presentations for more information.
  • the Table of Contents that is generated when you use the CONTENTS= option on an ODS HTML statement, assuming that the output is generated while the contents page is open.
  • the description and the properties for the output in the Results window.
  • the description and properties for the catalog entry in the SAS Explorer.
  • the Description field of the PROC GREPLAY window.
The description can include the #BYLINE, #BYVAL, and #BYVAR substitution options, which work as they do when used on TITLE, FOOTNOTE, and NOTE statements. Refer to Substituting BY Line Values in a Text String. The 256-character limit applies before the substitution takes place for these options. Thus, if in the SAS program the description text exceeds 256 characters, it is truncated to 256 characters, and then the substitution is performed.
Alias:DES=
Default:STAR CHART OF chart-variable
DISCRETE
treats a numeric chart variable as a discrete variable rather than as a continuous variable. The GCHART procedure creates a separate midpoint and, hence, a separate star slice for each unique value of the chart variable. If the variable has a format associated with it, each format value is treated as a separate value.
The LEVELS=number-of-midpoints option is ignored when you use the DISCRETE option. The MIDPOINTS= option overrides the DISCRETE option.
DOWN=number-of-rows
draws number-of-rows stars vertically in the procedure output area. The DOWN= option is ignored unless you also use the GROUP= option. If number-of-rows calls for more stars than fit vertically in the graphics area of the output device, no stars are drawn and an error message is written to the SAS log.
If you also use the ACROSS= option, the stars are drawn in left-to-right and top-to-bottom order.
FILL=SOLID | X
specifies the fill pattern for all slices in the star chart:
SOLID
rotates a solid fill through the list of colors available in the default style as many times as necessary. SOLID is the default.
Alias:S
X
rotates a single hatch pattern through the list of colors defined in the current style. If the NOGSTYLE option is specified, it rotates the hatch pattern through the device color list as many times as necessary. If you do not specify the colors= goption, the fill skips the first color in the color list.
FILL= overrides any pattern that is specified in PATTERN statements.
By default, the outline color is the color defined by the current style. If the NOGSTYLE option is specified, the outline color is the first color in the device's color list. If PATTERN statements are used to specify colors, the slice outline color matches the slice fill color.
If any PATTERN statements have been defined, the colors in the PATTERN definitions are used, in order, before the default style color rotation.
Style reference:Color attribute of the GraphData1 element
FREQ=numeric-variable
specifies a variable whose values weight the contribution of each observation in the computation of the chart statistic. Each observation is counted the number of times that are specified by the value of numeric-variable for that observation. If the value of numeric-variable is missing, 0, or negative, the observation is not used in the statistic calculation. Non-integer values of numeric-variable are truncated to integers.
The FREQ= option is valid with all chart statistics.
Because you cannot use TYPE=PERCENT or TYPE=FREQ with the SUMVAR= option, you must use FREQ= to calculate percentages and frequencies based on a sum.
The statistics are not affected by applying a format to numeric-variable.
GROUP=variable
organizes the data according to values of group-variable and produces a separate star chart for each unique value of group-variable. Group-variable can be either character or numeric and is always treated as a discrete variable. Missing values for group-variable are treated as a valid group.
By default, the charts are produced in ascending order of group variable value and each is drawn on a separate page or display. Therefore, the effect of GROUP= is essentially the same as using a BY statement. The exception is that GROUP= causes the midpoints with the same value to use the same color and fill pattern. To place more than one star chart on a page or display, use the ACROSS= or DOWN= options, or both.
HTML=variable
identifies the variable in the input data set whose values create links or data tips or both. The variable values are either links or data tips or both that are created in the HTML file generated by the ODS statement. The links are URLs pointing to Web pages to display when the user clicks (drills down) on elements in the graph. Data tips are detailed information or data values that are displayed as pop-up text when a mouse pointer is positioned over elements in the graph.
Restriction:Not supported by Java or ActiveX
HTML_LEGEND=variable
identifies the variable in the input data set whose values create links. Input data set variable values create links that are associated with a legend value and point to the URL to display when the user clicks (drills down) on the value.
Restriction: Only star charts with slices support drill-down functionality
LEGEND=LEGEND<1...99>
assigns the specified LEGEND definition to the legend generated by the SUBGROUP= option. The LEGEND= option itself does not generate a legend.
The LEGEND= option is ignored if any of the following are true:
  • The SUBGROUP= option is not used.
  • The specified LEGEND definition is not in effect.
  • The NOLEGEND option is used.
  • The PATTERNID= option is set to any value other than SUBGROUP. That is, the value of PATTERNID= is BY or GROUP or MIDPOINT.
To create a legend based on the chart midpoints instead of the subgroups, use the chart variable as the subgroup variable:
block city / subgroup=city;
Restriction:The Java and ActiveX devices do not support all LEGEND statement options.
See: the LEGEND Statement for more information

SUBGROUP=subgroup-variable

LEVELS=number-of-midpoints | ALL
specifies number of midpoints to be graphed for a chart variable. After you specify the number of midpoints that you want, the range for each numeric midpoint is calculated automatically using the algorithm described in Terrell and Scott (1985). If you specify LEVELS=ALL, then all unique numeric or character midpoint values are graphed. If your data contains a large number of unique midpoint values (more than 200), then you can use the XPIXELS and YPIXELS GOPTIONS. This enables the device driver to render a larger (and more readable) graph. The LEVELS=number-of-midpoints option is ignored if any of the following are true:
  • The chart variable is character type.
  • The DISCRETE option is used.
  • The MIDPOINTS= option is used.
MATCHCOLOR
uses the slice pattern color for all slice labels. MATCHCOLOR overrides the color that is specified in the CTEXT= option. If the chart uses spines instead of slices, the spine color is used for the slice label and value text.
MIDPOINTS=value-list
specifies the midpoint values for the slices. The way you specify value-list depends on the type of variable:
  • For numeric chart variables, value-list is either an explicit list of values, or a starting 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>>
    If a numeric variable has an associated format, the specified values must be the unformatted values.
    If you omit the DISCRETE option, then numeric values are treated as continuous, which means that the following is true by default:
    • The lowest midpoint consolidates all data points from negative infinity to the median of the first two midpoints.
    • The highest midpoint consolidates all data points from the median of the last two midpoints up to infinity.
    • All other values in value-list specify the median of a range of values, and the GCHART procedure calculates the midpoint values.
    If you include the DISCRETE option, each value in value-list specifies a unique numeric value.
  • For character chart variables, value-list is a list of unique character values enclosed in quotation marks and separated by blanks:
    'value-1' <...'value-n'>
    If a character variable has an associated format, the specified values must be the formatted values.
For a complete description of value-list, see the value-list in the AXIS statement.
MIDPOINTS=OLD
generates default midpoints using the Nelder algorithm (Applied Statistics 25:94–7, 1976). The MIDPOINTS=OLD option is ignored unless the chart variable is numeric
MISSING
accepts a missing value as a valid midpoint for the chart variable. By default, observations with a missing value are ignored. Missing values are always valid for the group variable.
NAME='entry-name'
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, and periods are converted to underscores. The default name is GCHART. If the name duplicates an existing name, then SAS/GRAPH adds a number to the name to create a unique name (for example, GCHART1).
If the name specified is exactly eight characters long, then the last character of the image output filename is replaced with a number. For example, myimages is changed to myimage1.
NOCONNECT
draws only star spines without connecting lines. By default, the spines are connected to form slices.
NOGROUPHEADING
suppresses the headings normally printed above each star when you use the GROUP= option.
NOHEADING
suppresses the heading normally printed at the top of each page or display of star chart output.
NOLEGEND
suppresses the legend automatically generated by the SUBGROUP= option. The NOLEGEND option is ignored if the SUBGROUP= option is not used.
PERCENT=ARROW | INSIDE | NONE | OUTSIDE
prints the percentage represented by each slice using the specified labeling method. For a description of the option values see Selecting and Positioning Spine and Slice Labels. By default, PERCENT=NONE (percentage is not displayed).
SLICE=ARROW | INSIDE | NONE | OUTSIDE
controls the position and style of the slice name (midpoint value) for each slice. For a description of the option values, see Selecting and Positioning Spine and Slice Labels. By default, SLICE=OUTSIDE (the name is outside the slice).
STARMAX=max-value
scales the chart so that the outside (or edge) of the circle represents the value that is specified by max-value. By default, the value for STARMAX= is the maximum chart statistic value.
STARMIN=min-value
scales the chart so that the center of the circle represents the value that is specified by min-value. By default, STARMIN=0. If the chart statistic has negative values, by default the value for the STARMIN= option is the minimum chart statistic value.
SUMVAR=numeric-variable
specifies a numeric variable for sum or mean calculations. The GCHART procedure calculates the sum or, if requested, the mean of the value of numeric-variable for each midpoint. The resulting statistics are represented by the size of the slice and displayed beside each slice.
When you use the SUMVAR= option, the TYPE= option must be either SUM or MEAN. With the SUMVAR= option, the default is TYPE=SUM.
TYPE=statistic
specifies the chart statistic.
  • If the SUMVAR= option is not used, statistic can be one of the following:
    FREQ
    frequency (the default)
    PERCENT PCT
    percentage
    If the SUMVAR= option is used, statistic can be one of the following:
    SUM
    sum (the default)
    MEAN
    mean
Because you cannot use TYPE=FREQ or TYPE=PERCENT with the SUMVAR= option, you must use FREQ= to calculate percentages or frequencies based on a sum.
URL=character-variable
specifies a character variable whose values are URLs. The variable values are URLs for Web pages to display when the user clicks (drills down) on elements in the graph.
Restrictions: This option affects graphics output that is created through the ODS HTML destination only.

Not supported by Java or ActiveX

Interaction:If you specify both the HTML= and the URL= options, then the URL= option is ignored

Example: GIF Output with Drill-Down Links

VALUE=ARROW | INSIDE | NONE | OUTSIDE
controls the position and style of the slice value (chart statistic) for each slice.
Default:VALUE=OUTSIDE (the value is outside of the slice)
See:Selecting and Positioning Spine and Slice Labels for a description of the option values
WOUTLINE=slice-outline-width
specifies the width of the outline in pixels. The WOUTLINE= option affects the slice outlines.
Style reference:LineThickness attribute of the GraphOutlines element

Details

Description

The STAR statement specifies the variable or variables that define the categories of data to chart. This statement automatically does the following:
  • determines the midpoints.
  • calculates the chart statistic for each midpoint (the default is FREQ).
  • scales each spine or slice to represent the chart statistic. Slices or spines are drawn for all midpoints where the value of the chart statistic is greater than the value that is specified in the STARMIN= option.
  • arranges the spines or slice counterclockwise around the star in ascending order of midpoint value, starting at the three o'clock position.
  • prints the midpoint value and chart statistic beside each spine or slice.
  • assigns patterns to the slices.
If all the data to be charted with the STAR statement are positive, the center of the star represents 0 and the outside circle represents the maximum value. If negative values are calculated for the chart statistic, the center represents the minimum value in the data. You can specify other values for the center and outside of the circle with the STARMIN= and STARMAX= options.
You can also use statement options to
  • select or order the midpoints
  • change the type of chart statistic
  • modify the appearance of the chart. This includes the content and position of the spine or slice labels, and patterns that fill the slice.
You can specify additional variables by which to group or sum the data.
Star charts allow grouping, which creates two or more separate charts that are displayed in rows or columns on one graph.
In addition, you can use global statements to modify patterns as well as add titles, footnotes, and notes to the chart. You can also use an Annotate data set to enhance the chart.

Selecting and Positioning Spine and Slice Labels

By default, each spine or slice is labeled with its midpoint value and its chart statistic value, which are printed outside of the circle. You can control where and how these labels are displayed with the SLICE= and VALUE= options, respectively. In addition, each spine can display the percentage that its midpoint contributes to the total chart statistic (spine percent). Use the PERCENT= option to request spine percent.
The SLICE=, VALUE=, and PERCENT= options use the same values:
ARROW
places the text outside of the star circle and connects the text to the circle with a line. The line points to the spine or the center of the slice. The arrow uses the color that is specified by the CTEXT= option in the STAR statement. If you omit the CTEXT= option, the arrow uses the color defined by the current style.
INSIDE
places the text inside the star circle.
NONE
suppresses the text.
OUTSIDE
places the text outside the star circle.
Slice Labeling Methods illustrates these values.
The SLICE= and VALUE= options are dependent on each other. If you specify only VALUE= or only SLICE=, the other option automatically uses the same labeling method. The PERCENT= option is independent of these two.
Be careful about the combinations that you specify. For example, if you specify PERCENT=ARROW and VALUE=OUTSIDE, the line that connects the percentage information to each spine might overlay the statistic value.

Selecting Patterns for the Star Charts

Determining Pattern Selection

Star charts are always patterned by midpoint.

Default Patterns and Outlines

Each slice in a star chart is filled with a pattern. Because the system option GSTYLE is in effect by default, the procedure uses the current style's default patterns and outlines when producing output. By default, the procedure does the following:
  • fills the slices with star patterns, beginning with the default fill, PSOLID, and rotates it through the list of colors available in the default style. When these colors are exhausted, the procedure rotates through a slightly modified version of the original list of colors. It continues in this fashion until all of the chart variables have been assigned a unique pattern.
    If you use the default style colors and the first color in the list is either black or white, the procedure does not create a pattern in that color. If you specify a color list with the COLORS= graphics option, the procedure uses all of the colors in the list to generate the patterns.
  • outlines slices using the color defined by the style. To change the outline color, use the COUTLINE= option.
See About Patterns for more information about how the GCHART procedure assigns default patterns and outlines.

Controlling Patterns

You can control slice patterns and their outlines in several ways.
  • To select a different fill for the slices, such as empty or hatched, you can do the following:
    • request a single hatched fill pattern for all slices by specifying the FILL=X option in the STAR statement. The pattern that is specified by FILL=X rotates through the list of colors available in the current style as many times as needed to generate all the patterns required by the chart. If you specify a single color with either CFILL= or the graphics option, CPATTERN=, all slices use the same color as well as the same pattern.
    • specify a pattern with the VALUE= option in the PATTERN statement. Only star patterns are valid; all other pattern specifications are ignored. For a complete description of all star patterns, see the option description for VALUE=pie/star-pattern in the PATTERN statement
      If no color options are specified, the procedure rotates each specified fill once through the list of colors available in the current style. Otherwise, the PATTERN statement generates one pattern definition for the specified pattern and color. When all of the specified patterns are exhausted, the procedure starts rotating through the default star patterns, beginning with PSOLID.
  • To select colors for the slices, you can do the following:
    • specify a single pattern color with the CFILL= option, or with the CPATTERN= graphics option, or with a COLORS= list of one color. For the PIE and DONUT statements, CFILL= starts with the default solid color and uses the foreground color for outlines. In contrast, using the CPATTERN= graphics option or a COLORS= list of one color skips the solid pattern. Beginning with P2N0, these options use each pie hatch pattern with the specified color, and use the fill color for the outline color.
    • specify only the COLOR= option in one or more PATTERN statements. In this case, the procedure creates a solid pattern for each specified color. When it runs out of PATTERN statements, it returns to the default patterns, beginning with PSOLID, and rotates them each through the list of colors available in the current style. Whenever you specify a PATTERN statement, the default outline color is SAME.
  • To define specific patterns and colors for the slices, use PATTERN statements and specify both the VALUE= and COLOR= options. If you provide fewer PATTERN definitions than the chart requires, the GCHART procedure uses the default pattern rotation for the slices that are drawn after all defined patterns are exhausted.
See About Patterns for more information about how the GCHART procedure uses patterns and outlines. See the PATTERN Statement for a description of default star patterns.

Modifying the Statistic Heading and the Group Heading

By default, the procedure prints a heading at the top of each chart indicating the type of statistic charted and the name of the chart variable. For an example see Pie Chart (GCHPISUM (a)). You can suppress this heading with the NOHEADING option.
When you use the GROUP= option, a heading is printed above each star indicating the name of the group variable and its value for the particular star. An example is SITE=Paris. You can suppress these headings with the NOGROUPHEADING option. You can also suppress the variable name SITE= so that only the value Paris remains. To do this, use a LABEL statement and assign a null value to the variable name, as shown in this example:
label site="00"x;
The AXIS statement cannot be used by the STAR statement. Instead, you should use the FTEXT and HTEXT graphics options to control the font and height of text on the chart. Increasing the value of HTEXT= decreases the size of the star if any slice labels are positioned outside.