\HeaderA{ContourScatterPlot}{Image and Contour Bivariate Plot}{ContourScatterPlot}
\keyword{hplot}{ContourScatterPlot}
\begin{Description}\relax
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.
\end{Description}
\begin{Usage}
\begin{verbatim}
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),
                   hexbin.plotted=FALSE,
                   hexbin.style=c("colorscale", "lattice", "centroids",
                             "nested.lattice", "nested.centroids"),
                   n.hexbins=100,
                   image.col =  c("gray82", "blue"),
                   numlev = 5,xaxt="s", yaxt="s",
                    ch.col=c("heat.colors(n)",
                                  "rainbow(n, start=.7, end=.1)",
                                  "terrain.colors(n)",
                                  "topo.colors(n)",
                                  "cm.colors(n)"),
                     plot.legend.CSP=FALSE,
                    ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{xvar}] numerical vector of the x-variable 
\item[\code{yvar}] numerical vector of the y-variable 
\item[\code{status}] numerical binary 0, 1 vector denoting the status of the
observations; default is NULL
\item[\code{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
\LinkA{make.density}{make.density} for details.
\item[\code{xlab}] character string of the x-variable name 
\item[\code{ylab}] character string of the y-variable name 
\item[\code{main}] character string of title of the plot
\item[\code{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.
\item[\code{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.
\item[\code{hexbin.plotted}] boolean; if TRUE then the grid
cells/compartments are hexagons; otherwise the grid cells are
rectangular; default value is FALSE
\item[\code{n.hexbins}] number of xbins for hexagon binning; default is 100
\item[\code{hexbin.style}] the style of hexbin plot; default is "colorscale" 
\item[\code{image.col}] color type for the image plot with the rectangular
grid; default=heat.colors(2)
\item[\code{numlev}] number of levels for the contour plot superimposed on
the image plot using a rectangular grid; default value=5
\item[\code{xaxt}] if "s", then the x-axis is plotted, if "n" then there is no
x-axis plotted
\item[\code{yaxt}] if "s", then the y-axis is plotted, if "n" then there is no
y-axis plotted
\item[\code{ch.col}] character string denoting the type of color palette used for the
image to be displayed in the legend; default is "heat.colors(n)"
\item[\code{plot.legend.CSP}] boolean; if TRUE, a legend will be made in a
separate plot; default is FALSE
\item[\code{...}] if hexbin.plotted=TRUE, the other options/arguments under
\code{plot.hexbin} (library(hexbin)) can be used; if
hexbin.plotted=FALSE, then other options under \code{\LinkA{contour}{contour}}
(library(base)) can be used
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
This function calls \LinkA{make.grid}{make.grid} or \LinkA{make.density}{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
\code{heat.colors}.
\end{Details}
\begin{Value}
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.
\end{Value}
\begin{Section}{Warning}
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).
\end{Section}
\begin{Author}\relax
A. J. Rossini, J. Y. Wan
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{make.grid}{make.grid}},
\code{\LinkA{legend.CSP}{legend.CSP}},
\code{\LinkA{image}{image}},
\code{\LinkA{contour}{contour}},
\code{\LinkA{heat.colors}{heat.colors}},
\pkg{hexbin},
'plot.hexbin',
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
##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=heat.colors(20),plot.legend.CSP=TRUE)

ContourScatterPlot(x, y,  status=status,
  type.CSP="p.hat",
  main="Proportion of Stimulated",
   xlab=col.nm[4],
   ylab=col.nm[5], image.col=heat.colors(20),plot.legend.CSP=TRUE)

ContourScatterPlot(x, y,  status=status,
   main="Normalized proportion of Stimulated",
   xlab=col.nm[4],
   ylab=col.nm[5], image.col=heat.colors(20),plot.legend.CSP=TRUE)

ContourScatterPlot(x, y,  status=status,
   main="z statistic",
   xlab=col.nm[4],
   ylab=col.nm[5], image.col=heat.colors(20),plot.legend.CSP=TRUE)
}

}

##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)
                         }
}
 
\end{ExampleCode}
\end{Examples}

