Example Program and Statement Details

Example Graph

The following graph was generated by the Example Program:
Example Layout DataPanel Graph

Example Program

This example shows a four-column, three-row data panel using two classification variables. With this layout, each data cell is subsetted and labeled with the values of the classification variables.
  • 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 layoutdatapanel;
  begingraph;
    entrytitle "Annual Furniture Sales Comparisons";    
    layout datapanel classvars=(country year) / 
      columns=4 rows=3 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=top;        
        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=layoutdatapanel;
run;

Statement Summary

The LAYOUT DATAPANEL statement creates a grid of graphs, based on the values of one or more classifications variables. The main differences between this layout and the DATALATTICE layout is that this layout supports more than two classification variables, and it provides more control over the grid layout.
By default, the number of cells in the layout is determined by a crosstabulation table of all the classification variables 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= option or the ROWS= option, or both with the PANELNUMBER= option to generate multiple panel displays.
The order of the value pairings for the classification variables is determined by the order that the variables are specified on the CLASSVARS= argument. The last named variable’s values vary most rapidly (like nested DO loops). Variable values are always returned in data order.
By default, the first data cell to be filled is in the layout’s top left corner, and data cells are filled from left-to-right, top-to-bottom. Use the START= option to change the starting data cell to the bottom left corner, and use the ORDER= option to determine whether data cells fill by column or by row. See the START= option for illustrations on how START= and ORDER= interact to manage the fill sequence for data cells.
Note: The DATAPANEL layout is designed to be the outermost layout in the template.

Required Argument

CLASSVARS=(class-var1 …class-varN)
specifies a list of classification variables. By default, a data cell is created for each crossing of these variables in the input data. The total number of grid cells created is the result of a crosstabulation table of all the classification variables plus any empty cells needed to complete the last row/column of the grid. You can request that data cells be generated for all possible crossings, even when the class variables have no values at those crossings. For more information, see the SPARSE= option.
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 DATAPANEL 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 DATAPANEL block, using the following syntax:
LAYOUT PROTOTYPE </option(s)>;
GTL-statements;
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 DATAPANEL enables you to display sidebars outside of the axis areas. 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 DATAPANEL, one for each of the bottom, top, left, and right sidebar positions.
  • The LAYOUT DATAPANEL 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 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.
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 whether cells are populated by column priority or by row priority.
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 the number of rows in the layout.
Specifies whether the external axes skip the empty cells in a partially filled grid.
Specifies whether crossings of the class variables include only the crossing in the data or all possible crossings.
Indicates whether to start populating the data cells 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-reference
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
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.
See 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.
COLUMNS=integer
specifies the number of columns in the layout.
Default:
  • If this option is not specified and ROWS= is specified, the number of data cells (and columns) increases dynamically to allow all classifier values to be presented.
  • If both this option and ROWS= are specified, a grid of that size is created, regardless of the number of classifier values. If the number of classifier values is greater than the grid size, no graphs is created for some classifier values. If the number of classifier values is small and the grid size large, there might be empty cells created.
Interaction: The overall grid size is constrained 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= and ORDER= options affect the how the rows 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 
and HEADERLABEL=VALUE would produce
  CANADA
  TABLE
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 CLASSVARS= argument and the ORDER= and START= options. 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= appearance-options 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.
ORDER=ROWMAJOR | COLUMNMAJOR
specifies whether data cells are populated by column priority or by row priority.
Default: ROWMAJOR
COLUMNMAJOR
fills the data cells by columns, from the starting position.
ROWMAJOR
fills the data cells by rows, from the starting position.
PACKED
fills all pages in ROWMAJOR order, using START=TOPLEFT. When the last page is reached and it is a partial page (fewer than ROWS*COLUMNS), the number of rows and columns of cells is adjusted, based on an internal algorithm.
Interaction: The starting point for rendering data cells is controlled by the START= option. See the START= option for examples.
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 sized grids under these conditions:
  • You set a grid size explicitly ( ROWS= and COLUMNS= options).
  • The grid size (gridrows x gridcolumns) is smaller than the total number of classifier levels.
  • You execute the template N times and increment the panel number each time. N is determined by CEIL(total-classification-levels / gridrows x gridcolumns).
Example: Suppose there are two classifiers (CLASS1 has 10 unique values and CLASS2 has 11 unique values). By setting some smaller grid size, say ROWS=3 and COLUMNS=4, and making the value of PANELNUMBER= a dynamic or macro variable, you can create 10 panels (9 panels with 12 data cells and 1 panel 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 that is before the first row, between the rows, and after the last row.
Default: 0
If there are n rows, then there are n-1 gutters.
ROWS=integer
specifies the amount of empty space between the rows.
Default:
  • If this option is not specified and COLUMNS= is specified, the number of data cells (and rows) increases dynamically to allow all classifier values to be presented.
  • If both this option and COLUMNS= are specified, a grid of that size is created, regardless of the number of classifier values. If the number of classifier values is greater than the grid size, no graphs is created for some classifier values. If the number of classifier values is small and the grid size large, there might be empty cells created.
Interaction: The overall grid size is constrained 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= and ORDER= options affect 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 total number of classifier crossings (data cells) is not evenly divisible by the panel size (columns * rows), the last panel is partially filled with data cells and padded with empty cells to complete the grid.
In this example, there are 16 data cells arranged in a 4-column, 3-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 the last panel are removed and external axis ticks and tick values snap to the data cells:
Empty Padding Cells are Removed
Note that SKIPEMPTYCELLS=TRUE removes only the empty padding cells on the last panel. It does not remove any data cells that have no crossing values and therefore no graph (these data cells are displayed when SPARSE=TRUE).
SPARSE=boolean
Specifies whether crossings of the class variables include only the crossings in the data or all possible crossings.
Default: FALSE
FALSE
Data cells are created only for crossings of the class variables that are in the data.
TRUE
The number of data cells is the product of the unique values for each classification variable.
By default, if a crossing of the class variables has a missing value as part of the data, a data cell is created for it.
Discussion: In this example, the classification variables are COUNTRY and STATE. There are 3 distinct values of COUNTRY (Canada, Mexico, and U.S.A.) Within Canada and Mexico there are 4 states, and within U.S.A. there are 8 states. All state names are unique to each country. Therefore, there are 16 unique STATE values and 48 unique crossings of COUNTRY and STATE, but there are data for only 16 of the crossings.
Assume that a data panel layout is created with COLUMNS=6 and SPARSE=TRUE, meaning to display all possible crossings. This is what the first row would look like, with blank data cells being added whenever there are no data values for a crossing:
Empty Cells Displayed
When SPARSE=FALSE the crossings of the classifiers with no data are automatically removed. This compacts the display:
Empty Cells Removed
START=TOPLEFT | BOTTOMLEFT
indicates whether to start populating the grid cells from the top left or bottom left corner.
Default: TOPLEFT
Interaction: If ORDER=ROWMAJOR (the default) and START=TOPLEFT (the default), a 2 row 2 column grid is populated as
cell 1
cell 2
cell 3
cell 4
If ORDER=ROWMAJOR (the default) and START=BOTTOMLEFT, a 2 row 2 column grid is populated as
cell 3
cell 4
cell 1
cell 2
If ORDER=COLUMNMAJOR and START=BOTTOMLEFT, a 2 row 2 column grid is populated as
cell 2
cell 4
cell 1
cell 3
If ORDER=COLUMNMAJOR and START=TOPLEFT, a 2 row 2 column grid is populated as
cell 1
cell 3
cell 2
cell 4