Paper TU05 It s Not All Relative: SAS/Graph Annotate Coordinate Systems Rick Edwards, PPD Inc, Wilmington, NC ABSTRACT This paper discusses the SAS/Graph Annotation coordinate systems and how a combination of the systems can be used in the same annotation data set for the best results. The paper will also cover some basic introductory information on creating annotations. Two examples of how to use annotation datasets will be presented. The first example demonstrates how to add information to a plot which cannot be done with the Proc GPLOT procedure alone. The second illustrates how annotations may be used to enhance the clarity of a grouped bar chart. INTRODUCTION SAS/Graph is one of the primary presentation graphics components of the SAS system. It provides analysis and graphing tools to create plots, charts and maps with only a few SAS statements. Using options provided with the procedures in SAS/Graph, it is possible to produce graphical summaries of data that meet most clients needs with out of the box graphs. There are occasions, however, when the default graphs do not meet the exact specifications for presenting the data, or the nature of the data being presented causes the graph to lose clarity. In these cases, SAS/Graph s Annotate data set can be used to overcome the limitations of SAS/Graph s procedures to create a new type of graph from an existing one or to enhance the normal output of a graph. You can use the Annotate data set to place lines, bars, text or symbols on a graph. These graphic objects can be positioned on the graph using either the data from the graphed data set itself, or with coordinates provided by the programmer. Typically, the annotation involves a combination of the two. The positions of the graphic elements are specified by setting the x and y values for an element within one of SAS/Graph s 12 coordinate systems. Although 12 systems of coordinates may sound complicated, it allows flexibility when choosing where to place the annotation graphic elements. This paper will concentrate on smaller subset of the systems and, through the use of examples, will show that it is quite easy to obtain the desired results and to mix and match the various coordinate systems when assigning the coordinates of the annotate graphic elements. SAS/GRAPH S COORDINATE SYSTEMS The twelve different sets of coordinate systems are created by defining three different areas within a graph and provided 4 different ways to specify a coordinate within each area. The three areas are the Data area, defined as the rectangle bounded by the horizontal and vertical axes, the Graphics Output area, defined by the total area available to the device used to create the graph on the screen or other output medium, and the Procedure Output area, defined by the Graphics Output area minus any space used for title, footnotes and/or legends. Within each of these three areas, coordinates are either Absolute or Relative. Absolute coordinates identify the exact location of the x, y and z coordinates within the area. The values of relative coordinates give the offset in the x, y or z direction from the last Annotate location. Both absolute and relative coordinates can use one of two units in all three areas; either a percentage of each of the three areas, or data values in the Data area and cells in the Graphics and Procedure Output areas.
These 12 coordinate systems are listed in the table below: Area Unit Value Absolute Relative Data Percentages 1 7 Data Data values 2 8 Graphics Percentages 3 9 Graphics Cells 4 A Procedure Percentages 5 B Procedure Cells 6 C For this presentation, we will not use the Procedure area when specifying where the Annotate elements are located. Additionally, we will only use the units that do not change from one graphics output device to another. These are the data values in the data area and the percentages of each area. The sizes and number of cells in the Graphics and Procedure areas can vary depending on options specified and the output device s resolution. Therefore, we will use six of the coordinate systems in the examples: Data Area Values (Absolute and Relative), Data Area Percentages (Absolute and Relative) and Graphics Area Percentages (Absolute and Relative). The Annotate variables XSYS, YSYS, ZSYS and HSYS are used to identify which coordinate system is being used for the values of x, y, z and height respectively. As a further simplification, only x and y variables will be used In the annotations. The values assigned to the XSYS and YSYS variables to specify the coordinate system to associate with the coordinate values are listed in the table below. Area Unit XSYS/YSYS Values Absolute Relative Data Percentages 1 7 Data Data values 2 8 Graphics Percentages 3 9 EXAMPLE ONE: CREATING A WHISKER PLOT The first example of using annotation is very simple with respect to the graphics elements required (only three lines) and the number of coordinate systems used, but it illustrates the use of different coordinate systems in the same annotate data set. It is also a good example of how annotation can be used to produce a plot that otherwise would not be possible. A plot was desired that would show the average value and the standard error associated with the mean for the Physician s Global Assessment (PGA) for all subjects in two different treatment groups. Whiskers were specified to indicate the plus and minus values of the standard error. Classic box and whisker plots were not useful for this graph since the standard error, not 1.5 * the quartile value, was the measure for the whiskers. Instead, a simple plot of the PGA means over time with annotated whiskers was required. Basic plot After using Proc Means to calculate the PGA means and their standard error, the means data set is graphed using Proc Gplot. The resulting graph is shown below with the Proc GPLOT code. proc gplot data = pgameans; plot mean * visitday=trt / vaxis=axis1 haxis=axis2 legend=legend1 ; run;
Annotated whiskers Only three lines are required to create the whiskers for each mean point; the vertical line representing the plus and minus standard error difference from the mean and the top and bottom horizontal lines at the standard error points. Also, since all of the annotated lines lie within the graph area, the data set will only need to use the Graph Area Absolute and Relative coordinate systems. The annotate data set that will contain the graphic commands required to draw the lines is produced using the same data set used with Proc GPLOT. As each record in the graph data set is read, the x and y coordinates for drawing the lines will be derived from the Visit Day variable (x value) and the mean and standard error for the PGA Rating (y values). Annotated lines are drawn by moving to its starting point using the MOVE function and then drawing the line to its end point with the DRAW function. The code for the annotate data set follows: data ganno ; length function $8; set pgameans; /* DATA area used for all coordinate systems */ xsys='2'; ysys='2'; /* x & y data values */ function = 'move'; x = visitday; y = mean - std; output; xsys='7'; ysys='7'; /* x & y relative percents */ function = 'move'; x = -.5; y = 0; output; function = 'draw'; x = 1; y = 0; output; function = 'move'; x = -.5; y = 0; output; xsys='7'; ysys='2'; /* x - relative percent; y - absolute data value */ function = 'draw'; x = 0; y = mean + std; output; xsys='7'; ysys='7'; /* x & y relative percents */ function = 'move'; x = -.5; y = 0; output; function = 'draw'; x = 1; y = 0; output; run ; Note that the initial starting location, the bottom of the whisker) is identified using the x and y values of the data set that proc gplot will use for the graph points (minus the standard error for the y coordinate). The bottom horizontal portion of the whisker is then drawn using relative offsets for the x coordinates to move left ½ percent of the length of the horizontal axis, then drawing a line one percent of the axis in length, followed by a move back to the original starting location. The y coordinate offset is kept at zero to keep the line perfectly horizontal. This value would not have to be respecified for the draw and second move function, but is included on each function s line for clarity. The vertical line of the whisker is then drawn by setting the x relative offset to zero. The Y coordinate system is switched back to use absolute data values to position the end of the line one standard deviation above the mean point. Then the top of the whisker is drawn in the same manner as the bottom.
As with all programming, there is more than one way to arrive at the same result. An alternative method for creating the whiskers of the plot could use only one coordinate system. The example below uses data values exclusively to position the starting points and to draw the three lines. It also does not repeat the x or y values that will not change from one annotate function to the next. data ganno ; length function $8; set pgameans; xsys='2'; ysys='2'; /* x & y graph area data values */ function = 'move'; x = visitday -.75; y = mean - std; output; function = 'draw'; x = visitday + 1.5; output; function = 'move'; x = visitday -.75; output; function = 'draw'; y = mean + std; output; function = 'move'; x = visitday -.75; output; function = 'draw'; x = visitday + 1.5; output; run ; Deciding which of the two is the better method is largely a matter of personal preference and what seems clearer to the programmer. The two annotate data sets will create almost exactly the same output since the length of 1.5 in data value of the horizontal portions of the whiskers will be approximately one percent of the data area with the current range of the graph, which is approximately 125. One drawback of the second method becomes apparent if the data range changes or if the code is used with another x variable. Imagine the length of the whiskers if the data had a range of only 10 or 1.5. When percentages are used to draw elements of the annotation that are not related to the data, such as the horizontal portions of the whiskers in this case, they will always remain the same size regardless of the values that comprise the data area. To include the annotation elements in the graph, specify the annotate option on the plot statement and give the name of the annotate data set. proc gplot data = pgameans; plot mean * visitday=trt / vaxis=axis1 haxis=axis2 legend=legend1 annotate=ganno; run; The code above will produce the plot below.
The following annotate data set is a hybrid of the two previous methods for adding the whiskers to the plot. In this case, the y coordinate system remains the Data Absolute Values system throughout the data step with only the X coordinate system changing to Data Relative Percents after the initial position using the Data Area Absolute Values. Also, the x and y values are not explicitly defined for each record if the value doesn t need to change. I have introduced an error in this code, however, to illustrate that care must be taken if the x and y values are not explicitly set for each record. See if you can find the mistake. The answer will be given at the end of the paper. data ganno ; length function $8; set pgameans; xsys='2'; ysys='2'; /* x & y absolute data values */ function = 'move'; x = visitday; y = mean - std; output; xsys='7'; /* x data area relative percentage */ function = 'draw'; x = 1; output; /* y remains absolute data value */ function = 'draw'; y = mean + std; output; /* x remains relative */ function = 'draw'; x = 1; output; run ; EXAMPLE TWO: ENHANCING A SAS/GRAPH BAR CHART This example illustrates using coordinate systems to be place annotation outside of the graphics area. It shows how deficiencies in the default labeling of graphs can be overcome with annotation. Basic chart A study with 5 different treatments required a bar chart of all adverse events which had occurred two or more times across all of the treatments. The client wanted the information presented grouped by adverse event and subgrouped by treatment with each adverse event. The adverse events were presented in order the total number of occurrences for each event fro the largest number to the smallest. The following code is used to produce to basic bar chart. legend1 label=(h=1.2 "Cohort:" position=(top center)) position=(middle right outside) down=5; * cframe=ligr; axis1 label=(a=90 f=duplex r=0 h=1.1 "Number of Participants") major = (height=.5) width=10 color=black MINOR=NONE; * origin=(20 pct, 20 pct) ; axis2 label=none major=none width=10 color=black offset=(1,1) minor=none origin=(10 pct, 30 pct) value = none; axis3 label=none major=none width=10 color=black split=' ' order=( 'Lymphadenopathy' 'Urinary tract infection NOS' 'Headache NOS' 'Multiple sclerosis aggravated' 'Upper respiratory tract infection NOS' Vision blurred' 'Weakness') offset=(1,1) minor=none origin=(10 pct, 30 pct) value=none; proc gchart data=graphdata; vbar trt / width=1 group=preft subgroup=trt gspace=.75 raxis=axis1 gaxis=axis3 maxis=axis2 legend=legend1; pattern1 v=s c=blue; pattern2 v=s c=maroon; pattern3 v=s c=orange; pattern4 v=s c=green; pattern5 v=s c=red; run; The code above will produce the plot below.
There are several problems with the labels in the basic graph. First, one label is too long (default 32 character limit) and is truncated. Second, the first label cannot be split since it is one long word, and it runs into the second group s bars. Third, in order to have the groups arranged in descending order of number of occurrences instead of the default alphabetical order, the order must be explicitly specified in the axis statement. Alternatively, a variable specifying the order of the adverse events could be created and then formatted with the event s name to create the labels. In either case, the axis or format statement would have to be changed if the data changes and the relative order of the adverse events changed or if a new adverse event with 2 or more occurrences needed to be added to the graph. Annotated group labels data chart_annotation; length function color $ 8 position $ 1 text $ 25; retain hsys '3' when 'a' color 'black'; set preftct2; /* create angled labels */ /* use the annotate values, group & midpoint, for the x coord for the label */ xsys='2'; ysys='3'; /* x - data value ; y - absolute % graphics area */ function='label'; angle=-30; group=preft; midpoint=3; y=27; size=2; /* The code to set the actual text of the label is found at the end of this example s section, but is not shown here to save space and highlight the coordinate system code */ run; As in the first example, add the annotate elements to the graph by specifying the annotate option on the vbar statement. axis3 label=none major=none width=10 color=black offset=(1,1) minor=none origin=(10 pct, 30 pct) value=none; proc gchart data=graphdata; vbar trt / width=1 group=preft subgroup=trt gspace=.75 raxis=axis1 gaxis=axis3 maxis=axis2 legend=legend1 anno=chart_annotation; pattern1 v=s c=blue; pattern2 v=s c=maroon; pattern3 v=s c=orange; pattern4 v=s c=green; pattern5 v=s c=red; run; The code above will produce the plot below.
The x coordinate of the label s location is found using the data value for the adverse event s (identified by the variable, preft) group of bars. The MIDPOINT variable is an annotate variable which gives the coordinates of the horizontal middle (x) and the vertical top (y) of a bar. Since we have grouped bars, we have to identify which group of bars we want the midpoint of by using the GROUP annotate variable. To find the horizontal middle of the group, we use the middle bar of the group (the 3 rd bar). The MIDPOINT and the GROUP values for each bar are set by Proc GCHART. For the y coordinate, we use the absolute percent location that will be a little lower than the horizontal axis of the data area. The origin of the horizontal axis was specified to lie at 30 percent of the graphics output area (see axis3 statement in the original plot code). The label s text (see the end of this example) is derived from the data, so the labels change as the data changes making the program much more robust. This is repeated for each adverse event s group in the plot data set. Annotated group labels and tick marks Since the angled labels extend beyond the borders of their groups, tick marks can be added to help connect the labels to their groups. The code below can go either before or after the label annotate code. xsys='2'; ysys='3'; /* x - data; y - area * function = 'move'; group = preft; midpoint=3; y = 30; output; xsys='9'; ysys='9'; /* x & y - relative * function = 'draw'; x = 0; y = -1; output; The additional code above will produce the plot below.
The x coordinate for the start of the line is found in the same manner that we used to position the label. We set the y coordinate to the same position as the vertical location of the horizontal axis. Then, using relative percentages of the graphics area, we draw a vertical line down a length of one percent of the graphics area. Annotated group levels and brackets Due to the sparseness of the data in some of the adverse events, it is still difficult to distinguish the groups when the graph is viewed initially. At first glance, it may appear that the first and second groups are one group. The third and fourth groups also seem to merge into one group. A final enhancement to the graph is to create brackets instead of tick marks to connect the labels to their groups of bars. The code below shows how brackets can be created. xsys='2'; ysys='3'; /* x - data value ; y - absolute % graphics area */ function = 'move'; group = preft; midpoint=1; y = 30; output; xsys='9'; ysys='9'; /* x & y - relative % graphics area */ function = 'move'; x = -1; y = 0; output; function = 'draw'; x = 0; y = -1; output; xsys='2'; ysys='9'; /* x - data value; y - relative % graphics area */ function = 'draw'; group = preft; midpoint=5; y = 0; output; xsys='9'; ysys='9'; /* x & y - relative % graphics area */ function = 'draw'; x = 1; y = 0; output; function = 'draw'; x = 0; y = 1; output; xsys='2'; ysys='9'; /* x - data value; y - relative % graphics area */ function = 'move'; group = preft; midpoint=3; y = -1; output; xsys='9'; ysys='9'; /* x & y - relative % graphics area */ function = 'draw'; x = 0; y = -1; output; The additional code above will produce the plot below.
The bracket is started by finding the midpoint of the leftmost bar of the group (bar #1) and then using a slight additional horizontal offset to start the bracket just outside the each group of bars. After the left side of the bracket is drawn, the data values are used to draw the bottom of the bracket to the middle of the rightmost bar and then an additional line is drawn to just outside of the group. The bracket s right side is then drawn to the axis. The bracket is finished by moving to the middle of the group using data values for the x coordinate and the same relative y distance as the length of the bracket s sides. From this point, a tick mark is drawn from the bracket towards the group s label. Code to set the text of the label and output the label function */ /* if the label is no longer than 25 characters, it will fit on one line */ if length(trim(left(preft))) <= 25 then do; text=preft; position='6'; output; end; /* otherwise, break the label at the space closest to 25 characters */ else do; break = 0; spaces = 0; searchtext = trim(left(preft)); space = index(searchtext,' ') - 1; do while (break+space < 25 and space ne 0); spaces = spaces + 1; break = break + space + spaces; searchtext = substr(searchtext,break+1); space = index(searchtext,' ') - 1; end; text=substr(preft,1,break-1); position='c'; output; text=substr(preft,break-1); position='f'; output; end;
ERROR IN THE THIRD VERSION OF THE WHISKER PLOT EXAMPLE data ganno ; length function $8; set pgameans; xsys='2'; ysys='2'; /* x & y graph area data values */ function = 'move'; x = visitday; y = mean - std; output; xsys='9'; /* x graph area relative percentage */ function = 'draw'; x = 1; output; /* y (still) absolute data value */ function = 'draw'; y = mean + std; output; /* ERROR */ /* x (still) relative */ function = 'draw'; x = 1; output; run ; The value for x is still -.5 for this record. Since the coordinate system for x is Relative Percent, the line wouldnot be drawn perfectly vertical, but would be drawn at a slight slant to the left. The top bar of the whisker would still be centered on the vertical line, but would be offset by the additional -.5 percent as well. The line in error should be: function = 'draw'; x = 0; y = mean + std; output; CONCLUSION The Annotate Coordinate Systems are essential to establish the reference point for the coordinates values. Multiple systems may be used within the same annotate data set and even within one function. The most portable systems are the Data Area values and any of the percentage systems. When tying the annotation to the graphical data, the Data Area Value systems are the obvious choice. The Percentage coordinate systems are best suited for elements that are related to other non-data elements of a graph, such as starting an annotate element along an axis whose origin is specified by a percentage in its axis statement. The choice of using an Absolute coordinate system versus a Relative system is often a matter of the user s preference and comfort with either of those two options. Generally, a series of annotate functions will start with an absolute location and then subsequent functions in the series may use either relative or absolute to produce the same results. By concentrating on the six systems used in this presentation, a little practice with annotation is all that is required to become at ease with knowing which coordinate system to use to achive the desired results. CONTACT INFORMATION Your comments and questions are valued and encouraged. Contact the author at: Rick Edwards Programmer Analyst PPD Biostatistics 929 North Front Street Wilmington, NC 28401-3331 Tel: 910-558-7249 Fax: 919-654-0633 e-mail: richard.edwards@wilm.ppdi.com SAS and all other SAS Institute Inc. product or service names are registered trademarks or trademarks of SAS Institute Inc. in the USA and other countries. indicates USA registration. Other brand and product names are trademarks of their respective companies.