MANAGING SAS/GRAPH DISPLAYS WITH THE GREPLAY PROCEDURE. Perry Watts IMS Health

Transcription

1 MANAGING SAS/GRAPH DISPLAYS WITH THE PROCEDURE Perry Watts IMS Health Abstract PROC is used for redisplaying graphs that have been stored in temporary or permanent catalogs. This tutorial will show how catalogs are created, populated, and managed so that graphs can be redisplayed in the current session or later on. While the replay command is demonstrated in an animated graphics example for a timed display of individual plots, the tutorial is primarily devoted to discussing issues related to treplay used for displaying multiple graphs on a page. A macro is also described that ends the drudgery of manually entering panel coordinates into a template. Templates can either be recalled from a catalog or now they can be simply recreated by exercising the macro. WORK.GSEG display default SAS/GRAPH graphics procedure which catalog other forms H yes Site other no temporary or permanent catalog stop GSF Introduction The procedure is an essential tool for reproducing graphs that have been stored in a catalog. Catalog entries can be created and retrieved with the GOUT and IGOUT commands. In addition, the name= and description= options in most graphics procedures enable developers to fully annotate their GRSEG (graphics segment) catalog entries. While works well for reproducing completed graphs, cataloging conventions are cumbersome for the programmer who is revising output in a non-batch environment. As figure 1 demonstrates all graphics output is stored in a catalog. This fact may not be so apparent, since default assignments are made in the absence of explicit definitions. For example, the following statements are identical: proc gslide; proc gslide gout=work.gseg; Names are also assigned by default to successive graphs generated by repeated executions of SAS code. For example, if a program invokes the GPLOT procedure three times, GPLOT, GPLOT1, and GPLOT2 will be generated the first time the program is executed, and GPLOT3, GPLOT4, and GPLOT5 are created in a second run. As we shall learn, this automatic naming convention can produce unpredictable results when the treplay procedure is used for producing multiple plots on a page. hardcopy Figure 1. A reproduction of Figure 44.1 in SAS/Graph Software Usage showing how graphics output is produced. The purpose of this tutorial is to understand how to use the resources available in SAS to display multiple graphs either in sequence or together on the same page. Initially commands associated with the procedure are defined. PROC is then exercised to show what problems are encountered when sets of revised graphs are plotted during a single programming session. Various solutions to the problems are discussed, and a versatile macro is described that creates template panels and optionally stores their coordinates in permanent catalogs. The paper concludes with an example of the replay feature that shows how shines in the production environment. Procedure statements are presented in line-mode where the nofs (no full screen) option is set. Commands While graphics output is automatically stored in catalogs, PROC needs to be invoked when graphs are redisplayed through templates, replayed in later sessions, or when catalog entries need to be modified. Individual plots developed in the current session can be redisplayed by simply cycling through the graphics output window in a full-screen device. The following command is used to initiate in line mode: proc greplay nofs;

2 Tables 1-3 below summarize features that will be used in the remainder of the paper. The summary is drawn from Chapter 36, The Procedure in SAS/GRAPH Software, Volume 2, Reference. Option IGOUT GOUT NOFS TC TEMPLATE Meaning Specifies the name of the input catalog. If IGOUT is not listed, input defaults to work.gseg. Specifies the output catalog. See above Specifies the name of the template catalog to use with. references a template entry by name within the template catalog specified by TC above. Table 1. There is a GOUT option associated with PROC as well as GOUT options attached to many graphics procedures. Statement COPY DELETE LIST REPLAY TDEF TREPLAY Meaning Copies entries from the IGOUT catalog to the GOUT catalog. Deletes catalog entries from the current catalog Entries in input and template catalogs are printed to the log file with the LIST statement. The REPLAY statement redisplays one or more entries from the current catalog. Entries can be designated by name or by number. TDEF defines or modifies template panels (panes) in the current template catalog. Options associated with TDEF can be found in table 3 below. selects one or more catalog entries for replay in template panels using the following syntax: panel#:entry-id panel# is defined in TDEF associated with the template and entry-id is the name or number of a particular catalog entry.. Table 2. statements applied to the IGOUT catalog. TDEF Option LLX LLY LRX LRY ULX ULY URX URY SCALEX SCALEY XLATEX XLATEY COLOR ROTATE Meaning Specifies X and Y coordinates in a panel:. (ULX, ULY) (URX, URY) (LLX, LLY) (LRX, LRY) U,L in the first character position references U(pper) and L(ower). L,R in the second position references L(eft) and R(ight). X and Y labels reference horizontal and vertical axes. Panels can be scaled independently in the X or Y direction. A value of 1 means no scale. A scale of less than one will increase the amount of space around a panel.. Specifies the distance to move a panel in the X or Y direction. Specifies the panel border color. Specifies the rotation angle of a panel in degrees. Table 3. TDEF options reference individual panels in a template. A more complete syntax of the procedure can be found by looking at the references in the bibliography. Revision Problems with Usually a graph needs to be modified a number of times before it is considered acceptable for production. Fonts, text sizes, line widths and color selections frequently have to be changed. Furthermore, multiple plot displays present additional difficulties that have to be handled. Individual plots, for example, must have a sufficient amount of space around them so that they can be distinguished from their neighbors. General titles need to be accommodated, and text that initially is large enough for a single plot display may turn out to be miniscule when 16 plots are grouped together on a single page Unfortunately does not work as expected when templates are involved. The difficulty can be traced to the lack of coordination between the default-naming scheme mentioned in the introduction and the way plots are referenced in treplay. Figure 2 shows a first run of a program displaying three plots and one title. By exercising the following code segment the plot names listed in the caption for figure 2 can be verified: proc greplay igout=work.gseg nofs; list igout;

3 4 4 Run #1 Figure 2. First run of a program automatically generates GPLOT, GPLOT1, GPLOT2, and GSLIDE catalog entries in work.gseg. At this point catalog names can be matched successfully with file names or numbers referenced in the treplay statement: treplay 1:1 2:2 3:3 4:4; or treplay 1:GPLOT 2:GPLOT1 3:GPLOT2 4:GSLIDE; Now, if the developer wants to modify any of the plots and change the title to Run #2, either catalog entry names have to be changed from their default values or treplay itself has to be altered. Otherwise the first run will just be replayed. By exercising the list igout command after the second run, one can see what is happening: 1 GPLOT I PLOT OF LEFTT * DAY 2 GPLOT1 I PLOT OF LEFTT * DAY 3 GPLOT2 I PLOT OF LEFTT * DAY 4 GSLIDE I OUTPUT FROM PROC GSLIDE 5 TEMPLATE I TEMPLATE GRAPH PRODUCED BY 6 GPLOT3 I PLOT OF LEFTT * DAY 7 GPLOT4 I PLOT OF LEFTT * DAY 8 GPLOT5 I PLOT OF LEFTT * DAY 9 GSLIDE1 I OUTPUT FROM PROC GSLIDE 1 TEMPLAT1 I TEMPLATE GRAPH PRODUCED BY To solve the problem with the second run, treplay could be re-written as: treplay 1:GPLOT3 2:GPLOT4 3:GPLOT5 4:GSLIDE1; or the plots could be renamed in PROC GPLOT: plot LeftT* RightT* /overlay name= PLOTA ; Given the need for making code revisions after each program run, mistakes are bound to occur. One way to avoid re-coding errors is to delete all work catalog entries at the beginning of each run. This purging action simulates what happens in a batch environment when control is returned to the operating system. The following macro deletes catalog entries by first checking to make sure the named catalog exists: %macro DelIfCaT(CatName); /*DelIfCatT means Delete if catalog is True (i.e. exists)*/ %if %sysfunc(cexist(&catname)) %then %do; proc greplay igout=&catname nofs; delete _all_; %end; %mend DelIfCaT; The macro is invoked in the sample program with: %DelIfCaT(work.gseg). This way new versions of GPLOT, GPLOT1, GPLOT2, and GSLIDE are created for each program run. To purge a graphics output window or file in addition to the catalog, set the value for goutmode or gsfmode to replace. The Macro for TDEF Typically many revisions are required before a programmer completes a graphics project. As mentioned previously, some of those revisions involve recalculating coordinates associated with template panels. Up to now, programmers could either create templates from scratch or retrieve them from catalogs. SASHELP.TMPLT contains about six predefined templates. Even with names and descriptions in a catalog directory, one should still preview the template to see how the panels are actually placed on a page. TDEF also builds a template one panel at a time. Panels are identified by an integer followed by a forward slash and the eight coordinates that define the panel boundaries. Optionally a panel can be scaled or translated in the vertical or horizontal direction, border colors can be defined, and overlapping panels can be clipped. A facility for rotation is also available. Below is a template definition for four panels: TDEF T1x3 1 / LLX=25 ULX=25 URX=75 LRX=75 LLY=5 ULY=1 URY=1 LRY=5 2 / LLX= ULX= URX=5 LRX=5 LLY= ULY=5 URY=5 LRY= 3 / LLX=5 ULX=5 URX=1 LRX=1 LLY= ULY=5 URY=5 LRY= 4 / LLX= ULX= URX=1 LRX=1 LLY= ULY=1 URY=1 LRY=;

4 Given all the available options for customization, the number of ways panels can be assembled into a template is infinite, and each time a change is required, the developer has to modify the affected coordinates in the catalog entry. Frequently when one panel is modified all the others have to be adjusted as well. Then what usually happens is that both versions of the template are kept resulting in larger catalogs that are more difficult to manage. The macro TmpltMac( ) copyrighted by the author and available upon request requires version 6.12 SAS to work. The graph introduced in figure 2 will be modified and annotated in figures 3 to 9 to demonstrate how the macro works. While only three plots are displayed in each of the figures below, the macro can accommodate up to eight rows of any number of panels. A trailing panel that covers 1% of the screen is automatically created so that undistorted general titles such as Run #2 can be printed out at the top of a page with the GSLIDE procedure. All of the smaller panels are the same size. 4 4 Run # Figure 3. The title Run #2 is obscured by the first plot, because ULY and URY values for ID #1 equal 1%. 4 Run #3 4 Figure 5. Run #4 now is completely visible, since the plots have been translated downwards Run # Run # Figure 6. The plots are spaced further apart, because they are now 95% their original size. 4 Run # Figure 4. Run #3 is more visible, since a 4% margin surrounds the three plots Figure 7. The plots are flipped so that two are now on the first row and one is on the second.

5 4 Run #7 4 4 Run # Figure 8. Left justify by creating two panels per row and leave the fourth panel blank Run # Figure 9. The three panels are placed next to each other with no space in between Run # Figure 1. Scale the plots to 5% in the vertical direction to reduce distortion and 9% in the horizontal direction to spread them apart. Figure 11. Right justify by leaving the third panel blank and translate the four panels to the right for a larger margin on the left. TempltMac( ) with its parameters tells the developer more about the layout of a set of panels in a template than the combination of a name and description in a catalog directory. For example, from the macro call below, we learn that the input graphics catalog is n98.ganno2. R1 +R2 or 6 panels will appear on a page in two rows with three panels each. NRows is the number of rows in the template, and MaxNCol is the number of panels in the longest row. R1 is the number of panels in Row#1, and R2 is the number of panels in Row#2. A 2.5% margin surrounds all the plots, and in this instance the plots have been translated 2.5% down the vertical axis with XLateY and 2.5% to the right with XLateX. In addition, each plot will be scaled to 9% of its original size with ScaleX and ScaleY. Lastly, a black border will offset the individual plots. %TmpltMac(igout=n98.ganno2, NRows=2, MaxNCol= 3, R1=3, R2=3, Margin=5, XLateY=-2.5,XlateX=2.5, ScaleX=.9, ScaleY=.9 color=black); Unlike TDEF that is oriented to the panel rather than to the template, values for XlateX, XLateY, ScaleX, ScaleY, Color, and Rotate are uniformly applied to all template panels except for the default title. Macro names are kept the same as TDEF names wherever possible. The height of each panel is determined by NRows, and the width by MaxNCol. Panels are always centerjustified, but if right-justification is desired, all one has to do is to create an extra panel which is not referenced in the treplay command. The following code generated the graph displayed in figure 11:

6 %TmpltMac(NRows=2, MaxNCol=2, R1=2, R2=2, Margin=8, XlateY=-4, XlateX=4, ScaleX=.95 ScaleY=.95); treplay 1:GPLOT 2:GPLOT1 4:GPLOT2 5:GSLIDE; Recall that the fifth panel that covers 1% of the screen is the default panel that is automatically generated inside the macro. Unless the mprint (macro print) option is turned on, the developer has no guaranteed access to the values of the coordinates calculated in TmpltMac( ). Given a margin and the possibility of different numbers of panels per row, coordinates frequently contain fractions. The following is pretty typical: TDEF TMPMAC 1 / LLX=26.25 ULX=26.25 URX=73.75 LRX=73.75 LLY=5 ULY=97.5 URY=97.5 LRY=5 SCALEX=1 SCALEY=1 XLATEY= / LLX=2.5 ULX=2.5 URX=5 LRX=5 LLY=2.5 ULY=5 URY=5 LRY=2.5 SCALEX=1 SCALEY=1 XLATEY= / LLX=5 ULX=5 URX=97.5 LRX=97.5 LLY=2.5 ULY=5 URY=5 LRY=2.5 SCALEX=1 SCALEY=1 XLATEY= / LLX= ULX= URX=1 LRX=1 LLY= ULY=1 URY=1 LRY=; TEMPLATE TMPMAC; RUN; Having to calculate such coordinates by hand for a template with 16 or more panels would truly be onerous, especially if many revisions had to be made. Interestingly, if the procedure is invoked in interactive mode, one can look at the values of the coordinates that are calculated after axes translations and scaling factors are performed. In other words, if ScaleX, ScaleY, XLateX or XLateY are set to any other values besides their defaults, template and macro values will not match. Creating Permanent Catalogs If the developer does not wish to rerun the macro in a later session to regenerate a template, TmpltMac( ) can be called in such a way that a final version of the template can be added to a permanent catalog. Relevant parameters are highlighted in the following invocation of TmpltMac( ): %TmpltMac(NRows=2, MaxNCol=2, R1=1, R2=2, Margin=8, XlateY=-4, ScaleX=.95 ScaleY=.95 tc=n98.tcat, TName=TR1R2); N98.Tcat (template-catalog) is created if it does not yet exist, and the template TR1R2 is added to it. Graphics output can also be stored in permanent catalogs with PROC Entries from work.gseg are copied to N98.GCat (Graphics-Catalog) in the following code segment: proc greplay igout=work.gseg gout=n98.gcat nofs; copy gplot; copy gplot1; copy gplot2; copy gslide; Template and graphics catalogs are independent of each other. Therefore, a program listing may contain a permanent graphics catalog and a work template catalog generated by the macro. Using for Animation Once a permanent graphics catalog has been created, the graphs can be replayed at will. The following brief program replays a series of graphs in sequential order to show how a left-branch binary tree traversal algorithm actually works: libname n98 e:\nesug\n98 ; goptions display rotate=landscape gwait=2; proc greplay igout=n98.ganno2 nofs; replay _1 _2 _3 _4 _5 _6 _7 _8 _9 _1 _11 _12 _13 _14 _15 _16 _17; The gwait clause in the goptions statement indicates that there is a two-second delay between the presentation of each catalog entry. With gwait, the operator doesn t have to press enter to advance to the next entry. Instead fullsize plots are automatically replayed in sequence so that the left-branch algorithm becomes an animated display. Since there is no way to demonstrate animation in a paper, TmpltMac( ) for treplay is again invoked in figure 12 to show the viewer how the plots in n98.ganno2 are organized. The color feature in TmpltMac( ) is used to place a black border around each plot in the display. Figure 13 shows off the rotate feature that is also accommodated by the macro.

7 References Carpenter, Arthur L. and Charles E. Shipp. Quick Results with SAS/GRAPH Software. Cary, NC: SAS Institute Inc., Jacobs, Marc. An Introduction to PROC. Proceedings of the Eighteenth Annual SAS Users Group International Conference. Cary, NC: SAS Institute Inc., 1993, Miron, Thomas. The How-To Book for SAS/GRAPH Software. Cary, NC: SAS Institute Inc., SAS/GRAPH Software, Usage, Version 6, First Edition. Cary NC: SAS Institute Inc., SAS/GRAPH Software, Volumes 1 and 2, Reference, Version 6, First Edition. Cary NC: SAS Institute Inc., 199. Figure 12. Frames 1, 2, 3 and 17 from n98. ganno2. Contact Information Perry Watts Senior Statistical Programmer IMS Health 66 W. Germantown Pike Plymouth Meeting, PA wattsp1@imsint.com Figure 13. Individual frames from the left-branch algorithm are rotated 18. Conclusion Two techniques for revising multiple plot displays have been presented in this tutorial. The first enables the developer to automatically purge catalogs between program runs, and the second makes it possible to reposition panels on a page without having to perform any mathematical calculations. With both of these techniques there is no need to change temporary names from their default values in a single programming session. Permanent catalogs can, however, be created for storing final versions of graphics output and template definitions. The replay feature in was also demonstrated in the tutorial to show how permanent catalogs make it possible to separate the development environment requiring code re-execution with input data from the production environment where catalog entries are simply redisplayed.