\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:palettes]{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}