Previous Page | Next Page

SAS/GRAPH Statements

LEGEND Statement


Controls the location and appearance of legends on two-dimensional plots, contour plots, maps, and charts.
Used by: GAREABAR, GCHART, GBARLINE, GCONTOUR, GMAP, GPLOT procedures
Type: Global
Syntax
Description
Options
Text Description Suboptions
Using Text Description Suboptions
Using the LEGEND Statement
Positioning the Legend
Positioning the Legend on the Graphics Output Area
Using POSITION= and OFFSET=
Using ORIGIN=
Relating Legends to Other Graphic Elements
Interactions Between POSITION= and MODE=
Creating Drop Shadows and Block Effects

Syntax

LEGEND<1...99> <options>;

option(s) can be one or more options from any or all of the following categories:

Description

LEGEND statements specify the characteristics of a legend but do not create legends. The characteristics are as follows:

LEGEND definitions are not automatically applied when a procedure generates a legend. Instead, they must be explicitly assigned with a LEGEND= option in the appropriate procedure statement.

The following figure illustrates the terms associated with the various parts of a legend.

Parts of a Legend

[Parts of a Legend]

Options

When the syntax of an option includes units, use one of these:

CELLS

character cells

CM

centimeters

IN

inches

PT

points

PCT

percentage of the graphics output area

Note:   The Java applet does not support CM, IN, or PT.  [cautionend]

If you omit units, a unit specification is searched for in this order:

  1. GUNIT= in a GOPTIONS statement

  2. the default unit, CELLS

ACROSS=number-of-columns

specifies the number of columns to use for legend entries. If there are multiple rows and columns in a legend, use the ROWMAJOR and COLMAJOR options to specify the arrangement of legend entries. Specify the ROWMAJOR option to arrange entries (from lowest to highest) starting from left to right, and then top to bottom. Specify the COLMAJOR option to arrange entries starting from top to bottom, and then left to right.

Featured in: Example 8. Creating a Simple Web Page with the ODS HTML Statement
See also: ROWMAJOR, COLMAJOR
CBLOCK=block-color

generates and colors a three-dimensional block effect behind the legend. The size and position of the block are controlled by the graphics option OFFSHADOW=(x,y).

The CBLOCK= and CSHADOW= options are mutually exclusive. If both are present, SAS/GRAPH software uses the last one specified. The CBLOCK= option is usually used in conjunction with the FRAME, CFRAME=, or CBORDER= options.

The Java applet treats the CBLOCK option like the CSHADOW option.

See also: The OFFSHADOW= graphics option and Creating Drop Shadows and Block Effects
Restriction: Not supported by Java.
CBORDER=frame-color

draws a colored frame around the legend. This option overrides the FRAME option. CBORDER= can be used in conjunction with the CFRAME= option.

Style Reference: Color attribute of the GraphBorderLines graph element
CFRAME=background-color

specifies the background color of the legend. This option overrides the FRAME option. If both the CFRAME= and FRAME= options are specified, only the solid background produced by the CFRAME= option is displayed. The CFRAME= option can be used in conjunction with the CBORDER= option.

Style Reference: Color attribute of the GraphLegendBackground graph element
CSHADOW=shadow-color

generates and colors a drop shadow behind the legend. The size and position of the shadow is controlled by the graphics option OFFSHADOW=(x,y).

The CSHADOW= and CBLOCK= options are mutually exclusive. If both are present, SAS/GRAPH uses the last one specified. The CSHADOW= option is usually specified in conjunction with the FRAME, CFRAME=, or CBORDER= options.

See also: the OFFSHADOW= graphics option and Creating Drop Shadows and Block Effects.
DOWN=number-of-rows

specifies the number of rows to use for legend entries. If there are multiple rows and columns in a legend, use the ROWMAJOR and COLMAJOR options to specify the arrangement of legend entries. Specify the ROWMAJOR option to arrange entries (from lowest to highest) starting from left to right, and then top to bottom. Specify the COLMAJOR option to arrange entries starting from top to bottom, and then left to right. The ROWMAJOR option is the default.

FRAME

draws a frame around the legend. The color of the frame is the first color in the color list.

FWIDTH=thickness-factor

specifies the thickness of the frame, where thickness-factor is a number. The thickness of the line increases directly with thickness-factor. By default, FWIDTH=1.

Restriction: Not supported by Java and ActiveX
LABEL=(text-argument(s)) | NONE

modifies a legend label. Text-argument(s) defines the appearance or the text of a legend label, or both. NONE suppresses the legend label. By default, the text of the legend label is either the variable name or a previously assigned variable label (except in the case of GPLOT with OVERLAY. In that case the default label is "PLOT"). Text-argument(s) can be one or more of these:

"text-string"

provides up to 256 characters of label text. Enclose each string in quotes. Separate multiple strings with blanks.

text-description-suboption

modifies a characteristic such as the font, color, or size of the text strings that follows it. Text-description-suboption can be as follows:

COLOR=text-color

FONT=font | NONE

HEIGHT=text-height <units>

JUSTIFY=LEFT | CENTER | RIGHT

POSITION=(<BOTTOM | MIDDLE | TOP> <LEFT | CENTER | RIGHT>)

Note:   The Java applet does not support the POSITION= suboption--it draws legend labels at the top-left of the legend. Also, it does not support multiple values for the JUSTIFY= suboption (only the first is honored). The ActiveX control supports the POSITION= option but does not support multiple values for the JUSTIFY suboption (only the first is honored).  [cautionend]

See Text Description Suboptions for complete descriptions.

Specify as many text strings and text description suboptions as you want, but enclose them all in one set of parentheses.

Style Reference: Color attribute of the GraphLabelText graph element
Featured in: Example 3. Rotating Plot Symbols Through the Color List and Example 8. Creating a Simple Web Page with the ODS HTML Statement
Restriction: Partially supported by Java and ActiveX
MODE=PROTECT | RESERVE | SHARE

specifies whether the legend is drawn in the procedure output area or whether legend elements can overlay other graphics elements. MODE= can take one of these values:

PROTECT

draws the legend in the procedure output area, but a blanking area surrounds the legend, preventing other graphics elements from being displayed in the legend. (A blanking area is a protected area in which no other graphics elements are displayed.)

RESERVE

takes space for the legend from the procedure output area, thereby reducing the amount of space available for the graph. If MODE=RESERVE is specified in conjunction with OFFSET=, the legend can push the graph off the graphics output area. RESERVE is valid only when POSITION=OUTSIDE. If POSITION=INSIDE is specified, a warning is issued and MODE= value is changed to PROTECT.

SHARE

draws the legend in the procedure output area. If the legend is positioned over elements of the graph itself, both graphics elements and legend elements are displayed.

By default, MODE=RESERVE unless POSITION=INSIDE. In this case, the default changes to MODE=PROTECT.

See also: Positioning the Legend
Restriction: Not supported by Java and ActiveX
OFFSET=(<x><,y>)<units> | (<x <units>><,y <units>>)

specifies the distance to move the entire legend; x is the number of units to move the legend right (positive numbers) or left (negative numbers), and y is the number of units to move the legend up (positive numbers) or down (negative numbers).

To set only the x offset, specify one value, with or without a following comma: 

offset=(4 cm,)

To set both the x and y offset, specify two values, with or without a comma separating them: 

offset=(2 pct, 4 pct)

To set only the y offset, specify one value preceded by a comma: 

offset=(,-3 pct)

The OFFSET= option is usually used in conjunction with the POSITION= option to adjust the position of the legend. Moves are relative to the location specified by the POSITION= option, with OFFSET=(0,0) representing the initial position. You can also apply the OFFSET= option to the default legend position.

The OFFSET= option is unnecessary with the ORIGIN= option since the ORIGIN= option explicitly positions the legend and requires no further adjustment. However, if you specify both options, the OFFSET= values are added to the ORIGIN= values,l and the LEGEND is positioned accordingly.

See also: Positioning the Legend and the option POSITION=
Restriction: Not supported by Java and ActiveX
ORDER=(value-list)

selects or orders the legend values that appear in the legend. The way you specify value-list depends on the type of variable that generates the legend:

  • For numeric 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.

  • For character variables, value-list is a list of unique character values enclosed in quotes 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 option ORDER= in the AXIS statement.

Even though the ORDER= option controls whether a legend value is displayed and where it appears, the VALUE= option controls the text that the legend value displays.

Restriction: Not supported by Java and ActiveX
ORIGIN=(<x><,y>)<units> | (<x <units >><,y <units>>)

specifies the x coordinate and the y coordinate of the lower-left corner of the legend box. The ORIGIN= option explicitly positions the legend anywhere on the graphics output area. It is possible to run a legend off the page or overlay the graph.

To set only the x coordinate, specify one value, with or without a following comma: 

origin=(4 cm,)

To set both the x and y coordinates, specify two values, with or without a comma separating them: 

origin=(2 pct, 4 pct)

To set only the y coordinate, specify one value preceded by a comma: 

origin=(,3 pct)

The ORIGIN= option overrides the POSITION= option if both are used. Although using the OFFSET= option with the ORIGIN= option is unnecessary, if the OFFSET= option is also specified, it is applied after the ORIGIN= request has been processed.

See also: Positioning the Legend
Restriction: Not supported by Java and ActiveX
POSITION=(<BOTTOM | MIDDLE | TOP> <LEFT | CENTER | RIGHT> <OUTSIDE | INSIDE>)

positions the legend on the graph. Values for POSITION= are

OUTSIDE or INSIDE

specifies the location of the legend in relation to the axis area.

BOTTOM or MIDDLE or TOP

specifies the vertical position.

LEFT or CENTER or RIGHT

specifies the horizontal position.

By default, POSITION=(BOTTOM CENTER OUTSIDE). You can change one or more settings. If you supply only one value the parentheses are not required. If you specify two or three values and omit the parentheses, SAS/GRAPH accepts the first value and ignores the others.

Once you assign the initial legend position, you can adjust it with the OFFSET= option.

The ORIGIN= option overrides the POSITION= option. The value of the MODE= option can affect the behavior of the POSITION= option.

Note:   The Java applet defaults to BOTTOM-CENTER and supports all possible combinations of BOTTOM | MIDDLE | TOP with LEFT | CENTER | RIGHT except for MIDDLE-CENTER (which would overwrite the map.) The Java applet does not support INSIDE for positioning.  [cautionend]

See also: OFFSET= option and MODE= option
Restriction: Partially supported by Java
REPEAT=1 | 2 | 3

Use the REPEAT= option to specify how many times the plot symbol is repeated in the legend. Valid values are 1 to 3, with 3 being the default.

ROWMAJOR | COLMAJOR

specifies the arrangement of legend entries when there are multiple rows and multiple columns. Specify the ROWMAJOR option (the default) to arrange entries (from lowest to highest) starting from left to right, and then top to bottom. Specify the COLMAJOR option to arrange the entries starting from top to bottom, and then left to right.

See also: ACROSS=, DOWN=
SHAPE=BAR(width<units>,height<units>) <units> | LINE(length) <units> | SYMBOL(width<units>,height<units>) <units>

specifies the size and shape of the legend values displayed in each legend entry. The SHAPE= value you specify depends on which procedure generates the legend.

BAR(width,height)<units>

is used with the GCHART and GMAP procedures, with the GPLOT procedure if you use the AREAS= option, and with the GCONTOUR procedure if you use the PATTERN option. Each legend value is a bar of the specified width and height. By default, width is 5, height is 0.8, and units are CELLS. You can specify units for the width,height pair or for the individual coordinates.

LINE(length) <units>

is used with the GPLOT and GCONTOUR procedures. Each legend value is a line of the length you specify. Plotting symbols are omitted from the legend values. By default, length is 5 and units are CELLS. You can specify units for length.

SYMBOL(width<units>,height<units>) <units>

is used with the GPLOT procedure. Each legend value (not each symbol) is the width and height you specify. For example, this specification produces legend values like the ones in Legend Values Produced with SHAPE= SYMBOL(a): 

shape=symbol(.5,.5)

This specification produces legend values like the ones in Legend Values Produced with SHAPE= SYMBOL(b): 

shape=symbol(2,.5)

Legend Values Produced with SHAPE= SYMBOL

[Legend Values Produced with SHAPE= SYMBOL]

By default, width is 5, height is 1, and units are CELLS. You can specify units for the width,height pair or for the individual coordinates.

Restriction: Not supported by Java and ActiveX
VALUE=(text-argument(s) ) | NONE

modifies the legend value descriptions. Text-argument(s) defines the appearance or the text of the value descriptions. By default, value descriptions are the values of the variable that generates the legend or an associated format value. Numeric values are right-justified and character values are left-justified.

NONE suppresses the value descriptions although the legend values (bars, lines, and so on) are still displayed. (NONE is not supported by Java or ActiveX). Text-argument(s) can be one or more of these:

"text-string"

provides up to 256 characters of text for the value description. Enclose each string in quotes. Separate multiple strings with blanks.

Specified text strings are assigned to the legend values in order. If you submit only one string, only the first legend entry uses the value of that string. If you specify multiple strings, the first string is the text for the first entry; the second string is the text for the second entry; and so on. For example, this specification produces legend entries like those shown in Specifying Value Descriptions with the VALUE= Option: 

value=("1986" "1987" "1988")

Specifying Value Descriptions with the VALUE= Option

[Specifying Value Descriptions with the VALUE=Option]

text-description-suboption

modifies a characteristic such as the font, color, or size of the text string(s) that follows it. Text-description-suboption can be as follows:

COLOR=text-color

FONT=font | NONE

HEIGHT=text-height <units >

JUSTIFY=LEFT | CENTER | RIGHT

TICK=n

See Text Description Suboptions for complete descriptions.

Place text description suboptions before the text strings they modify. Suboptions not followed by a text string affect the default values. To specify and describe the text for individual values or to produce multi-line text, use the TICK= suboption.

Specify as many text strings and text description suboptions as you want, but enclose them all in one set of parentheses.

To order or select legend entries, use the ORDER= option.

See also: Text Description Suboptions and the option ORDER=
Restriction: Partially supported by Java and ActiveX
Text Description Suboptions

Text description suboptions are used by the LABEL= and VALUE= options to change the color, height, justification, font, and angle of either default text or specified text strings. See the LABEL= suboption and the VALUE= suboption.

COLOR=text-color

specifies the color of the text. If you omit the COLOR= suboption, a color specification is searched for in this order:

  1. the CTEXT= option for the procedure

  2. the CTEXT= option in a GOPTIONS statement

  3. the color of the default style

Alias: C=text-color
FONT=font | NONE

specifies the font for the text. See Specifying Fonts in SAS/GRAPH Programs for information on specifying fonts. If you omit the FONT= suboption, a font specification is searched for in this order:

  1. the FTEXT= option in a GOPTIONS statement

  2. the default style font, NONE

Alias: F=font | NONE
HEIGHT=text-height <units>

specifies the height of the text characters in the number of units. By default, HEIGHT=1 CELL. If you omit the HEIGHT= suboption, a text height specification is searched for in this order:

  1. the HTEXT= option in a GOPTIONS statement

  2. the height specified by the default style

Alias: H=text-height <units>
JUSTIFY=LEFT | CENTER | RIGHT

specifies the alignment of the text. The default for character variables is JUSTIFY=LEFT. The default for numeric variables is JUSTIFY=RIGHT. Associating a character format with a numeric variable does not change the default justification of the variable.

You can use the JUSTIFY= suboption to print multiple lines of text by repeating the suboption before the text string for each line. For example, this statement produces a legend label and value descriptions like those shown in Specifying Multiple Lines of Text with the JUSTIFY= Suboption: 

legend label=(justify=c "Distribution"
              justify=c "Centers")
value=(tick=1 justify=c "Portland,"
              justify=c "Maine"
       tick=2 justify=c "Paris,"
              justify=c "France"
       tick=3 justify=c "Sydney,"
              justify=c "Australia");

Specifying Multiple Lines of Text with the JUSTIFY= Suboption

[Specifying Multiple Lines of Text with the JUSTIFY=Suboption]

Specify additional suboptions before any string.

See also: the suboption TICK= .
Alias: J=L | C | R
POSITION=(<BOTTOM | MIDDLE | TOP> <LEFT | CENTER | RIGHT>)

places the legend label in relation to the legend entries. The POSITION= suboption is used only with the LABEL= option. By default, POSITION=LEFT.

The parentheses are not required if only one value is supplied. If you specify two or three values and omit the parentheses, SAS/GRAPH accepts the first value and ignores the others.

Using the POSITION= Suboption with Multiple-line Legend Labels shows some of the ways the POSITION= suboption affects a multiple-line legend label in which the entries are stacked in a column (ACROSS=1). This figure uses a label specification such as the following: 

label=("multi-"
        justify=left "line"
        justify=left "label"
        position=left)

In this specification, the POSITION= suboption specifies the default value, LEFT, which is represented by the first legend in the figure. The POSITION= value is indicated above each legend. The default justification is used unless you also use the JUSTIFY= suboption.

Using the POSITION= Suboption with Multiple-line Legend Labels

[Using the POSITION= Suboption with Nulti-line Legend Labels]

POSITION

In addition, specifying POSITION=RIGHT mirrors the effect of POSITION=LEFT, and specifying POSITION=BOTTOM mirrors the effect of POSITION=TOP.

Restriction: Not supported by Java. Partially supported by ActiveX.
TICK=n

specifies the nth legend entry. The TICK= suboption is used only with the VALUE= option to designate the legend entry whose text and appearance you want to modify. For example, to change the text of the third legend entry to Minneapolis , specify the following code: 

value=(tick=3 "Minneapolis")

The characteristics of all other value descriptions remain unchanged.

If you use the TICK= suboption when you designate text for one legend entry, you must also use it when you designate text for any additional legend entries. For example, this option changes the text of both the second and third legend entries: 

value=(tick=2 "Paris" tick=3 "Sydney")

If you omitted TICK=3, the text of the second legend entry would be ParisSydney .

Text description suboptions that precede the TICK= suboption affect all the value descriptions for the legend unless the same suboption (with a different value) follows a TICK= specification. Text description suboptions that follow the TICK= suboption affect only the specified legend entry. For example, suppose you specify this option for a legend with three entries: 

value=(color=red font=swiss tick=2 color=blue)

The text of all three entries would use the Swiss font; the first and third entries would be red and only the second entry would be blue.

Alias: T=n
Using Text Description Suboptions

Text description suboptions affect all the strings that follow them unless the suboption is changed or turned off. If the value of a suboption is changed, the new value affects all the text strings that follow it. Consider this example: 

label=(font=albany amt height=4 "Weight"
       justify=right height=3 "(in tons)")

FONT=ALBANY applies to both Weight and (in tons) . HEIGHT=4 affects Weight , but is respecified as HEIGHT=3 for (in tons) . JUSTIFY=RIGHT affects only (in tons) .

Using the LEGEND Statement

LEGEND statements can be located anywhere in your SAS program. They are global and remain in effect until canceled or until you end your SAS session. LEGEND statements are not applied automatically, and must be explicitly assigned by an option in the procedure that uses them.

You can define up to 99 different LEGEND statements. If you define two LEGEND statements of the same number, the most recently defined statement replaces the previously defined statement of the same number. A LEGEND statement without a number is treated as a LEGEND1 statement.

Cancel individual LEGEND statements by defining a LEGEND statement of the same number without options (a null statement): 

legend4;

Canceling one LEGEND statement does not affect any other LEGEND definitions. To cancel all current LEGEND statements, use RESET= in a GOPTIONS statement: 

goptions reset=legend;

Specifying RESET=GLOBAL or RESET=ALL cancels all current LEGEND definitions as well as other settings.

To display a list of current LEGEND definitions in the LOG window, use the GOPTIONS procedure with the LEGEND option: 

proc goptions legend nolist;
run;

Positioning the Legend

By default, the legend shares the procedure output area with the procedure output, such as a map or bar chart. (See How Graphic Elements are Placed in the Graphics Output Area.) However, several LEGEND statement options enable you to position a legend anywhere on the graphics output area and even to overlay the procedure output. This section describes these options and their effect on each other.


Positioning the Legend on the Graphics Output Area

There are two ways you can position the legend on the graphics output area:


Using POSITION= and OFFSET=

The values of the POSITION= option affect the legend in two ways:

Legend Positions Inside the Axis Area shows the legend positions inside the axis area.

Legend Positions Inside the Axis Area

[Legend Positions Inside the Axis Area]

Legend Positions Outside the Axis Area shows legend positions outside the axis area.

Legend Positions Outside the Axis Area

[Legend Positions Outside the Axis Area]

The default combination is POSITION=(BOTTOM CENTER OUTSIDE). The combination (OUTSIDE MIDDLE CENTER) is not valid.

Use OFFSET=(x,y) to adjust the position of the legend specified by the POSITION= option. The x value shifts the legend either left or right and the y value shifts the legend either up or down.

The offset values are always applied after the POSITION= request. For example, if POSITION=(TOP RIGHT OUTSIDE), the legend is located in the upper right corner of the graphics output area. If OFFSET=(0,0) is specified, the legend does not move. If OFFSET=(-5,-8)CM, the legend moves 5 centimeters to the left and 8 centimeters down.


Using ORIGIN=

Use ORIGIN=(x,y) to specify the coordinates of the exact location of the lower left corner of the legend box. Because ORIGIN=(0,0) is the lower left corner of the graphics output area, the values of x and y must be positive. If you specify negative values, a warning is issued and the default value is used.


Relating Legends to Other Graphic Elements

By default, the legend is inside the procedure output area and the space it occupies reduces the size of the graph itself. To control the way the legend relates to the other elements of the graph, use the MODE= option. These are values for the MODE= option:


Interactions Between POSITION= and MODE=

You cannot specify both POSITION=INSIDE and MODE=RESERVE because MODE=RESERVE assumes that the legend is outside the axis area, and POSITION=INSIDE positions the legend inside the axis area. Therefore, when you specify POSITION=INSIDE, change the value of the MODE= option to SHARE or PROTECT. Otherwise, SAS/GRAPH issues a warning and automatically changes the MODE= value to PROTECT.

Creating Drop Shadows and Block Effects

To produce a drop shadow or a three-dimensional block effect behind the legend use the CSHADOW= or CBLOCK= option in the LEGEND statement in conjunction with the graphics option OFFSHADOW=(x,y).

The value of x determines how far the shadow or block extends to the right (positive numbers) or to the left (negative numbers) of the legend. The value of y determines how far the shadow or block extends above (positive numbers) or below (negative numbers) the legend. If OFFSHADOW=(0,0) is specified, the shadow or block is not visible.

By default, OFFSHADOW=(0.0625, -0.0625) IN; that is, the shadow or block extends 1/16th of an inch to the right and 1/16th of an inch below the legend.

Previous Page | Next Page | Top of Page

Copyright © 2010 by SAS Institute Inc., Cary, NC, USA. All rights reserved.