Example Program and Statement Details

Example Graph

The following graph was generated by the Example Program:
Example Layout DataLattice

Example Program

This example shows the result of using row and column classification variables. In this case, a four-column, three-row data lattice is created:
  • The classification values are placed as row or column labels by default.
  • The ROWDATARANGE = UNION option assures that an axis range is computed separately for each row using the data ranges of all Y= variables in that row. This facilitates the visual comparison of the data cells.
  • A SIDEBAR block is used to place the legend at the bottom of the lattice.
proc template;
 define statgraph layoutdatalattice;
  begingraph;
    entrytitle "Annual Furniture Sales Comparisons";    
    layout datalattice rowvar=country columnvar=year / 
      rowdatarange=union
      headerlabeldisplay=value 
      headerbackgroundcolor=GraphAltBlock:color
      rowaxisopts=(display=(tickvalues) griddisplay=on
        linearopts=(tickvalueformat=dollar12.))
      columnaxisopts=(display=(tickvalues)  
        timeopts=(tickvalueformat=monname3.));
      layout prototype / cycleattrs=true;
        seriesplot x=month y=TotalActual / name="Actual";
        seriesplot x=month y=TotalPredict / name="Predict";		   
      endlayout;
      sidebar / align=bottom;        
        discretelegend "Actual" "Predict" / border=false;
      endsidebar;
    endlayout;
  endgraph;
 end;
run;

proc summary data=sashelp.prdsal2 nway;
  class country year month;
  var actual predict;
  output out=prdsal2 sum=TotalActual TotalPredict;
run;

proc sgrender data=prdsal2 template=layoutdatalattice;
run;

Statement Summary

The LAYOUT DATALATTICE statement makes it easy to create a grid of graphs, based on the values of one or two classifications variables. To create a grid that is based on more than two classification variables, or to have more control over the grid layout, use LAYOUT DATAPANEL instead.
By default, the number of cells in the layout is determined by the number of value pairings that are possible for the classification values plus any empty cells needed to complete the last row/column of the grid. The contents of each data cell are based on a graph prototype that you specify in the graph-prototype-block. You can enhance the display using one or more sidebar-statement-blocks. For classification variables that have many values, you can use the COLUMNS= and or ROWS= options and the PANELNUMBER= option to generate multiple panel displays.
Classification variables for the layout are specified on the ROWVAR= argument (to specify a row variable), or the COLUMNVAR= argument (to specify a column variable), or both arguments to specify both a column and a row variable. The graph prototype for each data cell’s contents is specified within a Prototype Block block, and sidebars are specified within SIDEBAR blocks. The LAYOUT PROTOTYPE and SIDEBAR blocks are nested within the LAYOUT DATALATTICE block.
By default, the first data cell to be filled is in the layout’s top left corner. Use the START= option to change the starting data cell to the bottom left corner.
Rather than display the header labels outside the grid, you can set HEADERLABELLOCATION= INSIDE to display them inside the grid, as shown in the following figure:
DataLattice with Header Labels Inside
Note: The DATALATTICE layout is designed to be the outermost layout in the template.

Required Argument(s)

One of the ROWVAR= or COLUMNVAR= arguments is required. Both can be specified. Each specifies a single classification variable. Any one of the following uses is valid:
LAYOUT DATALATTICE ROWVAR=class-var
LAYOUT DATALATTICE COLUMNVAR=class-var
LAYOUT DATALATTICE ROWVAR=class-var COLUMNVAR=class-var
If you do not explicitly manage columns and rows using the COLUMNS= and ROWS= options, the default layout behavior is as follows:
  • If both ROWVAR= and COLUMNVAR= are specified, a data cell is created for each of the value pairings that are possible for the classification values of the specified variables. If the ROWVAR variable has R distinct values and the COLUMNVAR variable has C distinct values, the dimension of grid produced is R x C.
  • If only the ROWVAR variable is used, an R x 1 grid is produced.
  • If only the COLUMNVAR variable is used, a 1 x C grid is produced.
Variable values are always retained in data order. Formats can be assigned to class variables to create classification levels (for example, an AGEGROUPFMT. format for numeric AGE).
The output size does not grow automatically as the number of cells increases. To set a panel size for the current template, use the DESIGNHEIGHT= and DESIGNWIDTH= options in the BEGINGRAPH statement. To set a panel size for all templates in the current SAS session, use the HEIGHT= and WIDTH= options in the ODS GRAPHICS statement. Size settings in the ODS GRAPHICS statement override size settings in the BEGINGRAPH statement. The default output width is 640px, and the default output height is 480px.
As the number of cells in the grid increases, the size of each cell decreases. At some point the cells might become so small that a meaningful graph cannot be rendered. The CELLHEIGHTMIN= and CELLWIDTHMIN= options set a threshold for the smallest cell. If the actual cell height or width becomes smaller, no panel is drawn. The default minimum cell size is CELLHEIGHTMIN=100px and CELLWIDTHMIN=100px.
Using the default panel size and cell size, the DATALATTICE layout accommodates a grid of about 24 cells (6 columns by 4 rows). If you know that the number of cells is larger, you should increase the overall panel size, or decrease the minimum cell size, or both. You can also use ROWS=, COLUMNS=, and PANELNUMBER= options to partition your data so a number of smaller grids are produced that cumulatively show all of the value crossings.

Prototype Block

You must specify a single graph-prototype-block within the LAYOUT DATALATTICE block, using the following syntax:
LAYOUT PROTOTYPE </option(s)>;
GTL-statement(s);
ENDLAYOUT;
The graph-prototype-block determines the graphical content of each data cell and is repeated within each data cell, based on the subsets of the classification variables.
For more information about the LAYOUT PROTOTYPE block and the list of available options, see LAYOUT PROTOTYPE Statement.

Sidebar Blocks

A LAYOUT DATALATTICE enables you to display one or more sidebars outside of the axes. 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 a legend.
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 DATALATTICE, one for each of the bottom, top, left, and right sidebar positions.
  • The LAYOUT DATALATTICE automatically aligns a sidebar with the layout columns or rows.
  • 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 following example shows a SIDEBAR block that displays a legend at the top of the layout grid.
  sidebar / align=top;
     discretelegend 'p' 'a' / across=2;
  endsidebar;

Options

Statement Option
Description
Specifies the color of the layout background.
Specifies whether a border is drawn around the layout.
Specifies the properties of the border line.
Specifies the minimum height of a cell in the grid.
Specifies the minimum width of a cell in the grid.
Specifies axis options for all columns.
Specifies how the X-axes of instances of the graph-prototype are scaled.
Specifies the amount of empty space that is between the columns.
Specifies where to position the outside column header.
Specifies the number of columns in the layout.
Specifies the background color of the cell headers.
Specifies the text properties for the cell headers.
Indicates whether the automatic cell header text includes variable name and value or just the value.
Indicates whether the cell header is placed within each cell (INSIDE) or as row and column headers external to the lattice (OUTSIDE).
Specifies whether the background for the cell headers is opaque.
Specifies what information is displayed in an inset.
Specifies the location and appearance options for the inset information.
Specifies whether the layout background is opaque.
Specifies the amount of extra space that is added inside the layout border.
Specifies the number of the panel to produce.
Specifies axis options for all rows.
Specifies how the Y-axes of instances of the graph-prototype are scaled.
Specifies amount of empty space between the rows.
Specifies where to position the outside row header.
Specifies the number of rows in the layout.
Specifies whether the external axes skip the empty cells in a partially filled grid.
Indicates whether to start populating the grid from the top left or bottom left corner.
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.
CELLHEIGHTMIN=dimension
specifies the minimum height of a cell in the grid.
Default: 100px
Use this option in conjunction with the CELLWIDTHMIN= option to set the minimum cell size.
The overall size of the panel is constrained by the HEIGHT= and WIDTH= options in the ODS GRAPHICS statement. As the number of cells in the grid increases, the size of each cell decreases. At some point the cell becomes so small that a meaningful graph cannot be rendered. This option sets the minimum height threshold for all cells. If the actual cell height becomes smaller, no panel is drawn.
CELLWIDTHMIN=dimension
specifies the minimum width of a cell in the grid.
Default: 100px
Use this option in conjunction with the CELLHEIGHTMIN= option to set the minimum cell size.
The overall size of the panel is constrained by the HEIGHT= and WIDTH= options in the ODS GRAPHICS statement. As the number of cells in the grid increases, the size of each cell decreases. At some point the cell becomes so small that a meaningful graph cannot be rendered. This option sets the minimum width threshold for all cells. If the actual cell width becomes smaller, no panel is drawn.
COLUMNAXISOPTS=(axis-options)
specifies X-axis options for all columns. For a list of options, see Axis Options for LAYOUT DATALATTICE/DATAPANEL.
Requirement: Axis options must be enclosed in parentheses and separated by spaces.
COLUMNDATARANGE=UNIONALL | UNION
specifies how the X-axes of instances of the graph-prototype are scaled.
Default: UNIONALL
UNIONALL
scales the X-axis data ranges across all layout columns and panels (when PANELNUMBER= is in effect).
UNION
scales the X-axis data ranges separately for each column on a per-panel basis. The scaling does not span across multiple panels.
Use the COLUMNAXISOPTS= option to control shared axis features.
Use the PANELNUMBER= option for a discussion of how to create multiple panels.
COLUMNGUTTER=dimension
specifies the amount of empty space that is between the columns.
Default: 0
If there are n columns, then there are n-1 gutters.
COLUMNHEADERS=TOP | BOTTOM | BOTH
specifies where to position the outside column header.
Default: TOP
TOP
specifies that column header text appears at the top of the layout.
BOTTOM
specifies that column header text appears at the bottom of the layout.
BOTH
specifies that column header text alternates between the top and bottom of the layout column by column.
Interaction: HEADERLABELLOCATION=OUTSIDE must be set for this option to have any effect.
COLUMNS=integer
specifies the number of columns in the layout.
Default:
  • If this option is not specified, the number of columns is dynamically adjusted to equal the number of classifier values for the COLUMVAR= variable.
  • If this option is specified, that many columns are created. If the number of COLUMNVAR classifier values is greater than the specified number of columns, no graph is created for some classifier values. If the number of classifier values is smaller than the specified number of columns, extra empty columns are created.
Interaction: The overall grid size is constrained by the HEIGHT= and WIDTH= options in the ODS GRAPHICS statement. As the grid size grows, the cell size shrinks. To control the minimum size of a cell use the CELLHEIGHTMIN= and CELLWIDTHMIN= options.
The START= option affects the how the columns are populated.
The PANELNUMBER= option enables you to create multiple smaller grids that completely partition the classifier values.
HEADERBACKGROUNDCOLOR=style-reference | color
specifies the background color of the cell headers.
Default: The GraphHeaderBackground:Color style reference.
style-reference
A reference in the form style-element:style-attribute. Only the style-attribute named COLOR is used.
Interaction: HEADEROPAQUE=TRUE must be in effect for the color to be seen.
HEADERLABELATTRS=style-element | style-element (text-options) | (text-options)
specifies the color and font attributes of the data labels. See General Syntax for Attribute Options for the syntax on using a style-element and Text Options for available text-options.
Default: The GraphValueText style element.
HEADERLABELDISPLAY=NAMEVALUE | VALUE
indicates whether the automatic cell header text includes variable name and value or just the value.
Default: NAMEVALUE
Example: If the classification variables were Country and Product, HEADERLABEL=NAMEVALUE would produce cell headers such as
  Country=CANADA
  Product=TABLE 
HEADERLABEL=VALUE would produce
  CANADA
  TABLE  
HEADERLABELLOCATION=OUTSIDE | INSIDE
indicates whether the cell header is placed within each cell (INSIDE) or as row and column headers external to the lattice (OUTSIDE).
Default: OUTSIDE
HEADEROPAQUE=boolean
specifies whether the background for cell headers is opaque (TRUE) or transparent (FALSE).
Default: TRUE
Interaction: When this option is set to FALSE, the background color for cell headers is not used.
INSET=(variable-list)
specifies what information is displayed in an inset. The variable-list defines one or more variables whose names and values appear as a small table in the data cells. The variables can be either numeric or character. Variable names are separated by spaces.
Default: no default
Restriction: No predefined information is available for the inset. You must create the desired inset information as part of your input data. This is most typically done as follows (see the chapter on classification panels and the chapter on insets in the SAS/GRAPH Graph Template Language User’s Guide for complete examples):
  • Create a separate data set for the inset columns making sure that the column names are different from the other columns used in graph. The number observations of inset data should match the number of cells in the classification panel. The ordering of the inset observations should be the same as population order of the cells of the classification panel taking into account the ROWVAR= and COLUMNVAR= arguments and the START= option. Typically, the number of observations for the inset data is smaller than the other input data for the graph.
  • Merge the inset data set with the data set for the graph using a DATA or PROC SQL step. Do not match-merge the observations of the two data sets (no BY processing). The resulting data set typically has the inset columns padded with missing values.
  • Use the merged data set to produce the graph, specifying the inset column names in this option’s variable-list.
The variable values are associated with the data cells by data order. That is, the first observation from all the variables in variable-list are used in the first data cell, the second observation from all variables in variable-list are used in the second data cell, and so on. If a value is missing for an observation, the corresponding name-value pair is skipped in the affected data cell.
The location and appearance of the inset is controlled by the INSETOPTS= option.
INSETOPTS=(appearance-options)
specifies location and appearance options for the inset information.
The appearance-options can be any one or more of the settings that follow. The options must be enclosed in parentheses, and each option is specified as a name = value pair.
AUTOALIGN=NONE | AUTO | (location-list)
specifies whether the inset is automatically aligned within the layout.
Default: NONE
NONE Do not automatically align this inset. This inset’s position is set by the HALIGN= and VALIGN= appearance-options.
AUTO Attempt to center this inset in the area that is farthest from any surrounding markers. Data cells might have different inset placements.
(location-list) Restrict this inset’s possible locations to those locations in the specified location-list, and use the location-list position that least collides with the data cell’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 BOTTOMRIGHT. Example: AUTOALIGN = (TOPRIGHT TOPLEFT)
Interaction: When AUTOALIGN=AUTO or (location-list), the HALIGN= and VALIGN= are ignored.
BACKGROUNDCOLOR= style-reference | color
specifies the color of the inset background
Default: The background is transparent. No color is assigned.
style-reference A reference of the form style-element : style-attribute. Only the style-attribute named COLOR is used.
BORDER= boolean
specifies whether a border is displayed around the inset.
Default: FALSE
HALIGN=LEFT | CENTER | RIGHT
specifies the horizontal alignment of the inset.
Default: LEFT
Interaction: This option is ignored unless AUTOALIGN=NONE.
OPAQUE= boolean
specifies whether the inset background is opaque (TRUE) or transparent (FALSE).
Default: FALSE
Interaction: When OPAQUE=FALSE, the background color is not used.
TEXTATTRS=style-element | style-element (text-options) | (text-options)
specifies the text properties of the entire inset. See General Syntax for Attribute Options for the syntax on using a style-element and Text Options for available text-options.
Default: The GraphDataText style element.
VALIGN=TOP | CENTER |BOTTOM
specifies the vertical alignment of the inset.
Default: TOP
Interaction: This option is ignored unless AUTOALIGN=NONE.
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.
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.
PANELNUMBER=positive-integer
specifies the number of the panel to produce.
Default: 1
This option enables you to partition a large grid into a number of smaller grids under these conditions:
  • You set a grid size explicitly (ROWS= and COLUMNS= when ROWVAR and COLUMNVAR variables are specified; ROWS= when only a ROWVAR variable is specified; COLUMNS= when only a COLUMNVAR variable is specified)
  • The grid size is smaller in one or both of the dimensions of the default dynamically generated grid.
  • You execute the template N times and increment the panel number each time. N is determined by CEIL(all rows * all columns / grid rows * grid columns).
Example: Suppose ROWVAR=R (R has 10 unique values) and COLUMNVAR=C (C has 11 unique values). The dynamic grid has 10 rows and 11 columns and you would have to make the HEIGHT=and WIDTH= quite large to enable 110 plots to be displayed. By setting some smaller grid size, say ROWS=3 and COLUMNS=4, and by making the value of PANELNUMBER= a dynamic or macro variable, you can create 10 panels (9 with 12 data cells and 1 with 2 data cells) that collectively display all 110 possible crossings. You simply invoke PROC SGRENDER or a DATA step 10 times, incrementing the dynamic value for PANELNUMBER each time.
ROWAXISOPTS=(axis-options)
specifies Y-axis options for all rows. For a list of options, see Axis Options for LAYOUT DATALATTICE/DATAPANEL.
Requirement: Axis options must be enclosed in parentheses and separated by spaces.
ROWDATARANGE=UNIONALL | UNION
specifies how the Y-axes of instances of the graph-prototype are scaled.
Default: UNIONALL
UNIONALL
scales the Y-axis data ranges across all layout rows and panels (when PANELNUMBER= is in effect).
UNION
scales the Y-axis data ranges separately for each row in the layout on a per-page basis. The scaling does not span across multiple pages.
Use the ROWAXISOPTS= option to control shared axis features.
See the PANELNUMBER= option for a discussion of how to create multiple panels.
ROWGUTTER=dimension
specifies the amount of empty space between the rows.
Default: 0
If there are n rows, then there are n-1 gutters.
ROWHEADERS=RIGHT | LEFT | BOTH
specifies where to position the outside row header.
Default: RIGHT
RIGHT
specifies that row header appears at the right of the layout.
LEFT
specifies that row header appears at the left of the layout.
BOTH
specifies that row header alternates between the right and left of the layout row by row.
HEADERLABELLOCATION=OUTSIDE must be set for this option to have any effect.
ROWS=integer
specifies the number of rows in the layout.
Default:
  • If this option is not specified, the number of rows is dynamically adjusted to equal the number of classifier values for the ROWVAR= variable.
  • If this option is specified, the specified number of rows is created. If the number of ROWVAR classifier values is greater than the specified number of rows, no graph is created for some classifier values. If the number of classifier values is smaller than the specified number of rows, extra empty rows are created.
Interaction: The overall grid size is constrained by the HEIGHT= and WIDTH= options in the ODS GRAPHICS statement. As the grid size grows, the cell size shrinks. To control the minimum size of a cell use the CELLHEIGHTMIN= and CELLWIDTHMIN= options.
The START= option affects the way the rows are populated.
The PANELNUMBER= option enables you to create multiple smaller grids that completely partition the classifier values.
SKIPEMPTYCELLS=boolean
specifies whether the external axes skip the empty cells in a partially filled grid.
Default: FALSE
FALSE
External axes are displayed at their normal locations, even if there are empty cells at one or more of the locations.
TRUE
External axes skip empty cells and "snap" to the nearest data cell, both vertically and horizontally. Though the empty cells are not displayed, the data cells in the grid are not enlarged to fill the area.
Discussion: Whenever the number of unique COLUMNVAR= classifier values (data cells) is not evenly divisible by the COLUMNS= value, or the number of unique ROWVAR= classifier values (data cells) is not evenly divisible by the ROWS= value, then one or more panels is partially filled with data cells and padded with empty cells to complete the grid.
In this example, there are 4 column-data cells and 3 row-data cells arranged in a 4-column, 2-row grid. This is default appearance of the last panel:
empty padding cells are displayed by default
When SKIPEMPTYCELLS=TRUE, the empty padding cells of all panels are removed and external axis ticks and tick values snap to the data cells:
empty padding cells are removed
START=TOPLEFT | BOTTOMLEFT
indicates whether to start populating the grid from the top left or bottom left corner.
Default: TOPLEFT
If ROWVAR=R has values in the sort order 1 and 2 and COLUMNVAR=C has values in the sort order a and b, then START=BOTTOMLEFT is populated as follows:
start set to bottomleft
START=TOPLEFT is populated as follows:
start set to topleft