setLayout: Graph Layout

View source: R/setLayout.R

setLayoutR Documentation

Graph Layout

Description

Set up the layout of one or more graphs on a page.

Usage

setLayout(width = NULL, height = NULL, num.cols = max(1,
  length(width)), num.rows = max(1, length(height)),
  num.graphs = num.rows * num.cols, explanation = NULL,
  shared.x = -1, shared.y = -1, yleft = 3.5, yright = NA,
  xbottom = 3.2, xtop = NA)

Arguments

width

the width of the graph area, exclusive of any explanation. Can be either the total width or the width of each column of graphs. If NULL, then use default figure width. See Details.

height

the height of the graph area, exclusive of explanation. Can be either the total width or the height of each row of graphs. If NULL, then use defualt figure height.

num.cols

the number of columns in the rectangular array of graphs. Computed from width if not supplied.

num.rows

the number of rows in the rectangular array of graphs. Computed from height if not supplied.

num.graphs

the number of actual graphs in the rectangular array of graphs.

Computed from num.cols and num.rows if not supplied. Note that if the EXPLANATION is to be placed in one of the array of graphs, then num.graphs must be less than the product of num.cols and num.rows.

explanation

a description of where to place the explanation if put into a separate graph. See Details.

shared.x

indicate how the x axes are to be shared. See Details.

shared.y

indicate how the y axes are to be shared. If < 0, then no sharing–each has own axis labels, etc. If = 0, then axes in direct contact. If > 0, then the value indicates the relative spacing.

yleft

space to allocate on the left margin of each graph.

yright

space to allocate on the right margin of each graph. See Details.

xbottom

space to allocate on the bottom margin of each graph.

xtop

space to allocate on the top margin of each graph. See Details.

Details

The layout of multple graphs on a page is always set up as a rectangular grid. The columns can be specified in one of two ways, either by specifying the width of each column using width or setting equal-width columns by specifying num.cols. The rows can be specified in one of two ways, either by specifying the height of each column using height or setting equal-height rows by specifying num.rows.

If an explanation is to be placed outside of the graphs, then explanation is used to indicate where the explanation is to be placed. The explanation can be placed either to the right of the grid of graphs, at the bottom of the grid, or in one of the grid cells.

To place an explanation to the right of the graphs, explantion should be set to list(right=ewid), where ewid is the width of the explanation. In this case, the total of width and ewid must be less that the total available for the page.

To place an explanation at the bottom of the graphs, explantion should be set to list(bottom=ehei), where ehei is the height of the explanation. In this case, the total pf height and ehei must be less than the total available for the page.

To place an explanation within a cell of the grid, explantion should be set to list(grid=enum), where enum is the cell number in the grid. Cell numbers are sequential starting in the upper left and increasing by column. In this case num.graphs must be set to some number less than num.cols times num.rows.

The width of the explanation can be estimated by allocating 1 inch per 13 characters for font set to "preview" or 1 inch per 17 characters for font set to "USGS" plus 0.5 inch for the symbols. The width for box plots should be 2 inches for any type other that "tukey" and 2.5 inches for "tukey." The height of the explanation can be estimated as 1 inch per 8 lines of explanation for font set to "preview" and 1 inch per 10 lines of explanation for font set to "USGS"—allocate an extra 2 lines for the title. Box plots require about 3 inches for the truncated and simple types and about 4.5 inches for type "tukey" and about 4 inches for type "extended." The plot area within each cell is set up to have consistent widths within each column and consistent heights within each row.

The arguments yleft, yright, xbottom, and xtop are used to set up the plot area margins. If axes are not shared, then the margin values are set for any graph using those values. If the axes are shared, then the margin values apply to the corresponding left column, right column, bottom row or top row. The values for yleft and xbottom are useful defaults. If the y-axis labels are wider than typical values, such as those for very large numbers or names, then the value for yleft should be increased. If the x-axis labels are rotated, then the value for xbottom should be increased.

The arguments shared.x and shared.y control axis sharing. If the values are negative, then the axes are not shared and the margins are set as described in the preceding paragraph. If the values are nonnegative, then the axes are shared and the margin is set by the value. For example, a value of 0 means the axes are touching. A value of 1 generally gives enough spacing between the plots to prevent overlapping labels.

The axis ticks and labels can be supressed by setting the margins to a negative value. This is most useful when adding right-axes with addXY for example.

The value for yright can be set using the setRtMargin function if adding a plot using the secondary right axes; extract the fourth element of the returned value. The default is to set a narrow right-hand margin.

The value for xtop can be set to -2.2 if adding a plot using the secondary top axis. The default is to set the margin to 1.5, which allows only for a graph title.

Value

an object of class "Layout" with three named components and num.graphs numbered components:

explanation and each numbered component

a list with two components:

margin

the margin for the plot area

fig

the figure area

size

the size of the overall figure

mat

the figure layout

Note

It is very easy to confuse the graph number, used by setGraph and the grid cell number referenced in setlayout. The grid cell number always ranges from 1 to the number of columns times the number of rows. The graph number ranges from 1 to num.graphs and skips the grid cell number if defined in the explanation argument. Printing the output object can help understand the graph layout.

There is nothing special about the cell allocated for the explanation; it has no special characteristics, therefore an explantion can be placed in any graph numbered cell and anything can be placed in the "explanation" cell. As an example, the "explanation" at the bottom of the figure can be used for a description of the figure that is more than one line in height.

See Also

setPage, setGraph, setRtMargin, addTitle

Examples

## Not run: 
# See for examples of setLayout:
vignette(topic="BoxPlots", package="smwrGraphs")
vignette(topic="GraphGallery", package="smwrGraphs")
vignette(topic="GraphSetup", package="smwrGraphs")
vignette(topic="PiperPlot", package="smwrGraphs")
demo(topic="HydroPrecip", package="smwrGraphs")
demo(topic="PiperScript", package="smwrGraphs")

## End(Not run)

USGS-R/smwrGraphs documentation built on Oct. 11, 2022, 6:11 a.m.