\name{ContourScatterPlot}
\alias{ContourScatterPlot}
\title{ Image and Contour Bivariate Plot }
\description{
  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.
}
\usage{
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),
                   ...)
}
\arguments{
  \item{xvar}{ numerical vector of the x-variable }
  \item{yvar}{ numerical vector of the y-variable }
   \item{status}{ numerical binary 0, 1 vector denoting the status of the
     observations; default is NULL}
   \item{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
    \link{make.density} for details.}
  \item{xlab}{ character string of the x-variable name }
  \item{ylab}{ character string of the y-variable name }
  \item{main}{ character string of title of the plot}
  \item{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{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{hexbin.plotted}{boolean; if TRUE then the grid
    cells/compartments are hexagons; otherwise the grid cells are
    rectangular; default value is FALSE}
  \item{lattice}{logical}
  \item{n.hexbins}{number of xbins for hexagon binning; default is 100}
  \item{hexbin.style}{the style of hexbin plot; default is "colorscale" }
  \item{image.col}{vector of color or color type for the image plot with the rectangular
    grid; default=heat.colors(10)}
  \item{numlev}{ number of levels for the contour plot superimposed on
    the image plot using a rectangular grid; default value=5}
  \item{xaxt}{if "s", then the x-axis is plotted, if "n" then there is no
    x-axis plotted}
  \item{yaxt}{if "s", then the y-axis is plotted, if "n" then there is no
    y-axis plotted}
  \item{...}{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{\link{contour}}
    (library(base)) can be used}
}
\details{
  This function calls \link{make.grid} or \link{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}.
}
\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.
}
\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).
}
\author{ A. J. Rossini, J. Y. Wan }
\seealso{
  \code{\link{make.grid}},
  \code{\link{legend.CSP}},
  \code{\link{image}},
  \code{\link{contour}},
  \code{\link[grDevices]{heat.colors}},
  \pkg{hexbin},
  'plot.hexbin',
}
\examples{
##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)
			 }
}
 
}
\keyword{hplot}