subplot            package:TeachingDemos            R Documentation

_E_m_b_e_d _a _n_e_w _p_l_o_t _w_i_t_h_i_n _a_n _e_x_i_s_t_i_n_g _p_l_o_t

_D_e_s_c_r_i_p_t_i_o_n:

     Subplot will embed a new plot within an existing plot at the
     coordinates specified (in user units of the existing plot).

_U_s_a_g_e:

     subplot(fun, x, y, size=c(1,1), vadj=0.5, hadj=0.5, pars=NULL)

_A_r_g_u_m_e_n_t_s:

     fun: an expression defining the new plot to be embedded.

       x: 'x'-coordinate(s) of the new plot (in user coordinates of the
          existing plot).

       y: 'y'-coordinate(s) of the new plot, 'x' and 'y' can be
          specified in any of the ways understood by 'xy.coords'.

    size: The size of the embedded plot in inches if 'x' and 'y' have
          length 1.

    vadj: vertical adjustment of the plot when 'y' is a scalar, the
          default is to center vertically, 0 means place the bottom of
          the plot at 'y', 1 places the top of the plot at 'y'.

    hadj: horizontal adjustment of the plot when 'x' is a scalar, the
          default is to center horizontally, 0 means place the left
          edge of the plot at 'x', and 1 means place the right edge of
          the plot at 'x'.

    pars: a list of parameters to be passed to 'par' before running
          'fun'.

_D_e_t_a_i_l_s:

     The coordinates 'x' and 'y' can be scalars or vectors of length 2.
      If vectors of length 2 then they determine the opposite corners
     of the rectangle for the embedded plot (and the parameters 'size',
     'vadj', and 'hadj' are all ignored.

     If 'x' and 'y' are given as scalars then the plot position
     relative to the point and the size of the plot will be determined
     by the arguments 'size', 'vadj', and 'hadj'.  The default is to
     center a 1 inch by 1 inch plot at 'x,y'.  Setting 'vadj' and
     'hadj' to '(0,0)' will position the lower left corner of the plot
     at '(x,y)'.

     The rectangle defined by 'x', 'y', 'size', 'vadj', and 'hadj' will
     be used as the plotting area of the new plot. Any tick marks, axis
     labels, main and sub titles will be outside of this rectangle.

     Any graphical parameter settings that you would like to be in
     place before 'fun' is evaluated can be specified in the 'pars'
     argument (warning: specifying layout parameters here ('plt',
     'mfrow', etc.) may cause unexpected results).

     After the function completes the graphical parameters will have
     been reset to what they were before calling the function (so you
     can continue to augment the original plot).

_V_a_l_u_e:

     An invisible list with the graphical parameters that were in
     effect when the subplot was created.  Passing this list to 'par'
     will enable you to augment the embedded plot.

_A_u_t_h_o_r(_s):

     Greg Snow greg.snow@intermountainmail.org

_S_e_e _A_l_s_o:

     'cnvrt.coords', 'par', 'symbols'

_E_x_a_m_p_l_e_s:

     # make an original plot
     plot( 11:20, sample(51:60) )

     # add some histograms

     subplot( hist(rnorm(100)), 15, 55)
     subplot( hist(runif(100),main='',xlab='',ylab=''), 11, 51, hadj=0, vadj=0)
     subplot( hist(rexp(100, 1/3)), 20, 60, hadj=1, vadj=1, size=c(0.5,2) )
     subplot( hist(rt(100,3)), c(12,16), c(57,59), pars=list(lwd=3,ask=FALSE) )

     # augment a map
     if( require(TeachingDemos) && require(maptools) ){
             plot(state.vbm,fg=NULL)
             tmp <- t(sapply(state.vbm, function(x) attr(x,"centroid")))
             for( i in 1:50 ){
                     tmp2 <- as.matrix(USArrests[i,c(1,4)])
                     tmp3 <- max(USArrests[,c(1,4)])
                     subplot( barplot(tmp2, ylim=c(0,tmp3),names=c('',''),yaxt='n'),
                             x=tmp[i,1], y=tmp[i,2], size=c(.1,.1))
             }
     }

     tmp <- rnorm(25)
     qqnorm(tmp)
     qqline(tmp)
     tmp2 <- subplot( hist(tmp,xlab='',ylab='',main=''), 
                     cnvrt.coords(0.1,0.9,'plt')$usr, vadj=1, hadj=0 )
     abline(v=0, col='red') # wrong way to add a reference line to histogram

     # right way to add a reference line to histogram
     op <- par(no.readonly=TRUE)
     par(tmp2)
     abline(v=0, col='green')
     par(op)

     # scatter-plot using images
     if(require(rimage)){
             data(logo)

             x <- runif(10)
             y <- runif(10)

             plot(x,y,type='n')
             for(i in 1:10){
                     subplot(plot(logo),x[i],y[i],size=c(.3,.3))
             }
     }

