Annotate Processing Details

Order in Which Graphics Elements Are Drawn

When a procedure uses an Annotate data set, it reads and interprets the observations one at a time, starting with the first observation and proceeding to the last. The order of the observations in the data set determines the order in which the graphics elements are generated. If the coordinates of two graphics elements overlap, the graphics element produced by an earlier observation can be overwritten by any graphics elements that are produced by subsequent observations. As a result, graphics elements can overlay each other and they can also overlay or be overlaid by procedure output.

CAUTION:

• Overlay behavior is device-dependent. Most terminals, cameras , and some printers demonstrate overlay behavior because the process of drawing updates pixels as each graphics element is drawn. Plotters do not overlay the graphics elements internally before plotting; they draw graphics elements on top of each other on the paper. The area where graphics elements overlap shows one color bleeding through the color that overlays it. To ensure that one graphics element overlays another, use the WHEN variable.

Controlling the Processing with the WHEN Variable

The WHEN variable determines the order in which observations in an Annotate data set are processed. It determines if observations are processed before or after output that is produced by a SAS/GRAPH procedure. This means that Annotate graphics can be overlaid by procedure output or can overlay procedure output. By default, Annotate graphics are drawn before the procedure output.

In effect, you can have two sets of Annotate graphics elements that are generated for the same output:

• Annotate graphics drawn before procedure output (the default, WHEN= B ).

• Annotate graphics drawn after procedure output (WHEN= A ).

Within each set, graphics elements are drawn in the order that they appear in the Annotate data set and overlay each other as appropriate (on devices that demonstrate overlay behavior). For details, see the description of the WHEN variable on WHEN Variable on page 666.

Using BY- Group Processing with the Annotate Facility

You can use the Annotate facility with procedures that use BY statements to annotate each graph that is generated with a BY statement. The Annotate graphics for each graph are generated depending on the value of the BY variable. To use BY-group processing with the Annotate facility, your program must meet the following conditions:

• Both the input data set for the procedure and the Annotate data set must contain the same BY variable.

• The BY variable must be defined as the same type (character or numeric) and length in both data sets.

• If a label or format is associated with a BY variable in one data set, the same label or format has to be associated with it in the other data set.

• Both data sets must be sorted by the BY variable.

• The ANNOTATE= option must be specified in an action statement in the procedure. If you specify the ANNOTATE= option in the PROC statement, the Annotate graphics are used for all graphs that are generated by the procedure rather than for unique values of the BY variable.

See BY Statement on page 141 for details.

Using the LIFO Stack

The FUNCTION variable supports several programming functions that manipulate the internal coordinates and provide other utility operations. Several of these functions use the LIFO stack to track and set variable values.

The LIFO (last-in-first-out) stack is a storage area where you can keep internal coordinate values for later use. It is useful when you want to save the current values of (XLAST,YLAST) and (XLSTT,YLSTT) and use them with functions later in the DATA step.

You store and retrieve values from the stack using the PUSH and POP functions. The PUSH function copies the current values of XLAST, YLAST, XLSTT, and YLSTT onto the stack. The POP function copies values from the stack into XLAST, YLAST, XLSTT, and YLSTT.

LIFO stacks manage the stored data so that the last data stored in the stack is the first data removed from the stack. This means that a POP function retrieves the values most recently stored with a PUSH function. Figure 24.8 on page 603 illustrates how PUSH and POP functions work together.

Figure 24.8: Using PUSH and POP to Store and Retrieve Coordinate Values

See also Internal Coordinates on page 598.

Debugging

You can print your Annotate data set with the PRINT procedure. This is an easy way to examine the Annotation that you have specified or to debug your program. For example, a listing such as the one in Output 24.1 provides complete information about the value that you specify for each variable in every observation.

For more complex problems, the DEBUG function enables you to display the values of Annotate variables and internal coordinates before and after a function is submitted. The values are written to the SAS log.

If there is an error in your Annotate data set, one or more diagnostic messages are printed in the SAS log:

• If an error is found in preprocessing, this message appears:

   NOTE: ERROR DETECTED IN ANNOTATE=  libref.dataset  

• If an error is found as an observation is being read, this message appears:

   PROBLEM IN OBSERVATION  number  -  message  

  where message is the text of the error message.

• If the error limit of 20 errors is reached at any point during processing of the data set, a termination message similar to this one appears:

   ERROR LIMIT REACHED IN ANNOTATE PROCESS                20 TOTAL ERRORS 

For an explanation of common diagnostic messages, refer to the Help facility.