Chapter Contents

Previous

Next
SAS/GRAPH Software: Reference

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 values 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:

  1. Create a label. This instruction draws a blue 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.

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

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

  4. Draw the second line of the triangle.

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

[IMAGE]


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 variabale, 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

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


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


Chapter Contents

Previous

Next

Top of Page

Copyright 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.