\HeaderA{layout}{Specifying Complex Plot Arrangements}{layout}
\methaliasA{layout.show}{layout}{layout.show}
\aliasA{lcm}{layout}{lcm}
\keyword{iplot}{layout}
\keyword{dplot}{layout}
\keyword{environment}{layout}
\begin{Description}\relax
\code{layout} divides the device up into as many rows and columns as
there are in matrix \code{mat}, with the column-widths and the
row-heights specified in the respective arguments.
\end{Description}
\begin{Usage}
\begin{verbatim}
layout(mat, widths = rep(1, ncol(mat)),
       heights = rep(1, nrow(mat)), respect = FALSE)

layout.show(n = 1)
lcm(x)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{mat}] a matrix object specifying the location of the next
\eqn{N}{} figures on the output device.  Each value in the matrix must
be \code{0} or a positive integer.  If \eqn{N}{} is the largest
positive integer in the matrix, then the integers
\eqn{\{1,\dots,N-1\}}{} must also appear at least once in the matrix.
\item[\code{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 \code{lcm()} function (see
examples).
\item[\code{heights}] a vector of values for the heights of rows on the device.
Relative and absolute heights can be specified, see \code{widths} above.
\item[\code{respect}] either a logical value or a matrix object.  If the
latter, then it must have the same dimensions as \code{mat} and
each value in the matrix must be either \code{0} or \code{1}.
\item[\code{n}] number of figures to plot.
\item[\code{x}] a dimension to be interpreted as a number of centimetres.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Figure \eqn{i}{} is allocated a region composed from a subset
of these rows and columns, based on the rows and columns
in which \eqn{i}{} occurs in \code{mat}.

The \code{respect} argument controls whether a unit column-width is
the same physical measurement on the device as a unit row-height.

There is a limit (currently 50) for the numbers of rows and columns
in the layout, and also for the total number of cells (500).

\code{layout.show(n)} plots (part of) the current layout, namely the
outlines of the next \code{n} figures.

\code{lcm} is a trivial function, to be used as \emph{the} interface
for specifying absolute dimensions for the \code{widths} and
\code{heights} arguments of \code{layout()}.
\end{Details}
\begin{Value}
\code{layout} returns the number of figures, \eqn{N}{}, see above.
\end{Value}
\begin{Section}{Warnings}
These functions are totally incompatible with the other mechanisms for
arranging plots on a device: \code{\LinkA{par}{par}(mfrow)},
\code{par(mfcol)} and \code{\LinkA{split.screen}{split.screen}}.
\end{Section}
\begin{Author}\relax
Paul R. Murrell
\end{Author}
\begin{References}\relax
Murrell, P. R. (1999) Layouts: A mechanism for arranging plots on a page. 
\emph{Journal of Computational and Graphical Statistics},
\bold{8}, 121-134. 

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

Murrell, P. (2005) \emph{R Graphics}. Chapman \& Hall/CRC Press.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{par}{par}} with arguments \code{mfrow}, \code{mfcol}, or
\code{mfg}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
def.par <- par(no.readonly = TRUE) # 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 = TRUE))
## 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=TRUE), respect=TRUE)
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 <- pmin(3, pmax(-3, stats::rnorm(50)))
y <- pmin(3, pmax(-3, stats::rnorm(50)))
xhist <- hist(x, breaks=seq(-3,3,0.5), plot=FALSE)
yhist <- hist(y, breaks=seq(-3,3,0.5), plot=FALSE)
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,byrow=TRUE), c(3,1), c(1,3), TRUE)
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=FALSE, ylim=c(0, top), space=0)
par(mar=c(3,0,1,1))
barplot(yhist$counts, axes=FALSE, xlim=c(0, top), space=0, horiz=TRUE)

par(def.par)#- reset to default
\end{ExampleCode}
\end{Examples}

