LEGEND Statement | SAS.GRAPH 9.1 Reference, Volumes I and II

The LEGEND statement controls the location and appearance of legends on two-dimensional plots, contour plots, maps, and charts .

Used by:

GCHART, GCONTOUR, GMAP, GPLOT procedures

Global

Description

LEGEND statements specify the characteristics of a legend but do not create legends. These characteristics are

the position and appearance of the legend box
the text and appearance of the legend label
the appearance of the legend entries, including the size and shape of the legend values
the text of the labels for the legend values.

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.

illustrates the terms associated with the various parts of a legend.

Figure 7.5: Parts of a Legend

Syntax

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

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

appearance options
- ACROSS= number-of- columns
- CBLOCK= block- color
- CBORDER= frame-color
- CFRAME= background-color
- CSHADOW= shadow-color
- DOWN= number-of-rows
- FRAME
- FWIDTH= thickness -factor
- SHAPE=BAR( width , height )< units > LINE( length )< units >
  - SYMBOL( width , height )< units >

position-options
- MODE=PROTECT RESERVE SHARE
- OFFSET=(< x ><, y >)< units > (< x < units >><, y < units >>)
- ORIGIN=(< x ><, y >)< units > (< x < units >><, y < units >>)
- POSITION=(<BOTTOM MIDDLE TOP> <LEFT CENTER RIGHT>
  - <INSIDE OUTSIDE>)

text-options
- LABEL=( text-argument(s) ) NONE
- ORDER=( value-list )
- VALUE=( text-argument(s) ) NONE

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.

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

GUNIT= in a GOPTIONS statement
the default unit, CELLS.

ACROSS= number-of-columns

specifies the number of columns to use for legend entries.
Featured in: Example 8. Creating a Simple Web Page with the ODS HTML Statement on page 245.

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 ).
CBLOCK= and CSHADOW= are mutually exclusive. If both are present, SAS/GRAPH software uses the last one specified. CBLOCK= is usually used in conjunction with the FRAME, CFRAME=, or CBORDER= options.
The Java client treats the CBLOCK option like CSHADOW.
See also: the OFFSHADOW= OFFSHADOW on page 325 graphics option and Creating Drop Shadows and Block Effects on page 163.
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.

CFRAME= background-color

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

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 ).
CSHADOW= and CBLOCK= are mutually exclusive. If both are present, SAS/GRAPH uses the last one specified. CSHADOW= is usually specified in conjunction with the FRAME, CFRAME=, or CBORDER= options.
See also: the OFFSHADOW= OFFSHADOW on page 325 graphics option and Creating Drop Shadows and Block Effects on page 163.

DOWN= number-of-rows

specifies the number of rows to use for legend entries.

FRAME

draws a frame around the legend. The color of the frame is the first color in the colors 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.
Not supported by: Java, 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 which 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 string(s) that follows it. Text-description-suboption can be
    - 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. And, it does not support multiple values for the JUSTIFY suboption (only the first is honored). The ActiveX control supports POSITION= but does not support multiple values for the JUSTIFY suboption (only the first is honored).
  - See Text Description Suboptions on page 158 for complete descriptions.
Specify as many text strings and text description suboptions as you want, but enclose them all in one set of parentheses.
Featured in: Example 3. Rotating Plot Symbols through the Colors List on page 231 and Example 8. Creating a Simple Web Page with the ODS HTML Statement on page 245
Not supported by: Java (partial), ActiveX (partial)

MODE=PROTECT RESERVE SHARE

specifies whether or not 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 may 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= is changed to PROTECT.

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 which case the default changes to MODE=PROTECT.
See also: Positioning the Legend on page 162
Featured in: Example 8. Creating a Simple Web Page with the ODS HTML Statement on page 245.
Not supported by: Java, 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) 
```
OFFSET= is usually used in conjunction with POSITION= to adjust the position of the legend. Moves are relative to the location specified by POSITION=, with OFFSET=(0,0) representing the initial position. You can also apply OFFSET= to the default legend position.
OFFSET= is unnecessary with ORIGIN= since ORIGIN= explicitly positions the legend and requires no further adjustment. However, if you specify both options, the values of OFFSET= are added to the values of ORIGIN=, and the LEGEND is positioned accordingly .
See also: Positioning the Legend on page 162 and the option POSITION= on page 155
Not supported by: Java, 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= on page 130 in the AXIS statement.

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

Not supported by: ActiveX, Java

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. ORIGIN= 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) 
```
ORIGIN= overrides the POSITION= option if both are used. Although using the OFFSET= option with the ORIGIN= option is unnecessary, if OFFSET= is also specified, it is applied after the ORIGIN= request has been processed .
See also: Positioning the Legend on page 162
Featured in: Example 8. Creating a Simple Web Page with the ODS HTML Statement on page 245 .
Not supported by: Java, ActiveX

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

positions the legend on the graph. Value 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= options overrides POSITION=. The value of the MODE= option can affect the behavior of POSITION=.
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.
See also: information on positioning the Legend in the SAS/GRAPH Reference, Volumes 1 and 2 , the options OFFSET= on page 154, andMODE= on page 154.
Not supported by: Java (partial)

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 value you specify for SHAPE= depends on which procedure generates the legend.
- BAR( width , height )< units >
  - is used with the GCHART and GMAP procedures, the GPLOT procedure if you use the AREAS= option, and 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.
  - Featured in: Example 3. Rotating Plot Symbols through the Colors List on page 231 and Example 8. Creating a Simple Web Page with the ODS HTML Statement on page 245.
- 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 Figure 7.6 on page 157(a):
```
 shape=symbol(.5,.5) 
```
    Figure 7.6: Legend Values Produced with SHAPE= SYMBOL
  - This specification produces legend values like the ones in Figure 7.6 on page 157(b):
```
 shape=symbol(2,.5) 
```
  - 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.
  - Featured in: Example 3. Rotating Plot Symbols through the Colors List on page 231.
  - Not supported by: Java, 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 forth. For example, this specification produces legend entries like those shown in Figure 7.7 on page 157:
```
 value=('1986' '1987' '1988') 
```
    Figure 7.7: 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
    - COLOR= text-color
    - FONT= font
    - NONE
    - HEIGHT= text-height < units >
    - JUSTIFY=LEFT
    - CENTER
    - RIGHT
    - TICK= n (not supported by Java or ActiveX)
    - See Text Description Suboptions on page 158 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 on page 158 and the option ORDER= on page 155
Not supported by: Java (partial), ActiveX (partial)

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 LABEL= on page 153 and VALUE= on page 157.

COLOR= text-color

C= text-color

specifies the color of the text. If you omit COLOR=, 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 default, the first color in the colors list.

FONT= font NONE

F= font NONE

specifies the font for the text. See Chapter 5, SAS/GRAPH Fonts, on page 75 for information on specifying fonts. If you omit FONT=, a font specification is searched for in this order:
1. the FTEXT= option in a GOPTIONS statement
2. the default hardware font, NONE.

HEIGHT= text-height < units >

H= text-height < units >

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

JUSTIFY=LEFT CENTER RIGHT

J=L C R

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 JUSTIFY= to print multiple lines of text by repeating JUSTIFY= before the text string for each line. For example, this statement produces a legend label and value descriptions like those shown in Figure 7.8 on page 159:
```
 legend label=(justify=c 'Distribution'                justify=c 'Centers')  value=(tick=1 justify=c 'Portland,'                justify=c 'aine'         tick=2 justify=c 'Paris,'                justify=c 'France'         tick=3 justify=c 'Sydney,'                justify=c 'Australia'); 
```
Figure 7.8: Specifying Multiple Lines of Text with the JUSTIFY= Suboption
Specify additional suboptions before any string.

See also: the suboption TICK= on page 160.

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.
Figure 7.9 on page 160 shows some of the ways POSITION= affects a multi-line legend label in which the entries are stacked in a column (ACROSS=1). This figure uses a label specification such as
```
 label=(multi-          justify=left line          justify=left label          position=left) 
```
Figure 7.9: Using the POSITION= Suboption with Multi-line Legend Labels
In this specification, POSITION= specifies the default value, LEFT, which is represented by the first legend in the figure. The value of POSITION= is indicated above each legend. The default justification is used unless you also use the JUSTIFY= suboption.
In addition, specifying POSITION=RIGHT mirrors the effect of POSITION=LEFT, and specifying POSITION=BOTTOM mirrors the effect of POSITION=TOP.
Not supported by: Java

TICK= n

T= n

specifies the n th 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
```
 value=(tick=3 Minneapolis) 
```
The characteristics of all other value descriptions remain unchanged.
If you use TICK= 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 TICK= 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 TICK= 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.

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=swiss height=4 Weight         justify=right height=3 (in tons))

FONT=SWISS 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 one 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 Placement of Graphic Elements in the Graphics Output Area on page 39.) However, several LEGEND statement options allow 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:

Describe the general location of the legend with the POSITION= option. If necessary, fine-tune the position with the OFFSET= option.
Position the legend explicitly with the ORIGIN=option.

Using POSITION= and OFFSET=

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

OUTSIDE and INSIDE determine whether the legend is located outside or inside the axis area.
BOTTOM or MIDDLE or TOP (vertical position) and LEFT or CENTER or RIGHT (horizontal position) determine where the legend is located in relation to its OUTSIDE or INSIDE position.

Figure 7.10 on page 162 shows the legend positions inside the axis area.

Figure 7.10: Legend Positions Inside the Axis Area

Figure 7.11 on page 162 shows legend positions outside the axis area.

Figure 7.11: 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 POSITION=. 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 MODE=:

RESERVE reserve space for the legend outside the axis area and move the graph to make room for the legend. This is the default setting and is valid only when POSITION=OUTSIDE.
PROTECT prevents the legend from being overwritten by the procedure output. PROTECT blanks out graphics elements, allowing only legend elements to be displayed in the legend s space.
SHARE displays both graphics elements and legend elements in the same space. This setting is usually used when the legend is positioned inside the axis area. SHARE is useful when the graph has a space that the legend can fit into. For an example, see Example 8. Creating a Simple Web Page with the ODS HTML Statement on page 245.

Interactions Between POSITION= and MODE=

You cannot specify both POSITION=INSIDE and MODE=RESERVE because MODE=RESERVE assumes 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 MODE= to SHARE or PROTECT. Otherwise, SAS/GRAPH issues a warning and automatically changes the value of MODE= 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.