\HeaderA{pairs.CSP}{Contour/Hexbin Scatterplot Matrices}{pairs.CSP}
\keyword{hplot}{pairs.CSP}
\begin{Description}\relax
A pairs plotting of histograms and rectangular-binned or
hexagonal-binned image plots are produced using \code{hist} and
\code{ContourScatterPlot}, respectively.
\end{Description}
\begin{Usage}
\begin{verbatim}
pairs.CSP(x,
          status=NULL,
          box.idx.list=NULL,
          type.CSP=c("count.diff",
                  "p.hat",
                  "p.hat.norm",
                  "z.stat"),
          alternate.hexbinplot=FALSE,
          n.hexbins=100,
          range.x=range(x),
          varlabpos=round(seq(range.x[1],
                ceiling(diff(range.x)/150)*150+range.x[1],
                by=150),0),
          cutoffs = seq(range.x[1],
                  ceiling(diff(range.x)/25)*25+range.x[1],
                  by=25),  

           labels = colnames(x),

           panel = ContourScatterPlot,
           main="",
                    
           image.col=heat.colors(10),
           numlev=5,...,
           lower.panel = legend.CSP,
           upper.panel = panel,
           overlay.panel=rect.box.idx,
           border.boxes=1:length(box.idx.list),
           lwd.boxes=rep(3,length(box.idx.list)),
           lty.boxes=rep(1,length(box.idx.list)),
                      
           label.pos = 0.5 + has.diag/3,
           cex.labels = NULL,
           font.labels = 1,
           row1attop = TRUE,
           gap=1,
           ch.col=c("heat.colors(n)",
                   "rainbow(n, start=.7, end=.1)",
                   "terrain.colors(n)",
                   "topo.colors(n)",
                   "cm.colors(n)"))
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] matrix of data in which the columns are the variables and the
rows are the individual observations
\item[\code{status}] numerical binary 0, 1 vector denoting the status of the
observations; default is NULL
\item[\code{box.idx.list}] a list of vectors indicating the positions of
'x' which form a box to be overlayed on the binned plot in the upper
and lower panels of the hexbin plot and the only the upper panel
of the rectangular-binned plot by default

\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{alternate.hexbinplot}] Boolean; if TRUE then alternate
hexbin pairs plot is used; otherwise the ContourScatterPlot with
rectangular bins is implemented
\item[\code{n.hexbins}] number of bins for hexbin call; default is 100
\item[\code{range.x}] vector denoting the min and the max of the observation
values across all variable columns
\item[\code{varlabpos}] vector of position of the variable values in which to
label the x and y axes 
\item[\code{cutoffs}] the cutoffs for the x and y axes of the rectangular
bins when alternate.hexbinplot is FALSE
\item[\code{labels}] the labels for the diagonals when
alternative.hexbinplot is TRUE
\item[\code{panel}] default panel function; currently this is the
contour scatter plot with rectangular bins; this option is ignored
when 'alternate.hexbinplot' is TRUE
\item[\code{main}] the main title for the rectanglar Contour scatter plot
when alternative.hexbinplot is FALSE
\item[\code{image.col}] image colors for the rectangular bins when
alternative.hexbinplot is FALSE
\item[\code{numlev}] number of levels for the contours for the rectangular
bins when alternative.hexbinplot is FALSE
\item[\code{...}] other options in \code{hexagons} or \code{ContourScatterPlot}
\item[\code{lower.panel}] function for the lower panels of the pairs plot;
currently this is fixed as a hexbin (when
'alternate.hexbinplot' is TRUE) or the legend.CSP (when
'alternative.hexbinplot' is FALSE) 
\item[\code{upper.panel}] function for the upper panels of the pairs plot;
currently this is fixed as a hexbin or contour scatter plot  
\item[\code{overlay.panel}] Function which describes the overlay image on the
panels; currently this option only works with the 'rect.box.idx' function
and other functions that have the same signature
\item[\code{border.boxes}] vector of corresponding border colors for each of
the boxes in 'box.idx.list'
\item[\code{lwd.boxes}] vector of corresponding widths for each of the
outlined boxes in 'box.idx.list'; default is for all the boxes to
have lwd = 3
\item[\code{lty.boxes}] vector of corresponding line types for each of the
outlined boxes in 'box.idx.list'; default is for all the boxes to
have lty = 1
\item[\code{label.pos}] position of the labels on the diagonal panels which are
currently fixed as histograms; this option is not in use currently.
\item[\code{cex.labels}] cex for the labels, used only when
'alternative.hexbinplot' is TRUE 
\item[\code{font.labels}] font for the labels, used only when
'alternative.hexbinplot' is TRUE 
\item[\code{row1attop}] boolean if row 1 is at the top, used only when
'alternative.hexbinplot' is TRUE 
\item[\code{gap}] used only when 'alternative.hexbinplot' is TRUE  
\item[\code{ch.col}] character string denoting the type of color palette used
for the rectangular-binned image to be displayed in the legend when
'aternate.hexbinplot' is FALSE; default is "heat.colors(n)"
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
There are no legends for the hexagonal (when 'alternate.hexbinplot' is
TRUE) but there is a roughly estimate legend available for the
rectangular binning (when 'alternate.hexbinplot' is FALSE) in the pairs plot.
\end{Details}
\begin{Value}
A pairs plot is displayed.  NOTE: The histograms on the diagonals are of the
whole dataset regardless of the value of the cells in each ContourScatterPlot.
\end{Value}
\begin{Author}\relax
J.Y. Wan and A.J. Rossini
\end{Author}
\begin{References}\relax
Hexbin, other papers.
\end{References}
\begin{SeeAlso}\relax
objects to See Also as 'hexbin' in the \pkg{hexbin} package
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
  if (interactive()){
    if (require(rfcdmin)){
      data.there<-is.element(c("st.1829", "unst.1829", "st.DRT",
                    "unst.DRT"),objects())

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

      ## subsetting the data for quicker plot display of less data
      data.mat1<-st.DRT@data[1:10000, 1:5]

      ## hexagonal binning

      pairs.CSP(data.mat1, alternate.hexbinplot=TRUE)

      ## rectangular binning with legends 

      pairs.CSP(data.mat1, numlev=3,
         image.col=heat.colors(20))

      ## rectangular binning without legends 

      pairs.CSP(data.mat1, numlev=3,
         image.col=heat.colors(20),
         lower.panel=ContourScatterPlot)

      ## putting a box around the observations
      ## greater than 500 for the second variable
      ##  less than 200 for the first variable
      idx1<-which(data.mat1[,2] > 500)  ## green box
      idx2<-which(data.mat1[,1] < 200)  ## blue box

      box.idx.list<-list(idx1, idx2)
      ## hexbin plots
      pairs.CSP(data.mat1, box.idx.list=box.idx.list,
            alternate.hexbinplot=TRUE, border.vec=c("green", "blue"))
      ## rectangular binned plots
      pairs.CSP(data.mat1, box.idx.list=box.idx.list,
            alternate.hexbinplot=FALSE,border.vec=c("green", "blue"),
            lower.panel=ContourScatterPlot)
    }
  }
\end{ExampleCode}
\end{Examples}

