layout               package:graphics               R Documentation

_S_p_e_c_i_f_y_i_n_g _C_o_m_p_l_e_x _P_l_o_t _A_r_r_a_n_g_e_m_e_n_t_s

_D_e_s_c_r_i_p_t_i_o_n:

     'layout' divides the device up into as many rows and columns as
     there are in matrix 'mat', with the column-widths and the
     row-heights specified in the respective arguments.

_U_s_a_g_e:

     layout(mat, widths = rep(1, ncol(mat)),
            heights = rep(1, nrow(mat)), respect = FALSE)

     layout.show(n = 1)
     lcm(x)

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

       n: number of figures to plot.

       x: a dimension to be interpreted as a number of centimetres.

_D_e_t_a_i_l_s:

     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.

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

     'layout.show(n)' plots (part of) the current layout, namely the
     outlines of the next 'n' figures.

     'lcm' is a trivial function, to be used as _the_ interface for
     specifying absolute dimensions for the 'widths' and 'heights'
     arguments of 'layout()'.

_V_a_l_u_e:

     'layout' returns the number of figures, N, see above.

_W_a_r_n_i_n_g_s:

     These functions are totally incompatible with the other mechanisms
     for arranging plots on a device: 'par(mfrow)', 'par(mfcol)' and
     'split.screen'.

_A_u_t_h_o_r(_s):

     Paul R. Murrell

_R_e_f_e_r_e_n_c_e_s:

     Murrell, P. R. (1999) Layouts: A mechanism for arranging plots on
     a page.  _Journal of Computational and Graphical Statistics_, *8*,
     121-134. 

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

     Murrell, P. (2005) _R Graphics_. Chapman & Hall/CRC Press.

_S_e_e _A_l_s_o:

     'par' with arguments 'mfrow', 'mfcol', or 'mfg'.

_E_x_a_m_p_l_e_s:

     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