## Specifying complex plot arrangements

## Usage

    layout(mat,
           widths = rep(1, dim(mat)[2]),
           heights= rep(1, dim(mat)[1]),
           respect= FALSE)
    layout.show(n = 1)

## Arguments

`mat` | a matrix object specifying the location of the next N figures on the output device. Each value in the matrix must be `0` or a positive integer. If N is the largest positive integer in the matrix, then the integers {1,...,N-1} must also appear at least once in the matrix.
`widths` | a vector of values for the widths of columns on the device. Relative widths are specified with numeric values. Absolute widths (in centimetres) are specified with the `lcm()` function (see examples).
`heights` | a vector of values for the heights of rows on the device. Relative and absolute heights can be specified, see `widths` above.
`respect` | either a logical value or a matrix object. If the latter, then it must have the same dimensions as `mat` and each value in the matrix must be either `0` or `1`.

## Description

`layout` divides the device up into as many rows and columns as there are in `mat`, with the column-widths and the row-heights specified in the respective arguments. Figure i is allocated a region composed from a subset of these rows and columns, based on the rows and columns in which i occurs in `mat`. The respect argument controls whether a unit column-width is the same physical measurement on the device as a unit row-height.

## Value

The number of figures, N, see above, is returned.

## Author(s)

Paul R. Murrell

## References

Chapter 5 of Paul Murrell's Ph.D. thesis.

## See Also

`par(mfrow=..)`, `(mfcol=..)` and `(mfg=..)`

## Examples

     def.par <- par()# save default, for resetting...

     ## divide the device into two rows and two columns
     ## allocate figure 1 all of row 1
     ## allocate figure 2 the intersection of column 2 and row 2
     layout(matrix(c(1,1,0,2), 2, 2, byrow=T))
     ## show the regions that have been allocated to each plot
     layout.show(2)

     ## divide device into two rows and two columns
     ## allocate figure 1 and figure 2 as above
     ## respect relations between widths and heights
     nf <- layout(matrix(c(1,1,0,2), 2, 2, byrow=T), respect=T)
     layout.show(nf)

     ## create single figure which is 5cm square
     nf <- layout(matrix(1), widths=lcm(5), heights=lcm(5))
     layout.show(nf)

     ##-- Create a scatterplot with marginal histograms -----

     x <- rnorm(50)
     y <- rnorm(50)
     xhist <- hist(x, breaks=seq(-3,3,0.5), plot=F)
     yhist <- hist(y, breaks=seq(-3,3,0.5), plot=F)
     top <- max(c(xhist$counts, yhist$counts))
     xrange <- c(-3,3)
     yrange <- c(-3,3)
     nf <- layout(matrix(c(2,0,1,3),2,2,T), c(3,1), c(1,3), T)
     layout.show(nf)

     par(mar=c(3,3,1,1))
     plot(x, y, xlim=xrange, ylim=yrange, xlab="", ylab="")
     par(mar=c(0,3,1,1))
     barplot(xhist$counts, axes=F, ylim=c(0, top), space=0)
     par(mar=c(3,0,1,1))
     barplot(yhist$counts, axes=F, xlim=c(0, top), space=0, horiz=T)

     par(def.par)#- reset to default

[Package Contents]