About 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 Figure 24.5 on page 595 along with the value of the FUNCTION variable or Annotate macro that draws them.

Figure 24.5: 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

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 kinds 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. Figure 24.6 on page 597 shows the areas on the graphics output and the coordinate systems that use them.

  
  Figure 24.6: 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 on page 598.

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

Table 24.3 on page 597 describes the coordinate system values for the XSYS, YSYS, ZSYS, and HSYS variables.

Table 24.3: 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
[*] 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.

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 Procedure Output and the Graphics Output Area on page 34 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 on page 615.) 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 Figure 24.7 on page 599.

Figure 24.7: Programming Functions That Manipulate System Variables

For a complete description, see Annotate Internal Coordinates on page 678.

Attribute Variables

Attribute variables control the appearance of the graphics elements. Each function uses only a subset of these variables. See Table 24.1 on page 591 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 Annotate Variables on page 642.