ODS Graphics Template Modification


The Graph Template Language

Graph template definitions begin with a DEFINE STATGRAPH statement in PROC TEMPLATE, and they end with an END statement. Embedded in every graph template is a BEGINGRAPH/ENDGRAPH block, and embedded in that block are one or more LAYOUT blocks. You can specify the DYNAMIC statement to define dynamic variables (which the procedure uses to pass values to the template definition), the MVAR and NMVAR statements to define macro variables (which you can use to pass values to the template definition), and the NOTES statement to provide descriptive information about the graph. The default templates that SAS supplies for statistical procedures are often lengthy and complex, because they provide ODS Graphics with comprehensive and detailed information about graph construction. Here is one of the simpler graph templates for a statistical procedure:

define statgraph Stat.MDS.Graphics.Fit;
   notes "MDS Fit Plot";
   dynamic head _byline_ _bytitle_ _byfootnote_;
   begingraph / designwidth=defaultdesignheight;
      entrytitle HEAD;
      layout overlayequated / equatetype=square;
         scatterplot y=FITDATA x=FITDIST / markerattrs=(size=5px);
         lineparm slope=1 x=0 y=0 / clip=true extend=true
            lineattrs=GRAPHREFERENCE;
      endlayout;
      if (_BYTITLE_)
         entrytitle _BYLINE_ / textattrs=GRAPHVALUETEXT;
      else
         if (_BYFOOTNOTE_)
            entryfootnote halign=left _BYLINE_;
         endif;
      endif;
   endgraph;
end;

This template, which is supplied for the MDS procedure, creates a scatter plot of two variables, FitData and FitDist, along with a diagonal reference line that passes through the origin. The plot is square and the axes are equated so that a centimeter on one axis represents the same data range as a centimeter on the other axis. The plot title is provided by the evaluation of the dynamic variable Head, which is set by PROC MDS. It is not unusual for this plot to contain hundreds or even thousands of points, so a five-pixel marker is specified, which is smaller than the seven-pixel marker that most styles use by default.

The IF/ELSE construction is common to most templates and enables ODS Graphics to optionally display a BY line with BY-group information as either a footnote or a second title line.

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

  • Control statements specify the 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 specify the arrangement of the components of the graph. Layout statements are arranged in blocks that begin with a LAYOUT statement and end with an ENDLAYOUT statement. The blocks can be nested. Within a layout block, there can be plot, text, and other statements that define one or more graph components. Options provide control for attributes of layouts and components.

  • Plot statements 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 the data columns from the data object that is used in the graph. For example, in the SCATTERPLOT statement, there are mandatory X= and Y= arguments that specify which data columns are used for the X (horizontal) and Y (vertical) axes in the plot. (In the preceding example, FitData and FitDist are the names of columns in the data object that PROC MDS creates for this graph.) There is also a GROUP= option that specifies a data column as an optional classification variable.

  • Text statements specify the descriptions that accompany graphs. An entry is any textual description, including titles, footnotes, and legends; it can include symbols to identify graph elements.

The following statements display another of the simpler template definitions—the definition of the scatter plot available in PROC KDE (see Output 66.6.1 in Chapter 66: The KDE Procedure):

proc template;
   define statgraph Stat.KDE.Graphics.ScatterPlot;
      dynamic _VAR1NAME _VAR1LABEL _VAR2NAME _VAR2LABEL
              _byline_ _bytitle_ _byfootnote_;
      BeginGraph;
         EntryTitle "Distribution of " _VAR1NAME " by " _VAR2NAME;
         Layout Overlay / xaxisopts=(offsetmin=0.05 offsetmax=0.05)
                          yaxisopts=(offsetmin=0.05 offsetmax=0.05);
            ScatterPlot x=X y=Y / markerattrs=GRAPHDATADEFAULT;
         EndLayout;
         if (_BYTITLE_)
            entrytitle _BYLINE_ / textattrs=GRAPHVALUETEXT;
         else
            if (_BYFOOTNOTE_)
               entryfootnote halign=left _BYLINE_;
            endif;
         endif;
      EndGraph;
   end;
run;

Here, the PROC TEMPLATE and RUN statements have been added to show how to compile the template if you want to modify it. The DEFINE STATGRAPH statement in PROC TEMPLATE begins the graph template definition, and the END statement ends the definition. The DYNAMIC statement defines four dynamic variables that PROC KDE sets at run time. Three additional DYNAMIC variables control the BY line. The dynamic variables _Var1Name and _Var2Name provide the variable names for the title of the graph. The dynamic variables _Var1Label and _Var2Label contain the labels of the X and Y variables, respectively. The title of the graph is specified by the ENTRYTITLE statement. You can change the ENTRYTITLE statement to display variable labels instead of variable names in the title. You can also use any of the dynamic variables elsewhere in the graph template.

The axes are controlled by the LAYOUT OVERLAY statement inside the BEGINGRAPH/ENDGRAPH statement block. The offset options add a small amount of padding between the axes and the most extreme points. The SCATTERPLOT statement creates the scatter plot. The options in the SCATTERPLOT statement are specified after the slash and control the marker attributes (symbol, color, and size). You can specify these attributes directly, as in the PROC MDS template, or more typically through style elements, as in the PROC KDE template. Style elements are defined in ODS styles, and elements can vary across different styles. For more information about ODS styles, see the section ODS Styles in Chapter 21: Statistical Graphics Using ODS. The ENDLAYOUT statement ends the main layout block. For information about the syntax of the graph template language, see the SAS Graph Template Language: Reference.

You can write your own templates and use them to display raw data or output from procedures. For example, consider the iris data from Example 35.1 of Chapter 35: The DISCRIM Procedure. The iris data set is available from the Sashelp library.

The following statements create a template for a scatter plot of the variables PetalLength and PetalWidth with a legend:

proc template;
   define statgraph scatter;
      begingraph;
         entrytitle 'Fisher (1936) Iris Data';
         layout overlayequated / equatetype=fit;
            scatterplot x=petallength y=petalwidth /
                        group=species name='iris';
            layout gridded / autoalign=(topleft);
               discretelegend 'iris' / border=false opaque=false;
            endlayout;
         endlayout;
      endgraph;
   end;
run;

The layout is OVERLAYEQUATED, which equates the axes in the plot. However, unlike the PROC MDS template, which used EQUATETYPE=SQUARE to make a square plot, the EQUATETYPE=FIT option specifies that the lengths of the axes in this plot should fill the entire plotting area. A legend is placed internally in the top-left portion of the plot. There are three groups of observations, indicated by the three species, and each group is plotted with a separate color and symbol that depends on the ODS style. The legend identifies each group. The NAME= option provides the link between the SCATTERPLOT statement and the DISCRETELEGEND statement. An explicit link is needed since some graphical displays are based on multiple plotting statements.

The following step creates the plot by using the SGRENDER procedure, the Sashelp.Iris data set, and the custom template scatter:

proc sgrender data=sashelp.iris template=scatter;
run;

The syntax of PROC SGRENDER is very simple, because all of the graphical options appear in the template. The scatter plot in Figure 22.1 shows the results.

The intent of this example is to illustrate how you can write a template to create a scatterplot. PROC TEMPLATE and PROC SGRENDER provide you with the power to create highly customized displays. However, usually you can use the SGPLOT, SGSCATTER or SGPANEL procedures instead, which are much simpler to use. These procedures are discussed in the section Statistical Graphics Procedures in Chapter 21: Statistical Graphics Using ODS. See the section Grouped Scatter Plot with PROC SGPLOT and Figure 21.12 in Chapter 21: Statistical Graphics Using ODS, for an example that plots these data with PROC SGPLOT.

Figure 22.1: Petal Width and Petal Length in Three Iris Species

Petal Width and Petal Length in Three Iris Species