Customizing Graphics with Templates | SAS/STAT 9.1 Users Guide, Volumes 1-7

This section describes how to locate templates for ODS Graphics, and how to display, edit, and save these templates. It also provides an overview of the graph template language. Before presenting these details, a review of the TEMPLATE procedure terminology is helpful.

A template definition is a set of SAS statements that can be run with the TEMPLATE procedure to create a compiled template. Two common types of template definitions are table definitions and style definitions . A table definition describes how to display the output for an output object that is to be rendered as a table, and a style definition provides formatting information for specific visual aspects of your SAS output.

A third type of template definition is a graph template definition (or graph definition for short), which controls the layout and details of graphs produced with ODS Graphics. Graph definitions begin with a DEFINE STATGRAPH statement and end with an END statement.

A template store is a member of a SAS data library that stores compiled templates created by the TEMPLATE procedure. Default templates supplied by SAS are saved in the Sashelp.Tmplmst template store.

In common applications of ODS Graphics, it should not be necessary to modify the default template for each graph, which is supplied by SAS. However, when cus-tomization is necessary, you can modify the default template with the graph template language in the TEMPLATE procedure.

If you are using the SAS windowing environment, the easiest way to display, edit, and save your templates is by using the Templates window. For detailed information about managing templates, refer to the TEMPLATE Procedure: Managing Template Stores in the SAS Output Delivery System User s Guide .

For details concerning the syntax of the graph template language, refer to the TEMPLATE Procedure: Creating ODS Statistical Graphics Output (Experimental) at http://support.sas.com/documentation/onlinedoc/base/.

Locating Templates

The first step in customizing a graph is to determine which template was used to create the original graph. The easiest way to do this is to specify the ODS TRACE ON statement prior to the procedure statements that created the graph. The fully qualified template name is displayed in the SAS log. This is illustrated in Example 15.7 and the section Using the Output Delivery System on page 274. Note that the ODS TRACE ON statement applies to graphs just as it does to tables.

Displaying Templates

Once you have found the fully qualified name of a template, you can display its definition using one of these methods :

Open the Templates window by typing odstemplates (or odst for short) in the command line, as shown in Figure 15.13. If you expand the Sashelp.Tmplmst icon, you can browse all the available templates and double-click on any template icon to display its definition. This is illustrated in Example 15.7.

Figure 15.13: Requesting the Templates Window in the Command Line
Use the SOURCE statement in PROC TEMPLATE to display a template definition in the SAS log. For example, the following statements display the default definition of the residual Q-Q plot in PROC ROBUSTREG.
```
  proc template;   source Stat.Robustreg.Graphics.ResidualQQPlot;   run;  
```

Editing Templates

You can modify the format and appearance of a particular graph by modifying its template. There are several ways to edit a template definition:

Find the template icon in the Templates window, right-click on the icon, and select Edit from the pull-down menu. This opens a Template Editor window in which you can edit the template definition. This approach is illustrated in Example 15.7.
Find the template icon in the Templates window and double-click on the template icon to display the template definition. Copy and paste the template definition into the Program Editor.
Use the SOURCE statement with the FILE= option in PROC TEMPLATE. This writes the template definition to a file that you can modify. For example:
```
  proc template;   source Stat.Robustreg.Graphics.ResidualQQPlot /   file = "qqtpl.sas";   run;  
```
By default the file is saved in the SAS current folder. Note that with this approach you have to add a PROC TEMPLATE statement before the template definition statements and a RUN statement at the end before submitting your modified definition.

Note: Graph definitions are self-contained and do not support parenting as do table definitions. For more information about graph definitions and the graph template language see the Introducing the Template Language for Graphics section on page 342.

Saving Customized Templates

After you edit the template definition you can submit your PROC TEMPLATE statements as you would for any other SAS program:

If you are using the Template Editor window, select Submit from the Run menu. For example, see Example 15.7.
Alternatively, submit your PROC TEMPLATE statements in the Program Editor.

ODS automatically saves the compiled template in the first template store that it can update, according to the currently defined ODS path. If you have not changed the ODS path , then the modified template is saved in the Sasuser.Templat template store. You can display the current ODS path with the following statement.

  ods path show;

By default, the result of this statement is displayed in the SAS log, as illustrated in Figure 15.14.

  Current ODS PATH list is:   1. SASUSER.TEMPLAT(UPDATE)   2. SASHELP.TMPLMST(READ)

Figure 15.14: Result of ODS PATH SHOW Statement

Using Customized Templates

When you create ODS output (either graphs or tables) with a SAS program, ODS searches sequentially through each element of the ODS PATH list for the first template that matches the ODS name of each output object requested . This template is used to produce the output object. If you have not changed the default ODS path, then the first template store searched is Sasuser.Templat , followed by Sashelp.Tmplmst .

Note that you can have templates with the same name in different template stores. The template that is used is the first one found in the ODS path.

The ODS PATH statement specifies which locations to search for definitions that were created by PROC TEMPLATE, as well as the order in which to search for them. You can change the default path by specifying different locations in the ODS PATH statement. For example, the following statement changes the default ODS path so that the first template store searched is Work.Mypath .

  ods path work.mypath(update) sashelp.tmplmst(read);

The UPDATE option provides update access as well as read access to Work.Mypath . The READ option provides read-only access to Sashelp.Tmplmst .

For more information, refer to the ODS PATH Statement in the Dictionary of ODS Language Statements ( SAS Output Delivery System User s Guide ).

Reverting to Default Templates

Customized templates are stored in Sasuser.Templat or in user-defined template stores. The default templates provided by SAS are saved in the read-only template store Sashelp.Tmplmst . Consequently, if you have modified any of the default templates and you want to create ODS Graphics with the original default templates, one way to do so is by changing your ODS path as follows .

  ods path sashelp.tmplmst(read) sasuser.templat(update);

A second approach, which is highly recommended, is to save all your customized templates in a user-defined template store (for example Work.Mypath ). Then you can reset the default ODS path with the ODS PATH RESET statement:

  ods path reset;

A third approach is to save your customized definition as part of your SAS program and delete the corresponding template from your Sasuser.Templat template store.

Example 15.7 illustrates all the steps of displaying, editing, saving and using customized templates.

Introducing the Template Language for Graphics

Graph template definitions are written in a graph template language , which has been added to the TEMPLATE procedure in SAS 9.1. This language includes statements for specifying plot layouts (such as grids or overlays), plot types (such as scatter plots and histograms), and text elements (such as titles, footnotes, and insets ). It also provides support for built-in computations (such as histogram binning ) and evaluation of expressions. Options are available for specifying colors, marker symbols, and other attributes of plot features.

Graph template definitions begin with a DEFINE STATGRAPH statement in PROC TEMPLATE, and they end with an END statement. You can specify the DYNAMIC statement to define dynamic variables, the MVAR and NMVAR statements to define macro variables , and the NOTES statement to provide descriptive information about the graph.

The statements available in the graph template language can be classified as follows:

Control statements , which specify conditional or iterative flow of control. By default, flow of control is sequential. In other words, each statement is used in the order in which it appears.
Layout statements , which specify the arrangement of the components of the graph. Layout statements are arranged in blocks which begin with a LAYOUT statement and end with an ENDLAYOUT statement. The blocks can be nested. Within a layout block, you can specify plot, text, and other statement types to define one or more graph components. Statement options provide control for attributes of layouts and components .
Plot statements , which specify a number of commonly used displays, including scatter plots, histograms, contour plots, surface plots, and box plots. Plot statements are always provided within a layout block. The plot statements include options to specify which data columns from the source objects are used in the graph. For example, in the SCATTERPLOT statement used to define a scatter plot, there are mandatory X= and Y= options that specify which data columns are used for the x -and y -variables in the plot, and there is a GROUP= option that specifies a data column as an optional classification variable.
Text statements , which specify descriptions accompanying the graphs. An entry is any textual description, including titles, footnotes, and legends, and it can include symbols to identify graph elements.

As an illustration, the following statements display the template definition of the scatter plot available in PROC KDE (see Output 36.7.1 in Chapter 36, The KDE Procedure ).

  proc template;   define statgraph Stat.KDE.Graphics.ScatterPlot;   dynamic _TITLE _DEPLABEL _DEPLABEL2;   layout Gridded;   layout overlay / padbottom = 5;   entrytitle _TITLE;   endlayout;   scatterplot x=X y=Y /   markersymbol = GraphDataDefault:markersymbol   markercolor  = GraphDataDefault:contrastcolor   markersize   = GraphDataDefault:markersize;   EndLayout;   end;   run;

The DEFINE STATGRAPH statement in PROC TEMPLATE creates the graph template definition. The DYNAMIC statement defines three dynamic variables. The variable _TITLE provides the title of the graph. The variables _DEPLABEL and _DEPLABEL2 contain the names of the x and y -variables, respectively. You can use these dynamic text variables in any text element of the graph definition.

The overall display is specified with the LAYOUT GRIDDED statement. The title of the graph is specified with the ENTRYTITLE statement inside a layout overlay block, which is nested within the main layout. The main plot is a scatter plot specified with the SCATTERPLOT statement. The options in the SCATTERPLOT statement, which are given after the slash, specify the symbol, color , and size for the markers using indirect references to style attributes of the form style-element:attribute . The values of these attributes are specified in the definition of the style you are using, and so they are automatically set to different values if you specify a different style. For more information about style references see the Styles for Graphics section on page 344.

The second ENDLAYOUT statement ends the main layout block and the END statement ends the graph template definition.

Note: Graph template definitions are self-contained and do not support parenting (inheritance) as do table definitions. The EDIT statement is not supported.