\name{pairs.CSP}
\alias{pairs.CSP}
%- Also NEED an `\alias' for EACH other topic documented here.
\title{Contour/Hexbin Scatterplot Matrices}
\description{
  A pairs plotting of histograms and rectangular-binned or
  hexagonal-binned image plots are produced using \code{hist} and
  \code{ContourScatterPlot}, respectively.
}
\usage{
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,
           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)"))
}
%- maybe also `usage' for other objects documented here.
\arguments{
  \item{x}{matrix of data in which the columns are the variables and the
    rows are the individual observations}

  \item{status}{ numerical binary 0, 1 vector denoting the status of the
    observations; default is NULL}

  \item{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{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{alternate.hexbinplot}{Boolean; if TRUE then alternate
    hexbin pairs plot is used; otherwise the ContourScatterPlot with
    rectangular bins is implemented}
  
  \item{n.hexbins}{number of bins for hexbin call; default is 100}
  
  \item{range.x}{vector denoting the min and the max of the observation
    values across all variable columns}
  
  \item{varlabpos}{vector of position of the variable values in which to
    label the x and y axes }
  
  \item{cutoffs}{the cutoffs for the x and y axes of the rectangular
    bins when alternate.hexbinplot is FALSE}

  \item{labels}{the labels for the diagonals when
    alternative.hexbinplot is TRUE}
  
  \item{panel}{default panel function; currently this is the
    contour scatter plot with rectangular bins; this option is ignored
    when 'alternate.hexbinplot' is TRUE}
  
  \item{main}{the main title for the rectanglar Contour scatter plot
    when alternative.hexbinplot is FALSE}
  
  \item{image.col}{image colors for the rectangular bins when
    alternative.hexbinplot is FALSE}
  
  \item{numlev}{number of levels for the contours for the rectangular
    bins when alternative.hexbinplot is FALSE}
  
  \item{\dots}{other options in \code{hexagons} or \code{ContourScatterPlot}}
  
  \item{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{upper.panel}{function for the upper panels of the pairs plot;
    currently this is fixed as a hexbin or contour scatter plot  }

  \item{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{border.boxes}{vector of corresponding border colors for each of
    the boxes in 'box.idx.list'}
  \item{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{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{label.pos}{position of the labels on the diagonal panels which are
  currently fixed as histograms; this option is not in use currently.}

  \item{cex.labels}{ cex for the labels, used only when
    'alternative.hexbinplot' is TRUE }
  
  \item{font.labels}{ font for the labels, used only when
    'alternative.hexbinplot' is TRUE }
  
  \item{row1attop}{ boolean if row 1 is at the top, used only when
    'alternative.hexbinplot' is TRUE }
  
  \item{gap}{ used only when 'alternative.hexbinplot' is TRUE  }

  \item{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)"}
   

}
\details{
  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.
}
\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.
}
\references{Hexbin, other papers.}
\author{J.Y. Wan and A.J. Rossini}

\seealso{objects to See Also as 'hexbin' in the \pkg{hexbin} package}

\examples{
  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)
    }
  }
}
\keyword{hplot}