About Annotate Graphics :: SAS/GRAPH(R) 9.3: Reference, Third Edition

Overview of Annotate Graphics

When you create Annotate graphics, you specify these things:

what to draw (graphics elements)
where to draw those elements (the coordinates of the position on the output)
how to draw (characteristics of the element such as size or color).

The following sections describe the components of the graphics output that are produced by an Annotate data set.

Graphics Elements

In an Annotate data set, the FUNCTION variable determines the graphics element that is drawn.

The particular graphics elements that you can draw are shown in Annotate Graphics Elements along with the value of the FUNCTION variable or Annotate macro that draws them.

Annotate Graphics Elements

You can control the position of graphics elements in the following ways:

explicitly, using coordinates that you supply.
dependently, based on the location of features in the SAS/GRAPH output. For example, when you use the GCHART procedure, you can label the parts of a subgrouped vertical bar chart by using the SUBGROUP variable in your Annotate data set. The Annotate facility enables you to label subgroups without having to specify the actual coordinates of the subgroup bar.
dependently, based on values that are supplied from other data sets. For example, you can label the ending point of a plot line in the GPLOT procedure by extracting the value of the last point in the sorted input data set.

Coordinates

Coordinates specify where to put graphics elements. These variables can contain coordinate values:

X, Y, and sometimes Z are used for numeric coordinates.
XC and YC are used for character coordinates.
GROUP, MIDPOINT, and SUBGROUP can be used when you annotate output from procedures such as GCHART. Use these variables to specify coordinates for horizontal or vertical bar charts.

Coordinates are interpreted in terms of a coordinate system in order to identify a precise location in the graphics output.

Coordinate Systems

Overview of Coordinate Systems

A coordinate system determines how coordinates are interpreted. You specify a coordinate system to use for each dimension, using the XSYS, YSYS, and ZSYS variables (for X, Y, and Z, respectively). Use ZSYS to annotate graphics output only from the G3D procedure.

You also specify a coordinate system for the SIZE variable using the HSYS variable. HSYS takes the same types of values as XSYS, YSYS, and ZSYS. The SIZE variable specifies the size of a graphics element, such as the width of lines (for example, FRAME), the radius of pie slices (for example, PIE, PIECNTR, and PIEXY), or the height of text (for example, LABEL and SYMBOL).

These are the important components of the Annotate coordinate systems:

Area: Each coordinate system refers to one of three drawing areas: data area, procedure output area, and graphics output area. Coordinates are measured from a different origin for each area; they also have different limits. Areas and Their Coordinate Systems shows the areas on the graphics output and the coordinate systems that use them.

Areas and Their Coordinate Systems

Units: The units for a coordinate system are based on one of the following:
- data values (for data coordinate systems). The range of values depends on the range of data expressed along the axes of the graph.
- cells (for coordinate systems for the procedure output area or graphics output area). The range of values depends on the type of area. See Ranges for Cells.
- percentages of the total area available, that is, percent of the data area, or percent of the procedure output area, or percent of the graphics output area.
Placement: The placement of a coordinate can be absolute or relative. Absolute coordinates name the exact location for a graphics element in the graphics output. Relative coordinates name the location with respect to another graphics element in the output.

Coordinate System Values for XSYS, YSYS, ZSYS, and HSYS Variables describes the coordinate system values for the XSYS, YSYS, ZSYS, and HSYS variables.

Coordinate System Values for XSYS, YSYS, ZSYS, and HSYS Variables

Type of Coordinates	Area	Units	Range	Value for XSYS, YSYS, ZSYS, HSYS
Absolute	data	%	0-100% of axis	'1' *
	data	values	minimum to maximum of axis	'2' *
	graphics output area	%	0-100% of graphics output area	'3'
	graphics output area	cells	0 to limit of graphics output area	'4'
	procedure output area	%	0-100% of procedure output area	'5'
	procedure output area	cells	0 to limit of procedure output area	'6'
Relative	data	%	0-100% of axis	'7' *
	data	values	minimum to maximum of axis	'8' *
	graphics output area	%	0-100% of graphics output area	'9'
	graphics output area	cells	0 to limit of graphics output area	'A'
	procedure output area	%	0–100% of procedure output area	'B'
	procedure output area	cells	0 to limit of procedure output area	'C'
N/A	Text font point size	N/A	0 to limit of graphics output area	'D'**
Coordinate systems 1, 2, 7, and 8 are not valid with block, pie or star charts in the GCHART procedure or surface, prism or block maps with the GMAP procedure. In addition, coordinate systems 2 and 8 are not valid with radar charts in the GRADAR procedure. *Coordinate system D is used only for text functions such as LABEL. For functions that do not create text, a warning appears in the log and the 4 coordinate system is used.

Ranges for Cells

The available range for coordinate systems that are measured in cells differs by area:

graphics output area

The range of cells that are available for the graphics output area depends on the device and the number of rows and columns that are set by the HPOS= and VPOS= graphics options or by the PCOLS and LCOLS device parameters.

procedure output area

As with the graphics output area, the range of cells available for the procedure output area depends on the device and the number of rows and columns set by the HPOS= and VPOS= graphics options or by the PCOLS and LCOLS device parameters. However, the procedure output area is sized after areas for titles and footnotes are allocated and is reduced accordingly. If you specify that the legend appear outside of the axis area, the procedure output area also decreases by the size of the legend.

See Overview for descriptions of the procedure output area and the graphics output area.

Internal Coordinates

The Annotate facility maintains two pairs of internal coordinates that are stored in internal variables:

coordinates of the last graphics element drawn or the coordinates from the last move are stored in the variables XLAST and YLAST
coordinates of the last text drawn are stored in the variables XLSTT and YLSTT.

Many functions use these internal coordinates as a starting point, relying on the coordinates that are specified with the function as an ending point. For example, in the BAR function, the (XLAST, YLAST) coordinate pair is used for the lower left corner; the position defined by the X and Y variables is used for the upper right corner. (For details, see BAR Function.) These internal variables can also provide default coordinates if X, XC, Y, or YC contains a missing value.

The internal coordinates are automatically updated by some of the Annotate functions. The text functions, LABEL and SYMBOL, update the (XLSTT,YLSTT) variables. The BAR, DRAW, MOVE, PIE, and POINT functions update the (XLAST,YLAST) variables.

You cannot explicitly assign a value to XLAST, YLAST, XLSTT, or YLSTT because they are internal variables. For example, you cannot make this assignment:

xlast=50;

However, you can use several functions to directly manipulate the values of the internal coordinates. The functions are shown in Programming Functions That Manipulate System Variables.

Programming Functions That Manipulate System Variables

For a complete description, see Annotate Internal Coordinates.

Attribute Variables

Attribute variables control the appearance of the graphics elements. Each function uses only a subset of these variables. See Summary of Annotate Variables for a list of attribute variables.

What an attribute variable controls often depends on the graphics element to which it applies. For example, the SIZE variable controls the width of a line when it is used with FUNCTION='DRAW', but it controls the text height when it is used with FUNCTION='LABEL'.

For a complete description of the attribute variables and the aspect of the graphics elements that they control, see About the Annotate Variables.