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 on page 599.
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
Output 24.1 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 on page 600.)
 |
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.
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.
Figure 24.3 on page 591 shows the green title and the red triangle produced by the TRIANGLE data set and displayed with the GANNOChapter 26, The GANNO Procedure, on page 707 procedure. Notes on the figure in black contain the X and Y coordinates of the graphics elements.
Figure 24.3: 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.
Table 24.1 on page 591 lists all Annotate variables, grouped by task, and briefly describes each one. See Annotate Variables on page 642 for a complete description of each variable.
| Task Group | Variable | Description |
|---|---|---|
| Variable that defines an action | FUNCTION | specifies a drawing or programming action; Table 24.2 on page 594 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 XorY | |
| 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 | |
| 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 Figure 24.4 on page 593 for a table that shows you which Annotate functions are used with which Annotate variables.
Figure 24.4: Annotate Variables used with Annotate 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 on page 595.
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 on page 598, Using the LIFO Stack on page 603, and Debugging on page 604.
Table 24.2 on page 594 summarizes the tasks that are performed by the Annotate functions. See Annotate Functions on page 615 for a complete description of the FUNCTION variable and its values.
| 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 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 Figure 24.4 on page 593 for a table that shows you which Annotate functions work with which Annotate variables.
