BEGINGRAPH Statement

Defines the outermost container for a graph template that is defined with GTL-statements.

Requirements: All STATGRAPH template definitions must start with a BEGINGRAPH statement and end with an ENDGRAPH statement.
The BEGINGRAPH block must contain one and only one layout block.
The layout block and its nested layouts, if any, must contain at least one plot.

Syntax

BEGINGRAPH </option(s)>;
<GTL-global-statements>
GTL-layout-block
<GTL-global-statements>
ENDGRAPH;

Summary of Optional Arguments

Appearance options

ATTRPRIORITY=AUTO | COLOR | NONE

specifies a priority for cycling the group attributes.

BACKGROUNDCOLOR=style-reference | color

specifies the color of the graph background.

BORDER=TRUE | FALSE

specifies whether a border is drawn around the graph.

BORDERATTRS=style-element | style-element (line-options) | (line-options)

specifies the attributes of the border line around the graph.

DATACOLORS=(color-list)

specifies the list of fill colors that will replace the graph data colors from the GraphData1–GraphDataN style elements.

DATACONTRASTCOLORS=(color-list)

specifies the list of contrast colors that will replace the graph data contrast colors from the GraphData1–GraphDataN style elements.

DATALINEPATTERNS=(line-pattern-list)

specifies the list of line patterns that will replace the graph data line patterns from the GraphData1–GraphDataN style elements.

DATASKIN=NONE | CRISP | GLOSS | MATTE | PRESSED | SHEEN

enhances the visual appearance of all plots in the template that support data skins.

DATASYMBOLS=(marker-symbol-list)

specifies the list of marker symbols that will replace the graph data marker symbols from the marker symbols that are defined in the GraphData1–GraphDataN style elements.

DESIGNHEIGHT=DEFAULTDESIGNHEIGHT | dimension

specifies the design height of the graph.

DESIGNWIDTH=DEFAULTDESIGNWIDTH | dimension

specifies the design width of the graph.

DRAWSPACE= GRAPHPERCENT | GRAPHPIXEL | LAYOUTPERCENT | LAYOUTPIXEL | WALLPERCENT | WALLPIXEL | DATAPERCENT | DATAPIXEL | DATAVALUE

specifies a global drawing space and drawing units for all of the draw statements within this BEGINGRAPH block.

PAD=dimension | (pad-options)

specifies the amount of extra space that is added inside the graph border.

SUBPIXEL=AUTO | ON

specifies whether subpixel rendering is used when a graph is rendered.

Label options

LABELPLACEMENT=AUTO | GREEDY | SA

specifies the label-placement algorithm to use for positioning labels in the graphs.

SAPLACEMENTOPTS=(placement-options)

specifies the options for the label-placement algorithm when LABELPLACEMENT=SA.

Midpoint options

INCLUDEMISSINGDISCRETE=TRUE | FALSE

specifies whether missing values are displayed on a discrete axis.

Optional Arguments

ATTRPRIORITY=AUTO | COLOR | NONE

specifies a priority for cycling the group attributes.

AUTO

honors the current state of the attribute priority rotation pattern as specified in the active style or in the ODS GRAPHICS statement.

COLOR

changes the current setting of attribute priority rotation pattern to the color-priority pattern by cycling through the list of colors while holding the marker symbol, line pattern, or fill pattern constant. When all of the colors are exhausted, the marker symbol, line style, or fill pattern attribute increment to the next element, and then the colors in the list are repeated. This pattern repeats as needed.

NONE

changes the current setting of attribute priority rotation pattern to the default pattern, which cycles progressively through the attribute lists.

Default The attribute priority pattern that is specified in the active style or in the ODS GRAPHICS statement.
Interactions This option overrides the attribute priority rotation pattern that is specified in the current style and the ATTRPRIORITY= option in the ODS GRAPHICS statement.
The default lists of data colors, contrast colors, marker symbols, and line patterns are set in the active style’s GraphData1–GraphDataN elements.
The individual attributes in these lists can be overridden with the BEGINGRAPH options DATACOLORS=, DATACONTRASTCOLORS=, DATALINEPATTERNS=, and DATASYMBOLS=.
The ATTRPRIORITY= option affects the cycling of the style attributes for GROUP=, CYCLEATTRS=TRUE, and explicit style references such as MARKERATTRS=GraphData2.
See Attribute Rotation Patterns in SAS Graph Template Language: User's Guide

BACKGROUNDCOLOR=style-reference | color

specifies the color of the graph background.

style-reference

specifies a style reference in the form style-element:style-attribute. Only the style attribute named COLOR or CONTRASTCOLOR is used.

Default The GraphBackground:Color style reference.

BORDER=TRUE | FALSE

specifies whether a border is drawn around the graph.

Default The ODS GRAPHICS statement BORDER= option setting, which is TRUE by default.
Interaction If this option is set to FALSE, then the BORDERATTRS= option is ignored.
See boolean for other Boolean values that you can use.

BORDERATTRS=style-element | style-element (line-options) | (line-options)

specifies the attributes of the border line around the graph.

Default The GraphBorderLines style element.
Interaction BORDER=TRUE must be set for this option to have any effect.
See General Syntax for Attribute Options for the syntax on using a style-element .
Line Options for available line-options.

DATACOLORS=(color-list)

specifies the list of fill colors that will replace the graph data colors from the GraphData1–GraphDataN style elements.

(color-list)

a space-separated list of colors, enclosed in parentheses. You can use a style attribute reference such as GraphData3:color, a color name, or an RGB, CMYK, HLS, or HSV (HSB) color code to specify a color. The list can contain a mix of style attribute references, color names, and color codes.

Requirement The list of colors must be enclosed in parentheses.
Example
datacolors=(CXFF0000 green blue)
When this option is specified, the fill colors rotate through this color list rather than through the colors that are defined in the GraphData1–GraphDataN style elements. For information about the attribute rotation patterns, see Attribute Rotation Patterns in SAS Graph Template Language: User's Guide.
Default The colors that are defined in the GraphData1–GraphDataN style elements.
Interaction Where applicable, the COLOR= suboption of the FILLATTRS= option overrides the DATACOLORS= option.

DATACONTRASTCOLORS=(color-list)

specifies the list of contrast colors that will replace the graph data contrast colors from the GraphData1–GraphDataN style elements.

(color-list)

a space-separated list of contrast colors, enclosed in parentheses. You can use a style attribute reference such as GraphData3:color, a color name, or an RGB, CMYK, HLS, or HSV (HSB) color code to specify a color. The list can contain a mix of style attribute references, color names, and color codes.

Requirement The list of colors must be enclosed in parentheses.
Example
datacontrastcolors=(orange cyan #FF0000)
When this option is specified, the contrast colors cycle through this color list rather than through the contrast colors that are defined in the GraphData1–GraphDataN style elements. For information about the attribute rotation patterns, see Attribute Rotation Patterns in SAS Graph Template Language: User's Guide.
Default The contrast colors that are defined in the GraphData1–GraphDataN style elements.
Interaction Where applicable, the COLOR= suboption of the MARKERATTRS= option or the LINEATTRS= option overrides the DATACONTRASTCOLORS= option.

DATALINEPATTERNS=(line-pattern-list)

specifies the list of line patterns that will replace the graph data line patterns from the GraphData1–GraphDataN style elements.

(line-pattern-list)

a space-separated list of line patterns, enclosed in parentheses. You can use a style attribute reference such as GraphData3:lineStyle, a line pattern number, or a line pattern name (where applicable) to specify a pattern. The list can contain a mix of style attribute references, line pattern numbers, and line pattern names.

Requirement The list of line patterns must be enclosed in parentheses.
When this option is specified, the line patterns cycle through this line-pattern list rather than through the line patterns that are defined in the GraphData1–GraphDataN style elements. When the patterns in line-pattern-list are exhausted, the patterns repeat.
Default The line patterns that are defined in the GraphData1–GraphDataN style elements.
Interaction Where applicable, the PATTERN= suboption of the LINEATTRS= option overrides the DATALINEPATTERNS= option.
Example
datalinepatterns=(solid dash 16 26)

DATASKIN=NONE | CRISP | GLOSS | MATTE | PRESSED | SHEEN

enhances the visual appearance of all plots in the template that support data skins. The following plot statements support data skins:

BARCHART HISTOGRAM SCATTERPLOT
BARCHARTPARM HISTOGRAMPARM SCATTERPLOTMATRIX
BOXPLOT LINECHART SERIESPLOT
BOXPLOTPARM NEEDLEPLOT STEPPLOT
BUBBLEPLOT PIECHART VECTORPLOT
DROPLINE POLYGONPLOT WATERFALLCHART
HIGHLOWPLOT REFERENCELINE
Default The GraphSkins:DataSkin style attribute, if it is specified in the current style. If the current style does not specify the GraphSkins:DataSkin style attribute, then the default is NONE.
Restriction Starting with the first maintenance release of SAS 9.4, the maximum number of skinned graphical elements is limited to 200 per plot in an overlay or prototype layout. When this limit is exceeded for a plot, the specified data skin is not applied to that plot. In that case, use the DATASKINMAX= option in your ODS GRAPHICS statement to increase the maximum limit.
Interaction This option is overridden by the DATASKIN= option in the individual plot statements.
Note Applying data skins to a graph that has a very large number of markers can negatively impact performance.

DATASYMBOLS=(marker-symbol-list)

specifies the list of marker symbols that will replace the graph data marker symbols from the marker symbols that are defined in the GraphData1–GraphDataN style elements.

(marker-symbol-list)

a space-separated list of marker symbols, enclosed in parentheses. You can use a style attribute reference such as GraphData5:markerSymbol or a marker symbol name to specify a marker. The list can contain a mix of style attribute references and marker symbol names.

Requirement The list of marker symbols must be enclosed in parentheses.
When this option is specified, the marker symbols cycle through this marker symbol list rather than through the line patterns that are defined in the GraphData1–GraphDataN style elements. When the symbols in marker-symbol-list are exhausted, the symbols repeat.
Default The marker symbols that are defined in the GraphData1–GraphDataN style elements.
Interaction Where applicable, the SYMBOL= suboption of the MARKERATTRS= option overrides the DATASYMBOLS= option.
Example
datasymbols=(circle square triangle star)

DESIGNHEIGHT=DEFAULTDESIGNHEIGHT | dimension

specifies the design height of the graph.

Default DEFAULTDESIGNHEIGHT. This value is obtained from the SAS Registry key ODSthen selectODS Graphicsthen selectDesign Height when the graph is rendered. The initial value of this registry key is 480px.
Restriction The minimum dimension value that you can set is 2 pixels. If a smaller setting is specified, then the default design height is used.
Interactions The design height can be overridden at run time with a render height that is specified with the HEIGHT= option in the ODS GRAPHICS statement (external to the template). Also, the ODS destination statement’s IMAGE_DPI= option can affect the height.
You can change the value of the Design Height registry key in the SAS registry. However, doing so affects the design height of all templates that do not include an explicit dimension for the design height. You can also change the height setting in the graph style, but doing so affects the height of all templates that use that style.
See dimension

DESIGNWIDTH=DEFAULTDESIGNWIDTH | dimension

specifies the design width of the graph.

Default DEFAULTDESIGNWIDTH. This value is obtained from the SAS Registry key ODSthen selectODS Graphicsthen selectDesign Width when the graph is rendered. The initial value of this registry key is 640px.
Restriction The minimum dimension value that you can set is 2 pixels. If a smaller setting is specified, then the default design width is used.
Interactions The design width can be overridden at run time with a render width that is specified with the WIDTH= option in the ODS GRAPHICS statement (external to the template). Also, the ODS destination statement’s IMAGE_DPI= option can affect the width.
You can change the value of the Design Width registry key in the SAS registry. However, doing so affects the design width of all templates that do not include an explicit dimension for the design width. You can also change the width setting in the graph style, but doing so affects the width of all templates that use that style.
See dimension

DRAWSPACE= GRAPHPERCENT | GRAPHPIXEL | LAYOUTPERCENT | LAYOUTPIXEL | WALLPERCENT | WALLPIXEL | DATAPERCENT | DATAPIXEL | DATAVALUE

specifies a global drawing space and drawing units for all of the draw statements within this BEGINGRAPH block.

Default LAYOUTPERCENT
Tip Individual draw statements within this BEGINGRAPH block can override this global setting.
See About the Drawing Space and Drawing Units

INCLUDEMISSINGDISCRETE=TRUE | FALSE

specifies whether missing values are displayed on a discrete axis.

Default FALSE
Interaction This option affects all charts and plots within the template.
See boolean for other Boolean values that you can use.

LABELPLACEMENT=AUTO | GREEDY | SA

specifies the label-placement algorithm to use for positioning labels in the graphs.
The following labels are affected:
  • data labels for needle plots, scatter plots, series plots, step plots, and vector plots
  • vertex labels for line charts
  • curve labels when the curve label is positioned at the start or end of the curve

AUTO

always selects GREEDY.

GREEDY

specifies the Greedy method for managing label collision. The Greedy method tries different placement combinations in order to find an optimal approximation that avoids collisions. Label placement using this method is often less optimal than label placement using the Simulated Annealing (SA) method. However, depending on the number of data points and the potential for label collisions, the Greedy process can be significantly faster.

SA

specifies the Simulated Annealing method for managing label collision. The SA method attempts to determine the global minimization-of-cost function, which is based on a simulated annealing algorithm. The resulting label placement is usually better than placement using the Greedy method. However, depending on the number of data points and the potential for label collisions, the SA method can be significantly slower.

Restriction For BANDPLOT and LINECHART, the SA method has no effect on the curve labels when the CURVELABELPOSITION= option specifies START or END.
Default The value specified by the ODS GRAPHICS statement LABELPLACEMENT= option, which is AUTO by default.
Restriction The data label placement algorithm is not aware of bar labels, curve labels, box plot outlier labels, and marker characters. Collisions between these elements and data labels might occur regardless of the LABELPLACEMENT= setting.
Interactions This option overrides the ODS GRAPHICS statement LABELPLACEMENT= option.
This option affects a plot’s labels only when DATALABELPOSITION=AUTO is in effect for that plot.
The data label font size might be reduced in order to avoid overlapping labels and markers.

PAD=dimension | (pad-options)

specifies the amount of extra space that is added inside the graph border.

dimension

specifies a dimension to use for the extra space at the left, right, top, and bottom of the layout border.

(pad-options)

a space-separated list of one or more of the following name-value-pair options enclosed in parentheses:

LEFT=dimension specifies the amount of extra space added to the left side.
RIGHT=dimension specifies the amount of extra space added to the right side.
TOP=dimension specifies the amount of extra space added to the top.
BOTTOM=dimension specifies the amount of extra space added to the bottom.
Note Sides that are not assigned padding are padded with the default amount.
Tip Use pad-options to create non-uniform padding.
Default Padding for all sides is 10 pixels.
Note The default units for dimension are pixels.
See dimension

SAPLACEMENTOPTS=(placement-options)

specifies the options for the label-placement algorithm when LABELPLACEMENT=SA. Placement options can be any of the following:

MAXITERATIONS=positive-integer

specifies the maximum number of iterations for the SA label-placement algorithm.

Default 100

WEIGHTS=(keyword-number-list)

specifies the relative weight to give to a particular cost when determining the best label position. The keyword number list is a space-separated list of keyword = number pairs.

The following keywords can be used:
LABEL assigns a weight to the overlapping of labels
MARKER assigns a weight to the overlapping of markers and labels
OUTOFBOUND assigns a weight to labels that are out-of-bounds or clipped
PRIORITY assigns a weight to the priority of each potential label position
OBSTACLE assigns a weight to the overlapping of labels with drop lines, needles, reference lines, series lines, step lines, and vector lines
The higher the number, the more weight is assigned to the specified cost. For example, if MARKER is given more weight than OBSTACLE, avoiding marker collisions is given a higher priority than avoiding line collisions.
Default A weight of 1.0 is assigned to each keyword
Example
saplacementopts=(maxiterations=100
   weights=(LABEL=2.0 OBSTACLE=10.0))

SEED=positive-integer

specifies a random number seed for the Simulated Annealing algorithm.

Default 1234567
Range 0–2147483646 (231–1), where 0 specifies the current Java time as the seed value
Restriction This option applies only when LABELPLACEMENT=SA.

SUBPIXEL=AUTO | ON

specifies whether subpixel rendering is used when a graph is rendered.

AUTO

uses the default rendering for the rendering technology.

ON

always uses subpixel rendering, when applicable, for rendering line plots and bar charts.

Default AUTO
Restriction When this option is in effect, only the bar charts and line-based plots such as SERIESPLOT, BANDPLOT, REGRESSIONPLOT, LOESSPLOT, PBSPLINEPLOT, DENSITYPLOT, and LINECHART use subpixel rendering.
Requirement Anti-aliasing must be enabled for this option to have any effect.
Note When subpixel rendering is used, a one-half pixel alignment error can occur between some graph elements.
Tips Anti-aliasing is enabled by default. To re-enable anti-aliasing, use the ANTIALIAS=ON option in the ODS GRAPHICS statement.
For a large amount of data, anti-aliasing is disabled when the number of observations exceeds the default maximum of 4000 observations. In that case, subpixel rendering is also disabled. To increase the maximum, use the ANTIALIASMAX= option in the ODS GRAPHICS statement.
See Using Subpixel Rendering in SAS Graph Template Language: User's Guide
SAS Output Delivery System: User's Guide for information about the ANTIALIAS= and ANTIALIASMAX= options.

Details

About the BEGINGRAPH Statement

All template definitions in the Graphics Template Language must start with a BEGINGRAPH statement and end with an ENDGRAPH statement. Within a BEGINGRAPH block, one and only one GTL layout block is required. It can be a LATTICE, GRIDDED, OVERLAY, OVERLAYEQUATED, OVERLAY3D, REGION, DATALATTICE, or DATAPANEL layout block. This layout block and its nested layouts, if any, must contain at least one plot statement. It can contain other nested layout blocks.
The GTL global statements apply to the entire template and can include ENTRYTITLE and ENTRYFOOTNOTE statements, attribute maps, draw statements, conditional statements, and so on. Any of these global statements can precede or follow the GTL layout block.

Changing the Size of Your Graph

By default, graphs are rendered at 640px by 480px (4:3 aspect ratio). To change the output size for a single graph, use the DESIGNWIDTH= and DESIGNHEIGHT= options in the BEGINGRAPH statement for that graph. For example, the template in the Example Program uses DESIGNHEIGHT= to change the graph height to 320px. To prevent the graph width from automatically scaling to preserve the 4:3 aspect ratio, it uses DESIGNWIDTH= to maintain the 640px width. In this instance, the setting renders each graph cell as a 320px by 320px square. (The cells are square in this case, but the resulting cell size depends on the graph definition and would not be the same for all graphs.)
Note: To change the graph sizes for all templates in the current SAS session, you can use the WIDTH= and HEIGHT= options in the ODS GRAPHICS statement. Size settings in the ODS GRAPHICS statement override size settings in the BEGINGRAPH statement and remain in effect unless they are changed in another ODS GRAPHICS statement. You can also use WIDTH= and HEIGHT= settings in the graph style to modify the graphs sizes across template definitions. Be aware, however, that if you explicitly manage the graph output size, then the graph elements might be scaled so that the size specification is honored.
The following template defines a square graph (equal height and width, 1:1 aspect ratio) by setting the design width equal to the internal default height (480px). The setting is made with DESIGNWIDTH=DEFAULTDESIGNHEIGHT:
Note: A “square graph” means that the output graph’s width and height are equal. That does not imply that the X and Y axis lengths are equal if the graph contains only one cell.
proc template;
  define statgraph squareplot;
    dynamic title xvar yvar;
    begingraph / designwidth=defaultDesignHeight;
      entrytitle title;
      layout overlayequated / equatetype=square;
        scatterplot x=xvar y=yvar;
        regressionplot x=xvar y=yvar;
      endlayout;
    endgraph;
  end;
run;
If this template is executed with the following GRENDER procedure statement, then a 480px by 480px graph is created:
proc sgrender data=mydata template="squareplot" ;
dynamic title="Square Plot" xvar="time1" yvar="time2";
run;
If the ODS GRAPHICS statement’s WIDTH= or HEIGHT= options change the render width or render height, then the squareplot template’s 1:1 aspect ratio would still be honored. Thus, both of the following GRENDER procedure statements would create a 550px by 550px graph:
ods graphics / width=550px;
proc sgrender data=mydata template="squareplot" ;
dynamic title="Square Plot" xvar="time1" yvar="time2";
run;

ods graphics / height=550px;
proc sgrender data=mydata template="squareplot" ;
dynamic title="Square Plot" xvar="time1" yvar="time2";
run;

Example: BEGINGRAPH Statement

The following graph was generated by the Example Program:
Results of a Graph Defined within a BEGINGRAPH Block

Example Program

The BEGINGRAPH statement block is a required outermost container for any graph template. One of its purposes is to support options that apply to the entire graph. For example, the default graph size that a template produces is typically 640x480 pixels. If you need a different size, then you can declare the alternative size on this statement. To do so, use the DESIGNWIDTH= option, or the DESIGNHEIGHT= option, or both. This program shows one way to set the width and height of two graph cells to be equal.
proc template;
  define statgraph begingraph;
    dynamic XVAR YVAR;
    begingraph / designwidth=640px designheight=320px;
    layout lattice / columns=2;
      layout overlayequated / equatetype=square;
        entry "Linear Regression Fit" /
          valign=top texttattrs=(weight=bold);
        scatterplot x=XVAR y=YVAR / datatransparency=0.5;
        regressionplot x=XVAR y=YVAR;
      endlayout;
      layout overlayequated / equatetype=square;
        entry "Loess Fit" /
          valign=top texttattrs=(weight=bold);
        scatterplot x=XVAR y=YVAR / datatransparency=0.5;
        loessplot x=XVAR y=YVAR;
      endlayout;
    endlayout;
    endgraph;
  end;
run;

proc sgrender data=sashelp.iris template=begingraph;
  dynamic title="Square Plot"
    xvar="SepalLength" yvar="SepalWidth";
run;