Example Program and Statement Details

Example Graph

The following graph was generated by the Example Program. The LAYOUT OVERLAY statement’s XAXISOPTS= option uses NAME= to assign a name to the X axis so that it can be referenced in an AXISLEGEND statement. The LAYOUT OVERLAY statement’s DISCRETEOPTS= option specifies TICKVALUEFITPOLICY=EXTRACT, which implements the axis legend if a collision occurs in the tick-value display for the X axis. The AXISLEGEND statement references the name that was assigned to the X axis.

Example Program

proc template;
 define statgraph axislegend ;
  begingraph;
   entrytitle "Mileage for Vehicles Made by Dodge";
   layout overlay / xaxisopts=(name="xaxis" 
       discreteopts=(tickvaluefitpolicy=extract)) ;
     barchart x=model y=mpg_highway / stat=mean ;
     axislegend "xaxis"; 
   endlayout;
  endgraph;
 end;

proc sort data=sashelp.cars out=dodge; by descending mpg_highway;
  where make="Dodge";

proc sgrender data=dodge template=axislegend;
run;

Statement Summary

An AXISLEGEND statement is used to consolidate the axis display so that a large number of tick values can be clearly displayed without collision. In an axis legend, the legend symbol is a positive integer that is generated to represent a specific axis tick position, and the legend value displays the axis tick value. In the Example Graph, the first legend symbol is the integer 1 and the first legend value is

Neon SE
                     4dr

To implement an axis legend, all of the following requirements must be met:

The axis must be a discrete axis. The axis can be discrete by default, or explicitly set to discrete by setting TYPE=DISCRETE among the parent layout’s axis-option settings.
The parent layout’s axis options must specify NAME= to assign a name to the axis.
The parent layout’s axis options must use the DISCRETEOPTS= option to specify either TICKVALUEFITPOLICY=EXTRACT or TICKVALUEFITPOLICY=EXTRACTALWAYS. EXTRACT implements an axis legend if the system estimates that a collision might occur. EXTRACTALWAYS implements an axis legend regardless of whether a collision occurs.
The AXISLEGEND statement must reference the axis name that was specified in the parent layout’s NAME= axis option.

When all of these requirements are satisfied, the tick values of the named discrete axis can be replaced with consecutive positive integers. The axis legend displays those integer values and the corresponding tick values that the integers represent.

Within an overlay-type layout, when an axis legend is placed inside the plot area with LOCATION=INSIDE,

The axis legend is always placed on top of plot lines and markers.
By default, its background is fully transparent (OPAQUE=FALSE), meaning that underlying lines, markers, and data labels show through the legend.
Its position can be controlled with the AUTOALIGN= option, or with the HALIGN= and VALIGN= options.

Within an overlay-type layout, when an axis legend is placed outside the plot area with LOCATION=OUTSIDE,

By default, its background is fully opaque (OPAQUE=TRUE).
Its position can be controlled with the HALIGN= and VALIGN= options.

When an axis legend is placed within nested layouts, it might be necessary to do one of the following to obtain the desired legend organization:

use the ACROSS= option and also set ORDER=ROWMAJOR
use the DOWN= option and also set ORDER= COLUMNMAJOR

A legend might be dropped if the total legend area in the graph exceeds the percentage that is set by the MAXLEGENDAREA= option in an ODS GRAPHICS statement that is in effect for the output destination. A legend might also be dropped if DISPLAYCLIPPED=FALSE and the full legend cannot be displayed.

Arguments

"axis-name"

references an axis’s name. The name controls which axis determines the legend entries.

Requirement: The axis-name must be enclosed in quotation marks.

Options

Statement Option	Description
ACROSS	Specifies the number of legend entries that are placed horizontally before the next row begins.
AUTOALIGN	Specifies whether the legend is automatically aligned within its parent layout when nested within an overlay-type layout.
BACKGROUNDCOLOR	Specifies the color of the legend background.
BORDER	Specifies whether a border is displayed around the legend.
BORDERATTRS	Specifies the properties of the border line around the legend.
DISPLAYCLIPPED	Specifies whether the legend is displayed when any portion of the legend cannot be rendered entirely.
DOWN	Specifies the number of legend entries that are placed vertically before the next column begins.
HALIGN	Specifies the horizontal alignment of the legend within its parent layout when nested within an overlay-type or region layout.
LOCATION	Specifies whether the legend appears inside or outside the plot area when the legend is specified within an overlay-type or region layout.
OPAQUE	Specifies whether the legend background is opaque.
ORDER	Specifies whether legend entries are organized into rows or into columns.
PAD	Specifies the amount of extra space that is added inside the legend perimeter.
TITLE	Specifies the title of the legend.
TITLEATTRS	Specifies the color and font attributes of the legend title.
VALIGN	Specifies the vertical alignment of the legend within its parent layout when nested within an overlay-type or region layout.
VALUEATTRS	Specifies the color and font attributes of the legend values.

ACROSS=positive-integer

specifies the number of legend entries that are placed horizontally before the next row begins.

Default: The entries are placed to best fit the available area. This “best fit” approach works only when the legend is nested in the template’s outermost layout.

Restriction: This option is ignored if ORDER=COLUMNMAJOR

AUTOALIGN=NONE | AUTO | (location-list)

specifies whether the legend is automatically aligned within its parent layout when nested within an overlay-type layout. For more information about how child positions are determined in an overlay-type layout, see the LAYOUT OVERLAY’s Statement Summary.

Default: NONE

NONE

Do not automatically align the legend within its parent layout. The legend’s position is set by the HALIGN= and VALIGN= options.

AUTO

Available only if the parent layout contains a scatter plot; ignored otherwise. Within the parent layout, attempt to center the legend in the area that is farthest from any surrounding data point markers.

(location-list)

Within the parent layout, restrict the legend’s possible locations to those locations in the specified location-list, and use the location-list position that least collides with the parent layout’s other graphics features. The location-list is blank-separated and can contain any of these locations: TOPLEFT, TOP, TOPRIGHT, LEFT, CENTER, RIGHT, BOTTOMLEFT, BOTTOM, and BOTTOMRIGHT.

Interaction: This option has no effect unless LOCATION=INSIDE.

Interaction: If LOCATION=INSIDE, this option overrides HALIGN= and VALIGN=.

BACKGROUNDCOLOR=style-reference | color

specifies the color of the legend background.

Default: The GraphLegendBackground:Color style reference.

style-reference

A reference of the form style-element:style-attribute. Only the style-attribute named COLOR is used.

Interaction: OPAQUE=TRUE must be in effect for the color to be seen. By default, OPAQUE=FALSE.

BORDER=boolean

specifies whether a border is displayed around the legend.

Default: TRUE

BORDERATTRS=style-element | style-element (line-options) | (line-options)

specifies the attributes of the border line around the legend. See General Syntax for Attribute Options for the syntax on using a style-element and Line Options for available line-options.

Default: The GraphBorderLines style element.

Interaction: BORDER=TRUE must be set for this option to have any effect.

DISPLAYCLIPPED=boolean

specifies whether the legend is displayed when any portion of the legend cannot be rendered entirely.

Default: FALSE

Discussion: Based on the legend contents and placement, or when the graph size is reduced, parts of the legend (title, legend symbol, or legend value) might be clipped (truncated). When clipping occurs and this option is set to FALSE, the entire legend is removed from the graph. The space for that legend is then reclaimed by the remainder of the graph. When this option is set to TRUE, the legend always appears, even if some parts of it have been clipped.

DOWN=positive-integer

specifies the number of legend entries that are placed vertically before the next column begins.

Default: The entries are placed to best fit the available area. This “best fit” approach works only when the legend is nested in the template’s outermost layout.

Restriction: This option is ignored if ORDER=ROWMAJOR

HALIGN=CENTER | LEFT | RIGHT | number

specifies the horizontal alignment of the legend within its parent layout when nested within an overlay-type or region layout. For more information about how child positions are determined in an overlay-type or region layout, see the LAYOUT OVERLAY’s Statement Summary.

Default: CENTER

Range: A number specification can range from 0 to 1. The value represents a fraction of the parent container’s width, where 0 is all the way to the left and 1 is all the way to the right.

Restriction: This option is available only when this statement is nested within an overlay-type or region layout. It is ignored if the parent layout is not an overlay-type or region layout.

Interaction: If LOCATION=OUTSIDE, the HALIGN= and VALIGN= options cannot both be set to CENTER.

Interaction: For a number setting to take effect, LOCATION=INSIDE must be set. A number setting is invalid on this option when LOCATION=OUTSIDE.

Interaction: If LOCATION=INSIDE and the AUTOALIGN= option is enabled, this option is ignored.

LOCATION=OUTSIDE | INSIDE

specifies whether the legend appears inside or outside the plot area when the legend is specified within an overlay-type or region layout.

Default: OUTSIDE

Restriction: This option has effect only when the legend statement appears within an overlay-type or region layout and at least one stand-alone plot statement is referenced by the parent layout. For more information about how child positions are determined in an overlay-type or region layout, see the LAYOUT OVERLAY’s Example Program and Statement Details.

Interaction: The actual position is determined by the settings for the LOCATION=, AUTOALIGN=, HALIGN=, and VALIGN= options.

Interaction: If this option is set to OUTSIDE, the HALIGN= and VALIGN= options must specify a keyword (LEFT, RIGHT, or CENTER). The number setting for the alignment is invalid when the legend is positioned outside of the plot area.

OPAQUE=boolean

specifies whether the legend background is opaque (TRUE) or transparent (FALSE).

Default: TRUE when LOCATION=OUTSIDE, FALSE when LOCATION=INSIDE

Interaction: When this option is set to FALSE, the background color is not used.

ORDER=ROWMAJOR | COLUMNMAJOR

specifies whether legend entries are organized into rows or into columns.

Default: ROWMAJOR

Interaction: If ORDER=ROWMAJOR, use the ACROSS= option to limit the number of entries in a row. If ORDER=COLUMNMAJOR, use the DOWN= option to limit the number of entries in a column.

PAD=dimension | (pad-options)

specifies the amount of extra space that is reserved inside the legend perimeter.

Default: The default padding for all sides is 0. Values without units are in pixels (px). A unit must be provided if other than pixels.

dimension

Specifies a dimension to use for the extra space at the left, right, top, and bottom of the legend perimeter.

(pad-options)

Enables separate settings for the left, right, top, and bottom padding dimensions. Use the pad-options to create non-uniform padding. These options must be enclosed in parentheses. Each option is specified as a name = value pair. Sides not assigned padding are padded with the default amount.

Values without units are in pixels (px). A unit must be provided if other than pixels.

LEFT=dimension	specifies the amount of extra space added to the left side.
RIGHT=dimension	specifies the amount of extra space added to the right side.
TOP=dimension	specifies the amount of extra space added to the top.
BOTTOM=dimension	specifies the amount of extra space added to the bottom.

TITLE= "string"

specifies the title of the legend.

Default: no default

Requirement: string must be enclosed in quotation marks.

TITLEATTRS=style-element | style-element (text-options) | (text-options)

specifies the color and font attributes of the legend title. See General Syntax for Attribute Options for the syntax on using a style-element and Text Options for available text-options.

Default: The GraphLabelText style element.

Interaction: For this option to have any effect, the TITLE= option must also be specified.

VALIGN=CENTER | TOP | BOTTOM | number

specifies the vertical alignment of the legend within its parent layout when nested within an overlay-type or region layout. For more information about how child positions are determined in an overlay-type or region layout, see the LAYOUT OVERLAY’s Statement Summary.

Default: CENTER

Range: A number specification can range from 0 to 1. The value represents a fraction of the parent container’s height, where 0 is on the bottom and 1 is on the top.

Restriction: This option is available only when this statement is nested within an overlay-type or region layout. It is ignored if the parent layout is not an overlay-type or region layout.

Interaction: If LOCATION=OUTSIDE, the VALIGN= and HALIGN= options cannot both be set to CENTER.

Interaction: For a number setting to take effect, LOCATION=INSIDE must be set. A number setting is invalid on this option when LOCATION=OUTSIDE.

Interaction: If LOCATION=INSIDE and the AUTOALIGN= option is enabled, this option is ignored.

VALUEATTRS=style-element | style-element (text-options) | (text-options)

specifies the color and font attributes of the legend values. See General Syntax for Attribute Options for the syntax on using a style-element and Text Options for available text-options.

Default: The GraphValueText style element.