Using Annotate Data Sets

About the Annotate Data Set

In an Annotate data set, each observation represents a command to draw a graphics element or to perform an action. The graphic elements drawn by these commands can be added to SAS/GRAPH output or displayed with the GANNO or GSLIDE procedure as a custom graphic.

The observations in an Annotate data set use a set of predefined Annotate variables. The values of the variables in the observation determine what is done and how it is done. To create these observations, you assign values to the variables either explicitly with a DATA step or implicitly with Annotate macros. See Creating an Annotate Data Set.

The following sections describe the items in an Annotate data set and explain how SAS/GRAPH software uses the commands in an Annotate data set to create graphics elements.

Structure of An Annotate Data Set

Listing of the Annotate Data Set TRIANGLE is an example of an Annotate data set called TRIANGLE. The observations in this data set contain the commands that create a text label, move to a point in the output, and draw a triangle. (The DATA step that creates TRIANGLE is shown in Using the DATA Step.)

Listing of the Annotate Data Set TRIANGLE

  OBS   FUNCTION   X    Y   HSYS   XSYS   YSYS    STYLE    COLOR   POSITION  SIZE    LINE    TEXT

    1    label     20   85    3      3      3      swissb   green       6        6.0    .     Sample Annotate Graphics
    2    move      28   30    3      3      3      swissb   green       6        6.0    .     Sample Annotate Graphics
    3    draw      68   30    3      3      3      swissb   red         6        0.8    1     Sample Annotate Graphics
    4    draw      48   70    3      3      3      swissb   red         6        0.8    1     Sample Annotate Graphics
    5    draw      28   30    3      3      3      swissb   red         6        0.8    1     Sample Annotate Graphics

Note: A blank denotes a missing value for a character variable. A '.' denotes a missing value for a numeric variable. [cautionend]

Each observation in this data set contains complete instructions for drawing a graphic or moving to a position to draw a graphic. The value of the FUNCTION variable determines what the observation does. Other variables control how the function is performed. This list describes each observation in the TRIANGLE and the task it performs:

Create a label. This instruction draws a green label at position 20,85 (in X,Y coordinates). The value of the FUNCTION variable (LABEL) tells the program what to do. The values of the coordinate variables X and Y combined with the values of the coordinate system variables HSYS, XSYS, and YSYS tell where to do it. The values of the attribute variables STYLE, COLOR, TEXT, POSITION, and SIZE tell how to do it. These variables specify the font (SWISSB), the color and text of the label, the position of the label in relation to X and Y (centered on the point), and the size of the text.
Go to the starting point for the triangle. The value of the FUNCTION variable (MOVE) tells the program to go to the point specified by X and Y. This is the only instruction in the observation. Notice that the values of the variables specified for the first observation persist but are not used because they have no effect on the MOVE function.
Draw the first line of the triangle. The value of the FUNCTION variable (DRAW) tells the program to draw a line from the current point (the one specified by MOVE in the second observation to the new point specified by X and Y. The value of the COLOR variable changes to red.
Draw the second line of the triangle.
Draw the third line of the triangle.

Annotate Output from the TRIANGLE Data Set shows the green title and the red triangle produced by the TRIANGLE data set and displayed with the GANNO procedure. Notes on the figure in black contain the X and Y coordinates of the graphics elements.

Annotate Output from the TRIANGLE Data Set

[Annotate Output from the TRIANGLE Data Set]

Annotate Variables

Annotate variables have predefined names. In each observation, the Annotate facility looks only for variables with those names. Other variables can be present, but they are ignored. Conceptually, there are three types of variables:

an action variable	tells what to do. The only action variable is FUNCTION, which specifies what graphics element to draw (graphics primitive) or what action to take (programming function).
positioning variables	tell where to do it. The positioning variables specify the point at which to draw the graphics element.
attribute variables	tell how to do it. The attribute variables specify the characteristics of the graphics element (for example, color, size, line style, text font).

There is also an HTML variable, which provides linking information when you want to use the annotate data set to generate a drill-down graph that can be viewed in a Web browser.

Summary of Annotate Variables lists all Annotate variables, grouped by task, and briefly describes each one. See Annotate Variables for a complete description of each variable.

Summary of Annotate Variables
Task Group	Variable	Description
Variable that defines an action	FUNCTION	specifies a drawing or programming action; Summary of Graphics Tasks Performed by Annotate Functions describes these actions.
Positioning variables that determine coordinate values	GROUP	uses the value of the GCHART GROUP= option in place of X or Y
	MIDPOINT	uses the value of the GCHART MIDPOINT= option in place of X or Y
	SUBGROUP	uses the value of the GCHART SUBGROUP= option in place of X or Y
	X	specifies a numeric horizontal coordinate
	Y	specifies a numeric vertical coordinate
	Z	specifies a numeric third dimensional coordinate; used with G3D procedure only
	XC	specifies a horizontal character coordinate; only used with data coordinate systems 1, 2, 7, 8
	YC	specifies a vertical character coordinate; only used with data coordinate systems 1, 2, 7, 8
Positioning variables that contain internal coordinates	XLAST, YLAST	contain the X and Y coordinates of the last nontext function
	XLSTT, YLSTT	contain the X and Y coordinates of the last text function
Positioning variables that specify coordinate systems	HSYS	specifies type of units for the SIZE variable
	XSYS	specifies coordinate system for X or XC coordinates
	YSYS	specifies coordinate system for Y or YC coordinates
	ZSYS	specifies coordinate system for Z coordinate (G3D procedure only)
Attribute variables	ANGLE	angle of text label or starting angle of a pie slice
	CBORDER	colored border around text or symbol
	CBOX	colored box behind text or symbol
	COLOR	color of a graphics primitive
	IMGPATH	path to an image file to be displayed.
	LINE	line type to use in drawing or special control over pies and bars
	POSITION	placement and alignment for text strings
	ROTATE	angle at which to place individual characters in a text string or the delta angle (sweep) of a pie slice
	SIZE	size of an aspect of a graphics primitive; depends on FUNCTION variable (for TEXT, height of characters; for PIE, pie slice radius; for DRAW, line thickness; and so on)
	STYLE	font or pattern for a graphics element, depends on the FUNCTION variable
	TEXT	text to use in a label, symbol, or comment
	WHEN	whether a graphics element is drawn before or after procedure graphics output
Web variable	HTML	specifies link information for a drill-down graph

See Annotate Variables used with Annotate Functions for a table that shows you which Annotate functions are used with which Annotate variables.

Annotate Variables used with Annotate Functions

[Combining Annotate Variables and Functions]

Annotate Functions

The FUNCTION variable accepts a set of predefined values (functions) that perform both graphics tasks and programming tasks.

The graphics functions draw the graphics elements that are illustrated in Graphics Elements.

The programming functions control the internal coordinates, manipulate the LIFO stack, and help you debug an Annotate data set. These programming functions are discussed in Internal Coordinates, Using the LIFO Stack, and Debugging.

Summary of Graphics Tasks Performed by Annotate Functions summarizes the tasks that are performed by the Annotate functions. See Annotate Functions for a complete description of the FUNCTION variable and its values.

Summary of Graphics Tasks Performed by Annotate Functions
Task Group	If you want to...	Use this function...
Graphics tasks	begin to draw a polygon (starting point) and, optionally, specify a fill color and pattern	POLY
	continue drawing a polygon (additional vertex) and, optionally, specify an outline color of the polygon	POLYCONT
	draw an arrow from the current (X,Y) position (see MOVE and TXT2CNTL)	ARROW
	draw a line from the current (X,Y) position (see MOVE and TXT2CNTL)	DRAW
	draw a point	POINT
	draw a rectangle from the current (X,Y) position (see MOVE and TXT2CNTL); optionally, fill with a pattern	BAR
	draw a symbol	SYMBOL
	draw line from (XLAST, YLAST) coordinates to (XLSTT, YLSTT) coordinates	DRAW2TXT
	draw pie slice, circle, or arc	PIE
	draw text	LABEL
	move to the specified point (X,Y)	MOVE
	put a frame around the area defined by XSYS and YSYS, optionally, fill with a pattern	FRAME
Programming tasks	insert a comment in the data set (no action); documentation aid	COMMENT
	copy (XLAST, YLAST) coordinates to (XLSTT, YLSTT) coordinates	CNTL2TXT
	copy (XLSTT, YLSTT) coordinates to (XLAST, YLAST) coordinates	TXT2CNTL
	exchange LSTT and LAST coordinates	SWAP
	get coordinates of a point on a pie slice outline	PIEXY
	get values for LAST and LSTT coordinates from LIFO stack	POP
	put current values of LAST and LSTT coordinates onto LIFO stack	PUSH
	set pie radius and coordinates for center; does not draw a pie	PIECNTR
	turn on trace of previous values and LIFO stack	DEBUG

See Annotate Variables used with Annotate Functions for a table that shows you which Annotate functions work with which Annotate variables.

Top of Page