How Axis Features Are Determined

Overview

The GTL uses various criteria to determine the displayed axis features for a graph. Generally, axis features are based on the following criteria:

the layout type
the order of plot statements in the layout and the options specified on those statements
the use of primary and secondary axes on the plots (when secondary axes are supported)
the plot type
the column or columns of data that contribute to defining the axis range
the data formats for the contributing data columns

While the default axis features depend on a combination of the factors above, it is useful to understand how the axis features are determined in the templates that you build:

how the data are mapped to the plot axes
how the various layout types manage the axes.

Plot Data Are Mapped to a Designated Axis

Overview for Axis Mapping

Depending on the layout type and the plots that you specify within the layout, you can manage up to four axes for two-dimensional plots:

a primary X (bottom) axis
a primary Y (left) axis
a secondary X axis (X2 or “top” axis)
a secondary Y axis (Y2 or “right” axis)

Within single-cell layouts (for example, OVERLAY layout), there can be just one each of these four axes. However, within multi-cell layouts (for example, LATTICE layouts), each cell can display the four axes. Thus, there can be multiple X, X2, Y, and Y2 axes across the columns and rows in the layout grid. In a lattice-type layout, you might have to use layout options to specify how the data ranges and axis display should be managed. This section discusses the simpler case for axis mapping, and Axis Mapping in Lattice-type Layouts discusses the case for lattice-type layouts.

Note: GRIDDED layouts can be used to create a grid of cells, but the cells are independent. Thus, axes in the grid cannot be managed across columns and rows, so the simpler case applies to GRIDDED layouts.

Primary and Secondary Axes

By default, plot data are mapped to the primary axes. To enable you to override the default, plot statements that support a secondary X2 axis provide an XAXIS= option that can map data to the X or X2 axis. Plot statements that support a Y axis provide a YAXIS= option that can map data to the Y or Y2 axis.

To determine the axis features within a layout, the GTL must first determine what data must be mapped to a particular axis. Thus, your use of primary and secondary axes on plot specifications affects the GTL’s determination of default axis features for the layout.

For example, the plot statements in the following template specify Y-data mappings to the Y2 and Y axes:

proc template;
  define statgraph y2axis;
    begingraph;
      layout overlay;
        histogram weight / scale=count yaxis=y2 ;
        histogram weight / scale=percent yaxis=y ;
        densityplot weight / normal();
      endlayout;
    endgraph;
  end;
run;
proc sgrender data=sashelp.class template=y2axis;
run;

In this example, the first HISTOGRAM maps its Y-axis data to the Y2 axis, and the second HISTOGRAM maps its Y-axis data to the Y axis. The DENSITY plot does not explicitly map its Y-axis data, so the default Y axis is used. None of the plots explicitly maps X-data, so the default X axis is used for all three plots. Thus, the GTL must manage any interactions that result from representing multiple plots on the X and Y axes. For example, on the X axis, it must determine an appropriate data range for representing the data values of all three plots.

When establishing axis features for each axis, the GTL determines which plot specifications map data to the axis. The GTL also collects the data for all of the plots that must be represented and maps that data to the designated axis. When Plots Share Data and a Common Axis discusses the criteria the GTL uses to determine the axis features for the axes after this mapping has been done for each axis.

Axis Mapping in Lattice-type Layouts

Lattice-type layouts (LAYOUT LATTICE, LAYOUT DATALATTICE, and LAYOUT DATAPANEL) present a grid of graphs that automatically aligns plot areas and tick display areas across grid cells. This alignment facilitates data comparisons among graphs, and for those comparisons to be meaningful, the graph axes must be coordinated across the columns and rows in the grid. All of the principles discussed in Overview for Axis Mapping apply to the lattice-type layouts. In addition, because there can be multiple X, X2, Y, and Y2 axes across grid cells, you might have to use layout options to specify how the data ranges and axis display should be managed.

For example, the following template uses a LAYOUT LATTICE to generate a grid that displays a height analysis next to a weight analysis. By default in a LAYOUT LATTICE statement, the options ROWDATARANGE= and ROW2DATARANGE= are set to DATA. The DATA setting scales the Y-axis and Y2-axis data ranges separately for each cell in the layout. To ensure that the Y-axis data range is the same in both cells, the example specifies ROWDATARANGE=UNION. Similarly, to ensure that the Y2-axis data range is the same in both cells, the example specifies ROW2DATARANGE=UNION:

proc template;
  define statgraph y2axis;
    begingraph;
      layout lattice / columns=2 columngutter=10
          rowdatarange=union row2datarange=union ;
        layout overlay;
          histogram height / scale=count yaxis=y2;
          histogram height / scale=percent yaxis=y;
          densityplot height / normal();
        endlayout;
        layout overlay;
          histogram weight / scale=count yaxis=y2;
          histogram weight / scale=percent yaxis=y;
          densityplot weight / normal();
        endlayout;
      endlayout;
    endgraph;
  end;

proc sgrender data=sashelp.class template=y2axis;
run;

By default in a LAYOUT LATTICE statement, the options COLUMNDATARANGE= and COLUMN2DATARANGE= are also set to DATA. But in this analysis, the height is a separate measure from the weight, so the separate scales are appropriate for the X-axes across cells. If the X-axes were displaying the same measure (for example, comparing the height of female subjects to the height of male subjects), you could specify COLUMNDATARANGE=UNIONALL. This would set the same scaling to the X-axis data ranges across the two layout columns. In this example you would not bother changing the default COLUMN2DATARANGE= setting because the X2 axis is not needed.

Note: For DATALATTICE and DATAPANEL statements, UNIONALL is the default value for the data ranges. Thus, you would not have to change the data ranges unless you wanted to set UNION to scale data ranges per row or per column in the layout.

In the example, scaling the data ranges across the row ensures proper axis scaling. However, the graph display is cluttered by the duplicate display of ticks, axis values, and axis labels on both the Y and Y2 axes. To simplify the display, you can consolidate the axes. To do so, use a ROWAXES block to display a single Y axis for both cells, and a ROW2AXES block to display a single Y2 axis for both cells. The consolidated view removes the internal axes from the grid and displays only the external axes:

proc template;
  define statgraph y2axis;
    begingraph;
      layout lattice / columns=2 columngutter=10
          rowdatarange=union row2datarange=union;
        rowaxes;
          rowaxis / griddisplay=on;
        endrowaxes;
        row2axes;
          rowaxis;
        endrow2axes;
        layout overlay;
          histogram height / scale=count yaxis=y2;
          histogram height / scale=percent yaxis=y;
          densityplot height / normal();
        endlayout;
        layout overlay;
          histogram weight / scale=count yaxis=y2;
          histogram weight / scale=percent yaxis=y;
          densityplot weight / normal();
        endlayout;
      endlayout;
    endgraph;
  end;

proc sgrender data=sashelp.class template=y2axis;
run;

When using ROWAXES or ROW2AXES blocks in a LATTICE layout, you nest within the block one ROWAXIS statement for each row in the layout grid. The ROWAXIS statements are applied sequentially to the rows, and each ROWAXIS statement specifies the axis options for the Y or Y2 axes in its corresponding row. ROWAXIS statements within the ROWAXES block apply to the Y axes, and ROWAXIS statements within the ROW2AXES block apply to the Y2 axes. This example has just a single row in the grid, so each block specifies only one ROWAXIS statement. Notice that the ROWAXIS statement in the ROW2AXES block does not use any options. Thus, it consolidates Y2 axes in the row into a single, external Y2 axis, but it does not alter the default features of that axis. For columns in the grid, the LATTICE layout provides COLUMNAXES and COLUMN2AXES blocks. These blocks use COLUMNAXIS statements to externalize X and X2 axes and specify their features.

When you use DATALATTICE and DATAPANEL layouts, the layout dynamically generates a grid that contains as many cells as can be produced from the combination of classification values. In those layouts the axes are always external, and you can use the COLUMNAXISOPTS=, COLUMN2AXISOPTS=, ROWAXISOPTS=, and ROW2AXISOPTS= options to specify the features for the axes. The settings on each option apply across the entire grid. For example, if you specify the ROWAXISOPTS= option in a DATALATTICE layout, the specified settings apply to the external Y axes in every row.

When Plots Share Data and a Common Axis

Overview

If a layout block contains multiple plots that share data and a common axis, the plot settings often interact in ways that affect the axis features. Axis features include the axis type, axis label, tick-mark layout, and so on. The GTL resolves these interactions in ways that vary according to the layout block and plot statements.

Note: Axis interactions might not occur if other settings in the template prevent them. As discussed in Plot Data Are Mapped to a Designated Axis, if two plot statements are within an OVERLAY layout, one of them might map its data to the X axis and the other might map its data to the X2 (top) axis. Mapping to separate axes can avoid the interactions that might occur if they both mapped their data to the X axis.

Axis Features in Overlay-type Layouts

Overlay-type layouts (OVERLAY, OVERLAYEQUATED, and PROTOTYPE, for example) build a composite from one or more GTL-statements.

Within overlay-type layouts, if you do not explicitly set axis features in your template statements, the GTL automatically determines them. It sets the axis features based on the layouts and plots in the layout block and the data that are associated with the template at run time.

If only one plot statement within an overlay-type layout generates an axis, then determining axis features is straight forward: the features are derived directly from the plot type and the columns that are used for the plot data. For example, if a LAYOUT OVERLAY block contains a single SCATTERPLOT and the X variable specifies a numeric column of children’s weights, the default X-axis type is LINEAR. The default X-axis label is the column label of the WEIGHT variable. If the WEIGHT variable has no defined label, the column name is used as a label.

When an overlay-type layout contains multiple plots that generate axes, the GTL can determine default axis features for the shared axes. Alternatively, you can use the PRIMARY= option on one of the plot statements to specify which plot you want the GTL to use. The following code fragment explicitly specifies that the SCATTERPLOT of children’s weights be used to determine axis features within the layout:

layout overlay;
  scatterplot x=weight ... / primary=true;
  ...

If no plot in an overlay-type layout is designated as primary, the first plot that generates an axis is considered primary on a per-axis basis.
If PRIMARY=TRUE for a plot within an overlay-type layout, that plot’s data columns, data type, and plot type determine the default axis features. An explicitly specified primary plot determines the default axis features regardless of where that plot statement occurs within the layout block.
Only one plot can be primary on a per-axis basis. If multiple plots specify PRIMARY=TRUE for the same axis, the last one encountered is considered primary.

The following SCATTERPLOT specifies a string variable on the X= argument:

layout overlay;
  scatterplot x=name ... / primary=true;
  ...

In this case, the default X-axis type is DISCRETE and the X-axis label is the column label of NAME, or the column name if no label exists.

Note: The SAS format on the primary plot’s column determines the axis format, although the axis might not use that SAS format “as-is” from the column.

If a SCATTERPLOT’s X= argument specifies a column that has a SAS DATETIME format, the default X-axis type is TIME. The default X-axis label is the column label or name of the DATETIME column:

layout overlay;
  scatterplot x=date ... / primary=true;
  ...

For some plot types, the default axis type does not directly correlate to the specified column’s data type. For example, the following code fragment specifies a BARCHART for the numeric column AGE:

layout overlay;
  barchart x=age ... / primary=true;
  ...

Because a BARCHART requires a discrete X axis, the default X-axis type in this case is DISCRETE, in spite of the fact that column AGE is numeric. The X-axis label is the column label of AGE, or the column name if no label exists.

Finally, consider a HISTOGRAM that is set as the primary plot in the layout and that bins data values:

layout overlay;
  histogram weight / binaxis=true primary=true;
  ...

In this case, the default X-axis type is LINEAR, but the histogram’s data bins are used by default as the basis for the axis tick marks.

Axis Features in Data Panel and Data Lattice Layouts

The criteria discussed inAxis Features in Overlay-type Layouts apply to determining the default axis features for the plots within DATAPANEL and DATALATTICE layouts. Both of these layout types nest a LAYOUT PROTOTYPE statement within their layout blocks. In both cases, the plot statements within the LAYOUT PROTOTYPE block—an overlay-type layout—determine the axis features for the plot display.

Axis Features in Lattice-type Layouts

The LAYOUT LATTICE statement can create a grid of graphs that automatically aligns plot areas, data display areas, labels, and headers across the columns and rows in the layout. The layout gives you the option of unifying the scale of the data ranges that are displayed in the graphs.

If a LAYOUT LATTICE specification generates only one cell, then no competition exists between cells for determining axis features in the display. In this case, the axis features are derived directly from the plot type and the columns used for the plot data.

Similarly, for multi-cell displays, if any or all of the options COLUMNDATARANGE=, COLUMN2DATARANGE=, ROWDATARANGE=, or ROW2DATARANGE= use the DATA setting to scale axis data ranges separately for each cell in the layout, then the layout cells are data-independent. The data-independent cells do not interact with each other for determining the axis features in the display.

Axes are shared in the layout when one of the options COLUMNDATARANGE=, COLUMN2DATARANGE=, ROWDATARANGE=, or ROW2DATARANGE= is used to unite axis data ranges for layout cells. By default in those cases, the first cell that is drawn (by default, the top left cell) determines the axis features in the display. When UNIONALL is in effect, those same features are used in all of the grid’s layout cells. When UNION is in effect, those same features are used on a per-row or per-column basis. If you specify external axes for the columns or rows in the layout, you can specify desired axis features on the appropriate COLUMNAXIS or ROWAXIS statements used in the layout.

For an example LATTICE layout with external axes, see Axis Mapping in Lattice-type Layouts.

Axis Features in Gridded Layouts

In a GRIDDED layout the layout cells are independent of one another. Plot statements within the layout cells do not share data and are not represented on a common axis. Thus, no competition exists among layout cells for determining the axis features.

Plot Axis Types Must Agree on Common Axes

The GTL is extremely flexible and enables you to generate a wide variety of plot displays. However, if you request incompatible plot displays within the same layout, the results are unpredictable.

When Plots Share Data and a Common Axis discusses the criteria GTL uses to determine the default axis features. After the axis type has been determined, the GTL expects that all plots that share that axis will have the assigned axis type. The expectation applies whether you specify axis features in your template or let GTL determine default features.

For example, a BOXPLOT cannot be overlaid by a LINEPARM: the two types of plot cannot share axes because the plot types are incompatible within the same set of axes. Thus, if you were to use both a BOXPLOT statement and a LINEPARM statement within a LAYOUT OVERLAY block, only one of them can be displayed. The GTL therefore displays the primary plot (the first specified plot by default, or the plot designated as primary by setting PRIMARY=TRUE). The other plot is not displayed.

Similarly, a BARCHART requires a discrete X-axis, whereas a HISTOGRAM cannot be displayed on a discrete axis. If you specify both a BARCHART and a HISTOGRAM within the same overlay-type layout, only the primary plot is displayed and the other plot is rejected from the display.

Axis types must also be the same for plots that must share an axis across the columns or rows in a multi-cell layout. For example, in a LAYOUT LATTICE, the GTL expects that plots have the same axis type and data ranges if they are to share an external axis. Otherwise, the external axis cannot be displayed for that row or column.