Managing Your Graphics With ODS

Using the ODS GRAPHICS Statement

You can use the ODS GRAPHICS statement options to control many aspects of your graphics. The settings you specify remain in effect for all graphics until you change or reset these settings with another ODS GRAPHICS statement. When you use the GTL language or SAS/GRAPH Statistical Graphics procedures, the ODS GRAPHICS is always ON. However, you can use the ODS GRAPHICS statement to control the following:

the size of the image
the type and name of the image created
whether features such as data tips, scaling, and anti-aliasing are used

The basic syntax for the ODS GRAPHICS statement is:

ODS GRAPHICS < OFF | ON> </ option(s)>;

For a table of options for the ODS GRAPHICS statement, see ODS GRAPHICS Statement Options.

The following program uses the ODS GRAPHICS statement to illustrate several techniques for controlling your graphics. These techniques are discussed in the following sections:

Controlling Graphics with the ODS GRAPHICS Statement

1 ods graphics on / 
     2 width=3.25in
     3 imagefmt=gif
     4 imagemap=on
     5 imagename="MyBoxplot"
     6 border=off;

ods html file="Boxplot-Body.html" style=journal gpath="your-file-path";

proc sgplot data=sashelp.heart;
  title "Cholesterol Distribution by Weight Class";
  hbox cholesterol / category=weight_status;
run;
ods html close;

7 ods graphics on / reset=all imagename="MyResetplot";

ods html file="BoxPlotReset-Body.html" style=journal gpath="your-file-path";

proc sgplot data=laborforce;
hbox unemplrate / category=state datalabel=year;
run;

ods html close;

3.25 Inch Graph with Data Tips and No Border

[3.25 Inch Graph with Data Tips and No Border]

Graph with Options Set Back to Defaults

[Graph with Options Set Back to Defaults]

The numbers in the following sections correspond to numbers in the program above.

Controlling the Size of Your Graph

Overview

The output size of a graph is determined by the following:

For SGRENDER output, the design size for the graph as specified in the StatGraph template. The default sizes defined in the registry are:
- Default design width=640px
- Default design height=480px
- Default aspect ratio is 4/3
For SGPLOT, SGPANEL, or SGSCATTER output, the preceding default sizes are used.
DPI settings for the output destinations, as specified by the IMAGE_DPI= or DPI= options
User specified settings for width and height, as specified by the WIDTH= option and the HEIGHT= option for the ODS GRAPHICS statement.

When modifying the size of your graph, it is important to take into consideration the image scaling and aspect ratio, as well as the width and height of the graph. For example, rendering a graph to the Listing destination at the default design size and default DPI of 100, produces a graph that is 640 by 480 pixels. If the same graph is rendered to the RTF destination, which has a default DPI of 200, the graph size is 1280 by 960 pixels. In both cases, when this image is embedded into an RTF document, its size in the document is 6.4 in. by 4.8 in, since DPI data is included in the image. The aspect ratio of the graph is retained.

Graph Scaling for DPI

When the DPI of a graph is changed due to a change in output destination or user specification, the graph is scaled using a baseline DPI of 100. All graphical elements such as marker size, line thickness, font sizes, and gutters are also scaled.

Specifying Output Size with the ODS GRAPHICS statement

You can control the output size of a graph by specifying the WIDTH= or HEIGHT= options in the ODS GRAPHICS statement. In the ODS GRAPHICS statement below, taken from Controlling Graphics with the ODS GRAPHICS Statement, the WIDTH= option () changes the width of the graph to 3.25 inches:

ods graphics on / 
      2 width=3.25in
      imagefmt=gif
      imagemap=on
      imagename="MyBoxplot"
      border=off;

Retaining Aspect Ratio

Although you can use the ODS GRAPHICS statement to specify the WIDTH= option, the HEIGHT= option, or both, it is highly recommended that only one of these options be specified at a time. Using one option at a time ensures that the design aspect ratio of the graph is maintained.

When only width is specified, SAS uses the design aspect ratio of the graph to compute the appropriate height. Retaining the design aspect ratio of the graph is important in many cases as the graph might have a specific layout. For example, a plot that has multiple columns, or that has a statistics table on the side needs a wide aspect ratio. Changing the aspect ratio for this plot by specifying both width and height might produce unpredictable results.

Graph Scaling For User Specified Image Size

When the size of a graph is changed by specifying the WIDTH= option in the ODS GRAPHICS statement, the output size of the graph is computed based on the new size, and the active DPI, using a baseline of DPI of 100. All graphical elements such as marker size, line thickness, font size, and gutters are scaled using a non-linear scale. This is done to prevent rapid shrinking or growth of the fonts and markers.

Scaling of graph elements for change in graph size can be disabled by the ODS GRAPHICS statement options NOSCALE or SCALE=OFF. By default, scaling is on. Specifying NOSCALE or SCALE=OFF prevents the scaling of the graph elements. If you want to shrink your graph and keep the default sizes for fonts, use the NOSCALE or SCALE=ON option in the ODS GRAPHICS statement.

Tip For Embedding Images in Documents

It is often useful to produce a graph that fits in one column of a two column page. In this case, the column size might be 3.25 inches wide. You can place a default output image, which is 640 by 480 pixels, in this space, but then all graphical elements scale down. This results in small markers and unreadable small fonts.

In this case, it is useful to render the graph to the exact size required, and specify the correct DPI. In the situation above, you would specify a width of 3.25 inches and use the IMAGE_DPI= destination statement option to specify a DPI of 200. Then, the graph produced can be placed in the 3.25" wide column and the fonts and markers are readable.

Note: To get exactly the specified font sizes, use the NOSCALE option in the ODS GRAPHICS statement. [cautionend]

Adding Data Tips and Other Features

With ODS GRAPHICS statement options you can control different features of your graphs, such as borders and data tips. In the ODS GRAPHICS statement below, taken from Controlling Graphics with the ODS GRAPHICS Statement, the BORDER=OFF option () specifies that there be no border around the graph and the IMAGEMAP=ON () option enables the generation of data tips and any drill downs:

ods graphics on / 
    width=3.25in
    imagefmt=gif
    4 imagemap=on
    imagename="MyBoxplot"
    6 border=off;

When viewing HTML output, data tips appear when you move a mouse over certain features of the graph. Data tips and URL drill down functionality are available only for the HTML destination. You can also specify the maximum number of distinct mouse over areas allowed before data tips are disabled by using the TOOLTIPMAX= option. There are many other ODS GRAPHICS options you can use to control other aspects of your graphics. See ODS GRAPHICS Statement Options for a table of ODS GRAPHICS statement options.

Resetting ODS GRAPHICS Options

You can specify the RESET option to change the values for these options back to their defaults. In Controlling Graphics with the ODS GRAPHICS Statement, the second ODS GRAPHICS statement () uses the RESET=ALL option to set all options back to their defaults for a new graph:

7 ods graphics on / reset=all imagename="MyResetplot";

You can also reset ODS GRAPHICS options individually. For a list of values valid for the RESET= option, see ODS GRAPHICS Statement Options.

Note: When you specify the RESET= option, ensure that it is the first option specified in the ODS GRAPHICS statement. Otherwise, you might reset some of other options in the statement. [cautionend]

For the complete documentation on all ODS GRAPHICS statement options, see ODS GRAPHICS Statement Options.

Accessing Graphs as Separate Files

Overview

ODS enables you to change the ODS destination where you are sending your output to result in different output formats such as RTF or PDF. There might also be times when you want to access your graphs as individual image files.

The default image file type is determined by the ODS destination. You can use the IMAGEFMT= option to specify a different image file format. The type of image allowed is dependent on the destination you have specified. See Supported Image File Types for Output Destinations for a table of ODS destinations and their valid file types.

You can also specify names for your graphics image files and the directory in which you want to save them. The IMAGENAME= option specifies the base image filename and the GPATH= option specifies a directory for your images.

In the ODS GRAPHICS statement below, taken from Controlling Graphics with the ODS GRAPHICS Statement, the IMAGEFMT= option () specifies that the file type is a GIF, and the IMAGENAME= option () specifies that the name of the image is "MyBoxplot":

ods graphics on / 
          width=3.25in
          3 imagefmt=gif
          imagemap=on
          5 imagename="MyBoxplot"
          border=off;

The resulting filename for the image created is MyBoxplot.GIF. If there is more then one image, they are named MyBoxplot1.GIF, MyBoxplot2.GIF, and so on.

The second ODS GRAPHICS statement () specifies the filename "MyBoxplot" for the second image. However, because the RESET=ALL option is used, the file type is PNG, which is the default file type for the HTML destination:

7 ods graphics on / reset=all 
            imagename="MyBoxplot";

For the ODS destinations that generate graphic image files, these image files are saved by default into the SAS current working directory. You can use the GPATH= option to specify a directory for saving your graphics image files. For example, in Controlling Graphics with the ODS GRAPHICS Statement the GPATH= option on both of the ODS HTML statements specifies that all images be saved in the directory C:\myfiles\images.

For more information about ODS destinations, see SAS Output Delivery System: User's Guide.

Supported Image File Types for Output Destinations

The following table lists all of the supported image file types for ODS output destinations.

Output Destination	Supported Image File Types
HTML	PNG (default), GIF, JPEG, JPG
Listing	PNG (default), BMP, DIB, EMF, EPSI, GIF, JFIF, JPEG, JPG, PBM, PDF, PS, SASEMF, STATIC, TIFF, WMF
LATEX	PS(default), EPSI, GIF, PNG, PDF, JPG
Printer Family	PNG(default), JPEG, JPG, GIF
RTF	PNG(default), JPEG, JPG, JFIF
Markup Tagsets	All Markup family tagsets have the default imagefmt value built in.

Description of Supported Image File Types

Image File Type	Description
BMP (Microsoft Windows Device Independent Bitmap)	Supports color-mapped and true color images that are stored as uncompressed or run-length encoded data.
DIB (Microsoft Windows Device Independent Bitmap)	See the description of BMP. DIB is supported only under the OS/2 operating system.
EMF (Microsoft NT Enhanced Metafile)	Supported only under Windows 95, Windows 98, and Windows NT.
EPSI (Microsoft NT Enhanced Metafile)	An extended version of the standard PostScript (PS) format. Files that use this format can be printed on PostScript printers and can also be imported into other applications. Notice that EPSI files can be read, but PS files cannot be read.
GIF (Graphics Interchange Format)	Supports only color-mapped images.
JFIF (JPEG File Interchange Format)	Supports JPEG image compression.
JPEG or JPG (Joint Photographic Experts Group)	A file format that is used for storing noninteractive images.
PBM (Portable Bitmap Utilities)	Supports gray, color, RGB, and bitmap files.
PDF (Portable Document Format)	A file format for electronic distribution and exchange of documents.
PNG (Portable Network Graphic)	Supports true color, gray-scale, and 8-bit images.
PS (PostScript Image File Format)	The Image classes use only PostScript image operators. A level II PS printer is required for color images.
SASEMF (Enhanced Metafile)	EMF image tuned for RTF output.
STATIC	Chooses the best image format for the current ODS destination.
TIFF (Tagged Image File Format)	Internally supports a number of compression types and image types, including bitmapped, color-mapped, gray-scaled, and true color.
WMF (Microsoft Windows Metafile)	Supported only under Microsoft Windows operating systems.

ODS GRAPHICS Statement Options

The following options can be used with the ODS GRAPHICS statement.

ODS GRAPHICS Option Summary Table
Task		Option
Specify whether anti-aliasing is applied to the rendering of the line and markers in any graph.		ANTIALIAS= \| ANTIALIAS \| NOANTIALIAS
Specify the maximum number of markers or lines to be anti-aliased before anti-aliasing is disabled.		ANTIALIASMAX=
Specify whether to draw a border around each graph.		BORDER= \| BORDER \| NOBORDER
Specify the maximum number of discrete values to be shown in any graph.		DISCRETEMAX=
Specify the maximum number of group values to be shown in any graph.		GROUPMAX=
Specify the height of any graph.		HEIGHT=
Specify the image format used to generate image files.		IMAGEFMT=
Specify whether data tips are generated.		IMAGEMAP=\| IMAGEMAP \| NOIMAGEMAP
Specify the base image filename.		IMAGENAME=
Specify the maximum number of labeled areas before labeling is disabled.		LABELMAX=
Specify an integer that is interpreted as the maximum percentage of the overall graphics area that a legend can occupy.		MAXLEGENDAREA=
Specify the maximum number of cells in a graph panel where the number of cells is determined dynamically by classification variables.		PANELCELLMAX=
Reset one or more ODS GRAPHICS options to its default.		RESET \| RESET=
Specify whether the content of any graph is scaled proportionally.		NOSCALE \| SCALE \| SCALE=
Specify the maximum number of distinct mouse--over areas allowed before data tips are disabled.		TIPMAX=
Specify the width of any graph.		WIDTH=

ANTIALIAS= | ANTIALIAS | NOANTIALIAS

specifies whether anti-aliasing is applied to the rendering of the line and markers in any graph. Anti-aliasing smooths the appearance of diagonal lines and some markers. Text displayed in the graph is always anti-aliased. For graphical displays that plot large numbers of points it is recommended that ANTIALIAS=OFF be specified for performance considerations.

ANTIALIAS= OFF | ON

specifies whether anti-aliasing is applied to the rendering of the line and markers in the graph.

OFF

does not smooth jagged edges of components other than text in the graph.

Alias:

smooths jagged edges of all components in the graph.

Alias:

YES

ANTIALIAS

smooths jagged edges of all components in the graph.

NOANTIALIAS

does not smooth jagged edges of components other than text in the graph.

Default:	ON
Restriction:	If the number of markers or curve points in the plot exceeds the number specified by the ANTIALIASMAX= option, then the ANTIALIAS option is turned off, even if you specify the option ANTIALIAS=ON or ANTIALIAS.

ANTIALIASMAX= n

specifies the maximum number of markers or lines to be anti-aliased before anti-aliasing is disabled. For example, if there are more than 400 scatter point markers to be anti-aliased and ANTIALIASMAX=400, then no markers are anti-aliased.

n

specifies a positive integer.

Default:

600

BORDER= | BORDER | NOBORDER

specifies whether to draw a border around any graph.

BORDER= OFF | ON

specifies whether to draw the graph with a border on the outermost layout.

ON

specifies to draw a border around the graph.

Alias:

YES

OFF

specifies not to draw a border around the graph.

Alias:

BORDER

specifies to draw a border around the graph.

NOBORDER

specifies not to draw a border around any graph.

Default:

BORDER or BORDER=ON

DISCRETEMAX=n

specifies the maximum number of discrete values to be shown in any graph. Bar charts and box plots are examples of affected plot types. Scatter plots and other plot types might be affected if the data to be plotted is discrete or the axis is discrete.

n: specifies a positive integer.

Default:	1000
Tip:	Some plot layers might be unaffected by the DISCRETEMAX= option, and those layers are still rendered. If all layers are affected, then a blank graph is rendered.
Tip:	If the value specified by the DISCRETEMAX= option is exceeded by any plot layer in the graph, that layer is not drawn and a warning message is issued.

GROUPMAX=n

specifies the maximum number of group values to be shown in any graph. Any graph that supports the GROUP= option is affected.

n: specifies a positive integer.

Default:	1000
Tip:	If the value specified by the GROUPMAX= option is exceeded by any plot layer in the graph, that layer is rendered ignoring the GROUP= option and a warning message is issued.

HEIGHT=dimension

specifies the height of any graph.

dimension

is a nonnegative number.

See:

dimension

Default:

The value of the SAS registry entry "ODS > STATISTICAL GRAPHICS > Design Height" or the value of the DesignHeight= option in a STATGRAPH template. Typically, the value is 480px.

IMAGEFMT= image-file-type | STATIC

specifies the image format to be used. If the image format is not valid for the active output destination, the format is automatically changed to the default image format for that destination.

image-file-type: is the image format to be generated. See Supported Image File Types for Output Destinations.
STATIC: uses the best quality static image format for the active output destination. This is the default.

Default:

STATIC

IMAGEMAP= | IMAGEMAP | NOIMAGEMAP

controls data tips generation. Data tips are pieces of explanatory text that appear when you mouse-over the data portions of a graph contained in an HTML page.

IMAGEMAP= ON | OFF

controls data tips generation.

OFF

specifies not to generate data tips.

Alias:

specifies to generate data tips.

Alias:

YES

IMAGEMAP

specifies to generate data tips.

NOIMAGEMAP

specifies not to generate data tips.

Default:	OFF or NOIMAGEMAP
Restriction:	This option applies only when the ODS HTML destination is used.

IMAGENAME="filename"

specifies the base image filename.

If more than one image is generated, each is assigned filename as a base name followed by a number in order to create unique names. This numbering can be reset with the RESET=INDEX option. Path information (if needed) can be set with the GPATH= option in the ODS destination statement. The default path is the current output directory. A file extension for filename is automatically generated based on the IMAGEFMT= option.

Requirement:	You must enclose filename in quotation marks.
Restriction:	filename must be a single name. It must not include any path specification or image-format name extension.
Default:	The name of the output object.

LABELMAX= n

specifies the maximum number of labeled areas before labeling is disabled. For example, if there are more than 50 points to be labeled and LABELMAX=50, then no points are labeled.

n

specifies a positive integer.

Default:

200

MAXLEGENDAREA= n

specifies an integer that is interpreted as the maximum percentage of the overall graphics area that a legend can occupy.

n

specifies a positive integer.

Default:	20
Tip:	To turn off the legend, specify MAXLEGENDAREA=0. No warning is issued when the legend is turned off in this way.

PANELCELLMAX=n

specifies the maximum number of cells in a graph panel where the number of cells is determined dynamically by classification variables.

n: specifies a positive integer.

Default:	10000
Tip:	If the value specified by the PANELCELLMAX= option is exceeded by either of these layouts, an empty graph is rendered and a warning message is issued.

RESET | RESET= option

resets one or more ODS GRAPHICS options to its default.

RESET

resets all of the options to their defaults.

RESET=

resets one of the following to its default:

ALL

resets all of the reset-options to their defaults.

ANTIALIAS

resets the ANTIALIAS option to its default.

ANTIALIASMAX

resets the ANTIALIASMAX option to its default.

BORDER

resets the BORDER= option to its default.

IMAGEMAP

resets the IMAGEMAP= option to its default.

INDEX

resets the index counter that is appended to static image files.

HEIGHT

resets the HEIGHT= option to its default.

IMAGEMAP

resets the IMAGEMAP= option to its default.

Note: Not all output destinations support this feature. [cautionend]

LABELMAX

resets the LABELMAX= option to its default.

SCALE

resets the SCALE= option to its default.

TIPMAX

resets the TIPMAX= option to its default.

WIDTH=

resets the WIDTH= option to its default.

NOSCALE | SCALE | SCALE=

specifies whether the content of any graph is scaled proportionally.

NOSCALE

does not scale the components of graph proportionally.

SCALE

scales the components of graph proportionally.

SCALE=

specifies whether the content of the graph is scaled proportionally.

OFF

does not scale the components of graph proportionally.

Alias:	NOSCALE
Alias:	NO

scales the components of graph proportionally.

Alias:

YES

Default:

ON or SCALE

TIPMAX=n

specifies the maximum number of distinct mouse-over areas allowed before data tips are disabled. For example, if there are more than 400 points in a scatter plot, and TIPMAX=400, then no data tips appear.

n

specifies a positive integer.

Default:

500

WIDTH=dimension

specifies the width of any graph.

dimension

is a nonnegative number.

Default:	The value of the SAS registry entry "ODS > STATISTICAL GRAPHICS > Design Width" or the value of the DesignWidth= option in a STATGRAPH template. Typically, this value is 640px.
See:	dimension

dimension

is a nonnegative number, which can be followed by one of these units of measure:

cm	centimeters
in	inches
mm	millimeters
pt	a printer's point
px	pixels

Top of Page