ContourScatterPlot         package:rflowcyt         R Documentation

_I_m_a_g_e _a_n_d _C_o_n_t_o_u_r _B_i_v_a_r_i_a_t_e _P_l_o_t

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

     To make a bivariate image with a rectangular grid and a
     superimposed contour plot of two variables or to make a bivariate
     hexbin image plot from a hexagon grid with NO superimposed contour
     plot.

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

     ContourScatterPlot(xvar, yvar,
                        status=NULL,
                        type.CSP=c("count.diff", "p.hat", "p.hat.norm", "z.stat"),
                        xlab = NULL, ylab = NULL, main = NULL,
                         x.grid = round(seq(range(xvar)[1],
                                       ceiling(diff(range(xvar))/25)*25+range(xvar)[1],
                                       by=25),0),
                         y.grid =round(seq(range(yvar)[1],
                                       ceiling(diff(range(yvar))/25)*25+range(yvar)[1],
                                       by=25),0),
                        lattice=FALSE,
                        hexbin.plotted=FALSE,
                        hexbin.style=c("colorscale", "lattice", "centroids",
                                  "nested.lattice", "nested.centroids"),
                        n.hexbins=100, numlev = 5, xaxt="s", yaxt="s",image.col = heat.colors(10),
                        ...)

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

    xvar: numerical vector of the x-variable 

    yvar: numerical vector of the y-variable 

  status: numerical binary 0, 1 vector denoting the status of the
          observations; default is NULL

type.CSP: character string denoting the type of value to be estimated
          using the 'status' for each cell grid: the difference in
          counts ("count.diff"), the proportion ("p.hat"), the
          normalized proportion at 0.5 ("p.hat.norm"), the z.statistic
          ("z.stat"), see make.density for details.

    xlab: character string of the x-variable name 

    ylab: character string of the y-variable name 

    main: character string of title of the plot

  x.grid: numerical vector of the x-axis breaks for the image plot
          using the rectangular grid; default is a vector of values
          within the range of 'xvar' separated by 25 units increments.

  y.grid: numerical vector of the y-axis breaks for the image plot
          using the rectangular grid; default is a vector of values
          within the range of 'yvar' separated by 25 units increments.

hexbin.plotted: boolean; if TRUE then the grid cells/compartments are
          hexagons; otherwise the grid cells are rectangular; default
          value is FALSE

 lattice: logical

n.hexbins: number of xbins for hexagon binning; default is 100

hexbin.style: the style of hexbin plot; default is "colorscale" 

image.col: vector of color or color type for the image plot with the
          rectangular grid; default=heat.colors(10)

  numlev: number of levels for the contour plot superimposed on the
          image plot using a rectangular grid; default value=5

    xaxt: if "s", then the x-axis is plotted, if "n" then there is no
          x-axis plotted

    yaxt: if "s", then the y-axis is plotted, if "n" then there is no
          y-axis plotted

     ...: if hexbin.plotted=TRUE, the other options/arguments under
          'plot.hexbin' (library(hexbin)) can be used; if
          hexbin.plotted=FALSE, then other options under 'contour'
          (library(base)) can be used

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

     This function calls make.grid or make.density for the values in
     the rectangular grid which make up the image plot.  This procedure
     produces rectangular cells for the resulting grid, but if there is
     a library(hexbin) and the user wants hexagon cells in the image
     grid, hexbin cells are produced in the grid.  A superimposed
     contour plot is available for the rectangular-celled image grid,
     but not available for the hexbin image grid.  

     Other image colors (image.col) may be used.  See documentation for
     'heat.colors'.

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

     Image plot with a superimposed contour plot along with a legend
     roughly describing the values associated with the color scheme. 
     The white-colored grid cells correspond to those with no
     observations.

_W_a_r_n_i_n_g:

     The number of image colors used may vary from one plot to another,
     and users should be warned that a different number of colors, ie,
     heat.colors(2) (as default) may be used if there are few
     variations/clusters in the data.

     The user should use more colors, ie, heat.colors(10) or
     heat.colors(5), etc. to account for more variation in the data, if
     there is a lot of variation that is apparent. An error message to
     use gray or psuedo.cube colors will prompt the user in such cases
     that will need a change (usually a decrease) in the number of
     image colors.

     Gating (both interactive and non-interactive currently works only
     with the bivariate image plot using a rectangular and not
     hexagonal grid (ie, with the option hexbin.plotted=FALSE).

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

     A. J. Rossini, J. Y. Wan

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

     'make.grid', 'legend.CSP', 'image', 'contour', 'heat.colors',
     'hexbin', 'plot.hexbin',

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

     ##Example I: with a  FSC object
       if (require(rfcdmin)){
         data.there<-is.element("MC.053",objects())
         if ((sum(data.there) != length(data.there))) {
           ## obtaining the FCS objects from FHCRC data
           data(MC.053min)
         }
         ## obtain the two column variables
         xvar<-MC.053@data[,1]
         yvar<-MC.053@data[,2]

         ## have an example plot
         if (interactive()==TRUE) {

           ## rectangular cells with the contour plot 
           ContourScatterPlot(xvar, yvar,
                             xlab=colnames(MC.053@data)[1],
                             ylab=colnames(MC.053@data)[2],
                             main="Individual 042402c1.053",
                             hexbin.plotted=FALSE,
                             numlev=25, image.col=heat.colors(15),
                             plot.legend.CSP=TRUE)

           ## hexagon cells without contour lines; default n.hexbins=100
           ContourScatterPlot(xvar, yvar,
                             xlab=colnames(MC.053@data)[1],
                             ylab=colnames(MC.053@data)[2],
                             main="Individual 042402c1.053",
                            hexbin.plotted=TRUE)
           ## finer hexgonal binning
             ContourScatterPlot(xvar, yvar,
                             xlab=colnames(MC.053@data)[1],
                             ylab=colnames(MC.053@data)[2],
                             main="Individual 042402c1.053",
                             hexbin.plotted=TRUE, n.hexbins=300)

     ## and with some additional
           ## plot.hexbin options
           ContourScatterPlot(xvar, yvar,
                              xlab=colnames(MC.053@data)[1],
                              ylab=colnames(MC.053@data)[2],
                              main="Individual 042402c1.053", hexbin.plotted=TRUE,
                              minarea=1, maxarea=1)

           ## different hexbin styles

           ContourScatterPlot(xvar, yvar,
                              xlab=colnames(MC.053@data)[1],
                              ylab=colnames(MC.053@data)[2],
                              main="Hexbin.style=colorscale", hexbin.plotted=TRUE,
                              hexbin.style="colorscale")
           ContourScatterPlot(xvar, yvar,
                              xlab=colnames(MC.053@data)[1],
                              ylab=colnames(MC.053@data)[2],
                              main="Hexbin.style=lattice", hexbin.plotted=TRUE,
                              hexbin.style="lattice")
           ContourScatterPlot(xvar, yvar,
                              xlab=colnames(MC.053@data)[1],
                              ylab=colnames(MC.053@data)[2],
                              main="Hexbin.style=centroids", hexbin.plotted=TRUE,
                              hexbin.style="centroids")

           ContourScatterPlot(xvar, yvar,
                              xlab=colnames(MC.053@data)[1],
                              ylab=colnames(MC.053@data)[2],
                              main="Hexbin.style=nested.lattice", hexbin.plotted=TRUE,
                              hexbin.style="nested.lattice")
           ContourScatterPlot(xvar, yvar,
                              xlab=colnames(MC.053@data)[1],
                              ylab=colnames(MC.053@data)[2],
                              main="Hexbin.style=nested.centroids", hexbin.plotted=TRUE,
                              hexbin.style="nested.centroids")
           }
     ## See example(make.density) for examples of 'image' of
     ## grid images with values estimated from 'status'; ie plots of
     ## differences between stimulated and unstimulated
     ## HIV-protein 'status' scenarios

     if ( ( sum(data.there) != length(data.there) )){
           ## obtaining the FCS objects from VRC data
           data(VRCmin)
       }

     var1<-st.DRT@data[,4]
     var2<-st.DRT@data[,5]
     var1.2<-unst.DRT@data[,4]
     var2.2<-unst.DRT@data[,5]

     col.nm<-colnames(st.DRT@data)

     ## The status where 1=stimulated
     ## 0 = unstimulated
     status<-c(rep(1, dim(st.DRT@data)[1]), rep(0, dim(unst.DRT@data)[1]))
     x <- c(var1, var1.2)
     y <-c(var2, var2.2)

     if (interactive()){
     par(mfrow=c(3,4))
     ContourScatterPlot(var1, var2, 
       main="make.grid: Counts for stimulated",
        xlab=col.nm[4],
        ylab=col.nm[5], image.col=heat.colors(20),plot.legend.CSP=TRUE)

     ContourScatterPlot(x, y,
       main="make.grid: Counts for unstimulated",
        xlab=col.nm[4],
        ylab=col.nm[5], image.col=heat.colors(20),plot.legend.CSP=TRUE)

     ## white cells are those with NO data
     ContourScatterPlot(x, y,  status=status,
       type.CSP="count.diff",
       main="Count difference between Stimulated and unstimulated",
        xlab=col.nm[4],
        ylab=col.nm[5], image.col=c("brown","lightyellow"))

     ContourScatterPlot(x, y,  status=status,
       type.CSP="p.hat",
       main="Proportion of Stimulated",
        xlab=col.nm[4],
        ylab=col.nm[5], image.col=c("brown","lightyellow"))

     ContourScatterPlot(x, y,  status=status,
        main="Normalized proportion of Stimulated",
        xlab=col.nm[4],
        ylab=col.nm[5], image.col=c("brown","lightyellow"))

     ContourScatterPlot(x, y,  status=status,
        main="z statistic",
        xlab=col.nm[4],
        ylab=col.nm[5], image.col=c("brown","lightyellow"))
     }

     }

     ##Example II: with a  CytoFrame object
      if (require(rfcdmin)) {

      ##obtaining the location of the fcs files in the data
       pathFiles<-system.file("bccrc", package="rfcdmin")
       drugFiles<-dir(pathFiles)

      ## reading in the FCS files
       drugData<-read.series.FCS(drugFiles,path=pathFiles,MY.DEBUG=FALSE)
       xvar <- fluors(drugData[[1]])[,1]
       yvar <- fluors(drugData[[1]])[,2]
       if (interactive()==TRUE) {
         ContourScatterPlot(xvar, yvar,
                              xlab=colnames(exprs(drugData[[1]]))[1],
                              ylab=colnames(exprs(drugData[[1]]))[2],
                              main="Contour plot",
                              hexbin.plotted=FALSE,
                              numlev=25, image.col= c("gray82", "blue"),
                              plot.legend.CSP=TRUE)
                              }
     }
      

