Example Program and Statement Details

Example Graph

The following graph was generated by the Example Program:

Example Program

This example shows a two-cell lattice layout (two columns, one row). The ROWAXES block makes the primary and secondary Y axes external to both cells. The secondary Y axis is displayed on the right.

The ROWDATARANGE = UNION option assures that the data ranges of all Y= variables in the row cells are considered to construct a common axis range. This facilitates the visual comparison of the cells.
A SIDEBAR block is used to place the legend at the top of the lattice.

proc template;
 define statgraph layoutlattice;
  begingraph;
  entrytitle "Vehicle Gas Mileage";
  entryfootnote "Averages of 428 models from 38 manufactures";
    layout lattice / columns=2 rowdatarange=union;
     layout overlay / cycleattrs=true;
       barchart x=origin y=mpg_highway /
        stat=mean barwidth=.8 name="H" ;
       barchart x=origin y=mpg_city /
        stat=mean barwidth=.5 name="C" ;
     endlayout;
     layout overlay / cycleattrs=true;
       barchart x=type y=mpg_highway /
        stat=mean barwidth=.8;
       barchart x=type y=mpg_city /
        stat=mean barwidth=.5;
     endlayout;
     sidebar / align=top;	
       discretelegend "H" "C" / border=false;
     endsidebar;
     rowaxes;
       rowaxis / display=(tickvalues)
        displaysecondary=(tickvalues) griddisplay=on;
     endrowaxes;	   
    endlayout;
  endgraph;
 end;
run;
proc sgrender data=sashelp.cars template=layoutlattice;
run;

Statement Summary

The LAYOUT LATTICE statement creates a grid of graphs that are aligned across columns and rows. For plot statements that are specified in the layout block or nested in a LAYOUT OVERLAY statement, the LATTICE layout automatically aligns the plot areas and tick display areas in the plots.

Note: To achieve the alignment, the LATTICE layout automatically aligns plot areas and tick display areas across columns and rows. Also, it overrides axis-offset settings on the OVERLAY layouts that you specify in those columns and rows. (For details about offsets and the tick display area, see Adjusting Axis Offsets.) If you do not want this alignment, you might use LAYOUT GRIDDED instead. For example, if you have a heterogeneous panel of graphs, such as a mix of scatter plots, box plots, bar charts, or other types of graphs, you might consider using LAYOUT GRIDDED rather than LAYOUT LATTICE.

The layout can unify the scale of the data ranges that are displayed in the plots, based on the values set for the COLUMNDATARANGE and ROWDATARANGE= options. The data ranges can be scaled separately for each column, for each row, or for both. Or they can be scaled across all columns, all rows, or all of both.

When the data-range scales are unified, you can simplify the layout by displaying only the external axes that apply to all of the graphs across the corresponding columns or rows. See Axis Statements for more details.

The following figure shows the parts of the Lattice layout with the default axis display (internal axes are displayed).

This next figure shows the parts of the Lattice layout when the graph display is simplified so that only external axes are displayed.

Parts of a Lattice Layout Displaying External Axes

The columns and rows can be separated by areas called “gutters,” which are controlled by the COLUMNGUTTER= and ROWGUTTER= options. In addition, the COLUMNWEIGHTS= and ROWWEIGHTS= options can be used to allocate a proportion of available space to each row and column.

The LATTICE layout automatically decides how much area to allocate to cell contents:

text items have a fixed size based on the amount of text and the font properties
graphs take up the remaining space.

The layout’s grid size is determined by the COLUMNS= and ROWS= options.

By default, the results of the GTL-statements are placed into the grid sequentially from left to right, wrapping to a new row each time the current row is filled. You can use the ORDER= option to fill cells from top to bottom down a column. In that case, the layout cells wrap to a new column each time the current column is filled.

Cell Contents

The content of each cell in a LAYOUT LATTICE is specified by GTL-statement(s) that can be specified independently or enclosed in a CELL block. When you enclose the statements in a CELL block, you can specify one or more header lines at the top of the cell. If you do not need a cell header in a cell, there is no need to use the CELL block.

The following general syntax is used for the contents of each cell in a LAYOUT LATTICE:

GTL-statement(s) | cell-statement-block(s)

A cell-statement-block, when used, has the following syntax:

CELL;

<CELLHEADER; GTL-statement(s);ENDCELLHEADER;>

GTL-statement(s);

ENDCELL;

The contents of each cell is generated by GTL-statement(s) that can be specified independently or enclosed in a CELL block.
Whether specified independently or enclosed in a CELL block, the GTL-statement(s) can include text statements, plot statements, or layout statements.
Within a CELL block, a CELLHEADER block can be used to generate one or more header lines within the cell. Each header line is specified on a separate GTL-statement within the CELLHEADER block. The header block is typically used to specify one or more text statements, but other statements are allowed within the block. For example, you could specify a LAYOUT GRIDDED statement to produce a grid of text for the header
Only one CELLHEADER block can be used per CELL block. If more than one is specified, only the last one is used.
If a CELLHEADER block is not specified in a CELL block, the enclosed GTL-statement(s) produce the same results they would produce if they were specified independently.

The following example shows a LAYOUT LATTICE block that uses one GTL-statement and one cell-statement-block to generate the two-column layout shown in the following figure:

Lattice Layout with a Cell-statement Block

begingraph;
  layout lattice /
    columngutter=5 columns=2;
    
 /* independent plot statement - defines first cell */
    scatterplot x=age y=height;

 /* cell block - defines second cell */
    cell;
      cellheader;
        entry "Cell Header" / border =true;
      endcellheader;

      scatterplot x=weight y=height;

    endcell;
  endlayout;
endgraph;

Axis Statements

The axis statements can be used to simplify and clarify the layout by displaying only the external axes in the resulting graph.

The following figure shows the default layout with internal axes displayed:

Lattice Layout that Displays Internal Axes

This next figure shows a simplified layout with only the external axes displayed:

Lattice Layout that Displays External Axes

Axis statements are useful only if the data ranges across the affected columns or rows are comparable and can be unified to a common scale. For example, external axes are not supported if an affected lattice cell contains a LAYOUT OVERLAYEQUATED statement.

To unify column data ranges, use the COLUMNDATARANGE option. To unify row data ranges, use the ROWDATARANGE= option. If the axis ranges are not unified for the affected columns or rows, the axis statements in the layout are ignored.

For columns, external X axes (top, bottom, or both) are specified within a COLUMNAXES block, nesting one or more COLUMAXIS statements within the block. If a lattice cell contains a LAYOUT OVERLAY with the XAXISOPTS= option specified, the XAXISOPTS= option is ignored. In such cases, the desired axis features should be specified in the COLUMNAXIS statement. An X2AXISOPTS= option is also ignored if specified on the OVERLAY.

For rows, external Y axes (left, right, or both) are specified within a ROWAXES block, nesting one or more ROWAXIS statements within the block. If a lattice cell contains a LAYOUT OVERLAY with the YAXISOPTS= option specified, the YAXISOPTS= option is ignored. In such cases, the desired axis features should be specified in the ROWAXIS statement. A Y2AXISOPTS= option is also ignored if specified on the OVERLAY.

The axis statements have the following general syntax:

COLUMNAXES;

COLUMNAXIS / axis-option(s);

<...COLUMNAXIS-n;>

ENDCOLUMNAXES;

ROWAXES;

ROWAXIS / axis-option(s);

<...ROWAXIS-n;>

ENDROWAXES;

Only one COLUMNAXES block can be used in the LATTICE layout block. If more than one is specified, only the last one is used.
Within a COLUMNAXES block, the number of COLUMNAXIS statements should match the number of columns.
Only one ROWAXES block can be used in the LATTICE layout block. If more than one is specified, only the last one is used.
Within a ROWAXES block, the number of ROWAXIS statements should match the number of rows.
If the number COLUMNLAXIS or ROWAXIS statements is greater than the number needed, the extra statements are ignored. If the number of statements is fewer than the number needed, the additional COLUMNAXIS or ROWAXIS statements are automatically generated with DISPLAY=NONE options in effect.

For the list of axis-options, see Axis Options for LAYOUT LATTICE.

The following example shows a LAYOUT LATTICE block that uses a ROWAXES block to set external axes and display gridlines for the row display.

 begingraph;
   layout lattice /
      rowdatarange=union
      columns=2;

      /* axis definitions */
      rowaxes;
         rowaxis /griddisplay=on;
      endrowaxes;

      /* cell contents */
      scatterplot x=x y=t;
      scatterplot x=x y=y;

   endlayout;
 endgraph;

Here, the LAYOUT LATTICE statement specifies the ROWDATARANGE option to unify the data ranges across rows in the layout. Because LAYOUT LATTICE specifies COLUMNS=2 and there are two plot statements in the template, the resulting graph has two columns and only one row. Thus, only one ROWAXIS statement is needed in the ROWAXES block to specify axis attributes for that row of graphs.

Header Statements

Header statements are used to display one or more headers for the columns and rows in a Lattice layout. Each statement is specified as a block in the form statement - ENDstatement. The header block is typically used to specify one or more text statements, but other statements are allowed within the block. For example, you could specify a LAYOUT GRIDDED statement to produce a grid of text for the header.

The general syntax for a COLUMNHEADERS statement is

COLUMNHEADERS;

GTL-statement(s);

ENDCOLUMNHEADERS;

The following header statements are available:

COLUMNHEADERS	specifies a header for the primary (bottom) column-header position.
COLUMN2HEADERS	specifies a header for the secondary (top) column-header position.
ROWHEADERS	specifies a header for the primary (left) row-header position. ENTRY statements can be used to specify rotated text.
ROW2HEADERS	specifies a header for the secondary (right) row-header position. ENTRY statements can be used to specify rotated text.

The LAYOUT LATTICE aligns headers with the columns, or the rows, or both.
Each of the header blocks COLUMNHEADERS, COLUMN2HEADERS, ROWHEADERS, and ROW2HEADERS can be used once in a LAYOUT LATTICE block. If more than one block is specified for one of the statements, only the last specified block for that statement is used.

The following example shows a LAYOUT LATTICE block that uses a COLUMNHEADERS block to display column headers above the left and right columns in the layout.

begingraph;
   layout lattice / columns=2;

      /* Lattice header definitions */
      columnheaders;
         entry "Left Column";
         entry "Right Column";
      endcolumnheaders;

      /* cell contents */
      scatter x=x y=t;
      scatter x=x y=y;

   endlayout;
 endgraph;

Sidebar Statements

A LAYOUT LATTICE supports the display of a sidebar between a row or column header and an external axis. (See the figures in .)Example Program and Statement Details A sidebar spans across columns or rows and is useful for displaying information that applies to all of the columns or all of the rows. For example, sidebars are useful for displaying legends.

A SIDEBAR statement has the following syntax:

SIDEBAR </ ALIGN= BOTTOM | TOP | LEFT | RIGHT>;

GTL-statement(s);

ENDSIDEBAR;

ALIGN=BOTTOM is the default alignment.
You can specify up to four SIDEBAR blocks in a LAYOUT LATTICE, one for each of the top, bottom, left, and right sidebar positions.
If two or more SIDEBAR blocks have the same alignment, the sidebar information forms two or more columns (ALIGN=LEFT or ALIGN=RIGHT) within the sidebar area. Or it forms two or more rows (ALIGN=TOP or ALIGN=BOTTOM) within the sidebar area.
Only one statement (such as ENTRY or DISCRETELEGEND) or one layout block (such as LAYOUT GRIDDED) is allowed in a SIDEBAR block. To create multi-line text in a sidebar, nest ENTRY statements within a LAYOUT GRIDDED block.
The LAYOUT LATTICE automatically aligns a sidebar with the layout columns or rows.
Using ENTRY statements with the ROTATE= option, it is possible to place rotated text in the right or left sidebars.

The following example shows a LAYOUT LATTICE block that uses a SIDEBAR block to display a top sidebar in the layout.

begingraph;
 layout lattice / columns=2;
 
  sidebar / align=top;
    layout gridded / border=true ;
      entry "Top Sidebar" ;
      entry "(spans both columns)";
    endlayout;
  endsidebar;
 
  scatterplot x=x y=t;
  scatterolot x=x y=y;
 
 endlayout;
begingraph;

Options

Statement Option	Description
AUTOALIGN	specifies whether this layout is automatically aligned within its parent when nested within an overlay-type layout.
BACKGROUNDCOLOR	Specifies the color of the layout background.
BORDER	Specifies whether a border is drawn around the layout.
BORDERATTRS	Specifies the properties of the border line.
COLUMNDATARANGE	Specifies how the X-axis data ranges of graphs within the layout columns are scaled.
COLUMNGUTTER	Specifies the amount of empty space between the columns.
COLUMNS	Specifies the number of columns in the layout.
COLUMNWEIGHTS	Specifies the fractional proportion of each cell relative to the overall grid width, not including headers, sidebars, and column axes.
HALIGN	Specifies this layout’s horizontal alignment within its parent when nested within an overlay-type layout.
OPAQUE	Specifies whether the layout background is opaque.
ORDER	Specifies whether cells are populated with column priority or row priority.
PAD	Specifies the amount of extra space that is added inside the layout border.
ROWDATARANGE	Specifies how the Y-axis data ranges of graphs within the layout are scaled.
ROWGUTTER	Specifies amount of empty space between the rows.
ROWS	Specifies the number of rows in the layout.
ROWWEIGHTS	Specifies the fractional proportion of each cell relative to the overall grid height, not including headers, sidebars, and row axes.
SKIPEMPTYCELLS	Specifies whether the external axes skip the unused cells in a partially filled lattice.
VALIGN	Specifies this layout’s vertical alignment within its parent when nested within an overlay-type layout.

AUTOALIGN= NONE | AUTO | (location-list)

specifies whether this layout is automatically aligned within its parent when nested within an overlay-type layout. For more information about how child positions are determined in an overlay-type layout, see the LAYOUT OVERLAY’s Example Program and Statement Details.

Default: NONE

NONE

Do not automatically align this layout within its parent layout. This layout’s position within its parent layout is therefore set by the HALIGN= and VALIGN= options.

AUTO

Available only if the parent layout contains a scatter plot; ignored otherwise. Within the parent layout, attempt to center this layout in the area that is farthest from any surrounding data point markers.

(location-list)

Within the parent layout, restrict this layout’s possible locations to those locations in the specified location-list, and use the location-list position that least collides with the parent layout’s other graphics features. The location-list is blank-separated and can contain any of these locations: TOPLEFT, TOP, TOPRIGHT, LEFT, CENTER, RIGHT, BOTTOMLEFT, BOTTOM, and BOTTOMRIGHT.

dynamic VAR STAT1 STAT2 STAT3; 
layout overlay;
  histogram VAR;
  layout lattice / AUTOALIGN=(TOPRIGHT TOPLEFT)
columns=1;
     entry STAT1;
     entry STAT2;
     entry STAT3;
  endlayout;
endlayout;

Here the LATTICE layout is the child of the OVERLAY layout. The child layout appears in either the top right or top left position, based on which position has more “unoccupied” area.

Restriction: This option is available only when this layout statement is nested within an overlay-type layout. This option is ignored if this statement is the outermost layout or if the parent layout is not an overlay-type layout.

Interaction: If this option is enabled, it overrides the HALIGN= and VALIGN= options.

BACKGROUNDCOLOR=style-reference | color

specifies the color of the layout background.

Default: The GraphBackground:Color style reference.

style-element

A reference in the form style-element:style-attribute. Only the style-attribute named COLOR is used.

Interaction: OPAQUE=TRUE must be in effect for the color to be seen. By default, OPAQUE=FALSE.

BORDER=boolean

specifies whether a border is drawn around the layout.

Default: FALSE

Interaction: If this option is set to FALSE, the BORDERATTRS option is ignored.

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

specifies the attributes of the border line around the layout. See General Syntax for Attribute Options for the syntax on using a style-element and Line Options for available line-options.

Default: The GraphBorderLines style element.

Interaction: BORDER=TRUE must be set for this option to have any effect.

COLUMNDATARANGE= DATA | UNION | UNIONALL

specifies how the X-axis data ranges of graphs within the layout columns are scaled.

Default: DATA

DATA

scales the X-axis data ranges separately for each cell in the layout.

UNION

scales the X-axis data ranges separately for each column in the layout. This setting is supported only if all plots across the column can share the same data range and axis type. For more information, see Plot Axis Types Must Agree on Common Axes.

UNIONALL

scales the X-axis data ranges across all columns in the layout. This setting is supported only if all plots across the column can share the same data range and axis type. For more information, see Plot Axis Types Must Agree on Common Axes.

Restriction: If any plot statement in any cell contains an XAXIS=X2 option, this option is ignored if it is set to UNION or UNIONALL. The union setting causes all data to be mapped to the X axis.

Interaction: Axes are always internal to the cell, by default. To externalize column axes, 1) set this option to UNION or UNIONALL 2) specify a COLUMNAXES block with as many COLUMNAXIS statements as there are columns.

If column axes are externalized, and if a lattice cell contains a LAYOUT OVERLAY with the XAXISOPTS= option specified, the XAXISOPTS option is ignored. In such cases, the COLUMNAXIS statement should be used to specify desired axis features.

COLUMNGUTTER=dimension

specifies the amount of empty space between the columns.

Default: 0

If there are n columns, then there are n-1 gutters.

COLUMNS=integer

specifies the number of columns in the layout.

Default: If ORDER=ROWMAJOR, the default is 1. If ORDER=COLUMNMAJOR, as many columns are created as are needed to satisfy the ROWS= request.

Interaction: If both ROWS=n and COLUMNS=m is specified, an n by m grid of cells is created. If the number of statements that define cell contents is greater than n x m, the grid size does not expand and some statements are not displayed. If the number of statements that define cell contents is less than n x m, the grid will contain empty cells.

If this option is not defined and ORDER=COLUMNMAJOR, the number of columns is dynamically determined by the number of defined cells.

COLUMNWEIGHTS= (numeric-list)

specifies the fractional proportion of each cell relative to the overall grid width, not including headers, sidebars, and column axes.

Requirement: numeric-list must be enclosed in parentheses. If there are n columns, then the list specified should contain n values and the sum of the weights should be 1.0.

HALIGN= CENTER | LEFT | RIGHT

specifies this layout’s horizontal alignment within its parent when nested within an overlay-type layout. For more information about how child positions are determined in an overlay-type layout, see the LAYOUT OVERLAY’s Example Program and Statement Details.

Default: CENTER

Restriction: This option is available only when this statement is nested within an overlay-type layout. It is ignored if this statement is the outermost layout or if the parent layout is not an overlay-type layout.

Interaction: If the AUTOALIGN= option is enabled, this option is ignored.

Discussion: In the following example, the LATTICE layout is the child of the OVERLAY layout and is positioned in the OVERLAY’s top right corner.

dynamic VAR STAT1 STAT2 STAT3; 
layout overlay;
  histogram VAR;
  layout lattice / VALIGN=TOP HALIGN=RIGHT
columns=1;
     entry STAT1;
     entry STAT2;
     entry STAT3;
  endlayout;
endlayout;

OPAQUE= boolean

specifies whether the layout background is opaque (TRUE) or transparent (FALSE).

Default: FALSE

Interaction: When this option is set to FALSE, the background color is not used.

ORDER= ROWMAJOR | COLUMNMAJOR

specifies whether cells are populated with column priority or by row priority.

Default: ROWMAJOR

ROWMAJOR

fills all the columns in a row, from left to right, before going to the next row.

COLUMNMAJOR

fills all the rows in a column, from top to bottom, before going to the next column.

Requirement: If this option is set to COLUMNMAJOR, the ROWS= option must be specified to indicate how many rows to fill before wrapping to the next column. The default number of rows is 1.

Requirement: If this option is set to ROWMAJOR, the COLUMNS= option must be specified to indicate how many columns to fill before wrapping to the next column. The default number of columns is 1.

PAD=dimension | (pad-options)

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

Default: The default padding for all sides is 0. Values without units are in pixels (px). A unit must be provided if other than pixels.

dimension

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

(pad-options)

Enables separate settings for the left, right, top, and bottom padding dimensions. Use the pad-options to create non-uniform padding. These options must be enclosed in parentheses. Each option is specified as a name = value pair. Sides not assigned padding are padded with the default amount.

Values without units are in pixels (px). A unit must be provided if other than pixels.

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.

ROWDATARANGE= DATA | UNION | UNIONALL

specifies how the Y-axis data ranges of graphs within the layout rows are scaled.

Default: DATA

DATA

scales the Y-axis data ranges separately for each cell in the layout.

UNION

scales the Y-axis data ranges separately for each row in the layout. This setting is supported only if all plots down the row can share the same data range and axis type. For more information, see Plot Axis Types Must Agree on Common Axes.

UNIONALL

scales the Y-axis data ranges across all rows in the layout. This setting is supported only if all plots down the row can share the same data range and axis type. For more information, see Plot Axis Types Must Agree on Common Axes.

Restriction: If any plot statement in any cell contains a YAXIS=Y2 option, this option is ignored whenever it is set to UNION or UNIONALL. The union setting causes all data to be mapped to the Y axis.

Interaction: Axes are always internal to the cell, by default. To externalize row axes, 1) set this option to UNION or UNIONALL 2) specify a ROWAXES block with as many ROWAXIS statements as there are rows.

If row axes are externalized, and if a lattice cell contains a LAYOUT OVERLAY with the YAXISOPTS= option specified, the YAXISOPTS option is ignored. In such cases, the ROWAXIS statement should be used to specify desired axis features.

ROWGUTTER=dimension

specifies amount of empty space between the rows.

Default: 0

If there are n rows, then there are n-1 gutters.

ROWS=integer

specifies the number of rows in the layout.

Default: If ORDER=COLUMNMAJOR, the default is 1. If ORDER=ROWMAJOR, as many ROWS are created as needed to satisfy the COLUMNS= request.

ROWWEIGHTS=(numeric-list)

specifies the fractional proportion of each cell relative to the overall grid height, not including headers, sidebars, and row axes.

Requirement: numeric-list must be enclosed in parentheses. If there are n columns, then the list specified should contain n values and the sum of the weights should be 1.0.

SKIPEMPTYCELLS=boolean

specifies whether the external axes skip the unused cells in a partially filled lattice.

Default: FALSE

FALSE

External axes are displayed at their normal locations.

TRUE

Empty cells are skipped by external axes and the axes “snap” to the nearest populated cell, both vertically and horizontally.

VALIGN=CENTER | TOP | BOTTOM

specifies this layout’s vertical alignment within its parent when nested within an overlay-type layout. For more information about how child positions are determined in an overlay-type layout, see the LAYOUT OVERLAY’s Example Program and Statement Details.

Default: CENTER

Interaction: If the AUTOALIGN= option is enabled, this option is ignored.