

   SSppeecciiffyyiinngg ccoommpplleexx pplloott aarrrraannggeemmeennttss

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

   AArrgguummeennttss::

        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 exam-
             ples).

    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'.

   DDeessccrriippttiioonn::

        `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 argu-
        ments.  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 argu-
        ment controls whether a unit column-width is the same
        physical measurement on the device as a unit row-
        height.

   VVaalluuee::

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

   AAuutthhoorr((ss))::

        Paul R. Murrell

   RReeffeerreenncceess::

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

   SSeeee AAllssoo::

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

   EExxaammpplleess::

         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

