\name{ImageParCoord}
\alias{ImageParCoord}
\alias{JointImageParCoord}
%- Also NEED an `\alias' for EACH other topic documented here.
\title{Image Parallel Coordinates Plot: Joint and marginal}
\description{
  This function constructs an image plot in which a rectangular grid structure
  displays the change of observations from the value of one variable to the
  value of the next variable.  The vertical axis of the image plot
  denotes the value of the variables that are labeled on the horizontal
  axis.  Traditionally, the lines in a parallel coordinates plot
  represent the movement of each observation from one variable to the
  next, but in this case a colored image transition column will
  represent the movement of observations from cell to cell in the image
  grid produced by horizontal bins on the vertical axis and vertical
  divisions between variables and transitions between
  variables labeled on the horizontal axis.  Lines with scaled widths
  overlaying the image plot indicate the movement of observations from
  binned values of one variable to the binned values of another (either
  marginally and only between pairs of variables using
  \code{ImageParCoord} OR jointly across all
  variables using \code{JointImageParCoord}).
  Histograms for each variable and the transitions between the variables
  can be plotted as well.
  
}
\usage{
ImageParCoord(x,
              num.bins=10,
              range.var=range(x),
              break10 = NULL,
              joint=FALSE,
              title="",
              use.shortnames=FALSE,
              color.image=gray((25:5/25)[-c(1,2,3, 4, 5, 6)]),
              xwidth.scale=5,
              ntrans=1,
              legend.plotted=TRUE,
              legend.shrink = 0.9,
              hist.plotted=FALSE,
              image.plotted=TRUE,
              para.plotted=FALSE,
              lines.plotted=TRUE,
              lwd.vec=1:7,
              lty.vec=rep(1,7),
              col.vec=7:1,
              range.image=c(0,dim(x)[1]),
              horizontal.legend = TRUE,
              offset.legend=0.03,
              nlevel.legend=length(color.image),
              xlab.image="",
              ylab.image="Bins",
              MY.DEBUG=TRUE,...)
                       
JointImageParCoord(x,
    num.bins=10,
    range.var=range(x),
    break10=NULL,
    title="",
    use.shortnames=FALSE,
    color.image=gray((25:5/25)[-c(1,2,3, 4, 5,6)]), 
    xwidth.scale=5,
    ntrans=1,
    legend.plotted=TRUE,
    legend.shrink = 0.9,
    hist.plotted=FALSE,
    image.plotted=TRUE,
    para.plotted=FALSE,
    lines.plotted=TRUE,
    lwd.vec=1:7,
    lty.vec=rep(1,7),
    col.vec=7:1,
    range.image=c(0, dim(x)[1]),
    horizontal.legend = TRUE,
    offset.legend=0.03,
    nlevel.legend=length(color.image),
    xlab.image="",
    ylab.image="Bins",
    MY.DEBUG=TRUE,...)

}
\arguments{
  
  \item{x}{data matrix from a FCS object; data has columns as the
    variables and rows as the cells and assume that all column variables
    are of the same unit and range}
  
  \item{num.bins}{numeric value denoting the number of horizontal bins
    on the vertical axis to determine how well-defined/sharp the columns
    of the image plot are; default value is 10 bins}
  
  \item{range.var}{a 2-dimensional vector denoting the minimum value and
    the maximum value of the variables to be plotted; default is
    the range of the FCS object data}

  \item{break10}{vector denoting the breaks for the binning on the
    vertical axis; default is equal interval binning denoted by num.bins
    unless otherwise specified; the breaks
    must include the range of the variable; each bin is denoted by an open
    lower value and a closed upper value, ie, (a,b]
    where a and b are breakpoints and a<b.}
  
  \item{joint}{boolean; if TRUE then the plots will be joined;
    default value is TRUE}

  \item{title}{character string denoting the title of the image plot;
    default value is an empty string}

  \item{use.shortnames}{Boolean; if TRUE, then the shortnames of the
    variables will be used in labeling in the plots; otherwise if FALSE,
    the longnames of the variables will be used; default is FALSE}

  \item{color.image}{the color scheme for the image plot; default is
    gray((25:5/25)[-c(1,2,3, 4, 5, 6)])}

  \item{xwidth.scale}{numeric value denoting the horizontal width of the variable
    and the transitions blocks; default value is 5 units of width}

  \item{ntrans}{numeric value denoting the number of transition columns
    between each pair of variables; default is 1 transition column
    between each pair of variables}
  
   \item{legend.plotted}{Boolean; if TRUE then the legend is produced in
     a separate graph/plot; otherwise if FALSE, then no legend plot is
     made; default is TRUE}
  
   \item{legend.shrink}{numeric to reduce the size of the legend}

   \item{hist.plotted}{Boolean; if TRUE then the histogram plots of the
    variables and the transitions are made; otherwise if FALSE, there is
    no histogram plots; default value is FALSE}
  
  \item{image.plotted}{Boolean; if TRUE, then the image parallel
    coordinates plot is displayed; otherwise if FALSE, the plot is
    surpressed; default is TRUE}
  
  \item{para.plotted}{Boolean; if TRUE, then the parallel
    coordinates plot is displayed; otherwise if FALSE, the plot is
    surpressed; default is TRUE}
  
   \item{lines.plotted}{Boolean; if TRUE, then 
     superimposed binned parallel coordinate lines displayed on
     top of the existing plot; otherwise if FALSE, the plot is
     surpressed; default is TRUE; Note that image.plotted has to be TRUE
     to see the superimposed image and parallelCoordinates lines}

  \item{lwd.vec}{vector denoting the line width sizes to
    be used in the lines overlaying the image parallel coordinates plot;
    default value is an integer vector from 1 to 7}

  \item{lty.vec}{vector denoting the line type (solid or
    dotted, etc) for the corresponding line width in lwd.vec; the
    default is to have a solid line for each line width}

  \item{col.vec}{ vector denoting the color for each line with the
    corresponding line width in lwd.vec and line type in lty.vec; the
    default is to have colors ranging from yellow to black (in that
    order).}
  
  \item{range.image}{2-dimensional numerical vector denoting the range
    of the number of counts in the image block to be plotted.  The
    default value is to have a vector with a mininum value of zero and
    to have a maximum dependent on the number of cells/rows and bins}
  
  \item{horizontal.legend}{default value is TRUE}
  
  \item{offset.legend}{default value is 0.03}

  \item{nlevel.legend}{default value is the length of the color.image vector}

  \item{xlab.image}{a character string denoting the label of the
    horizontal x-axis on the image plot; default value is an empty string}
  
  \item{ylab.image}{a character string denoting the label of the
    vertical y-axis on the image plot; default value is "Bins"}
  
  \item{MY.DEBUG}{a boolean; if TRUE then debugging statements for the
    binning are output, otherwise if FALSE, the statements are
    surpressed; default is TRUE}
  \item{...}{graphical parameters for \code{\link{plot}} may also be
    passed as arguments to this function}
}
\details{
  The result is to have an image block or matrix.  Each variable was
  binned according to the number of bins specified by the option
  num.bins.
  
  A point-slope line formula was used to determine
  the counts in the transition block (a matrix of the same transition
  column across a certain number of rows defined by ntrans and x.width
  options) between two variables.  For each pair of column variables,
  the horizontal positions of the two variables were regressed on the
  bin position of the particular observation in order to obtain a
  point-slope line formula.  Thus, for each row observation, one could
  predict the particular bin that it passed through for the transition
  block between two known bin values of the two variables.

  The following is the point-slope formula for each pair of
  column variables:
  
  \deqn{ bin.predicted = slope*(xpos.trans - xpos.V1) + bin.V1}

  \describe{
  \item{$bin.predicted$}{a row observation's predicted bin value for the specific transition
    column}
  \item{$slope$}{the slope of the line determined by dividing the
    difference between the bin values of variable 1 (V1) and variable 2
    (V2) by the difference between the horizontal, x-axis positions of
    V1 and V2: \eqn{ slope = (bin.V2-bin.V1)/(xpos.V2 - xpos.V1)} }
  \item{$xpos.trans$}{the x-axis, horizontal position of the transition
    column for the particular row observation}
  \item{$xpos.V1$}{the x-axis, horizontal position of V1 for the
    particular row observation}
  \item{$bin.V1$}{a row observation's bin value for V1}
  
  Please note that the lines are only marginal.  They denote the number
  of cells moving only between adjacent pairs of variables.  To view the
  cells jointly across all variables, the function
  \code{JointImageParCoord} should be used.
  
  The line widths in the image parallel coordinates plot were scaled by
  the following equation:

  \deqn{ x = (m-1)*((n-i)(a-i)) + 1}

 \item{$x$}{is the scaled size for a particular line}
 \item{$m$}{is the maximum line width size denoted by max.lwd from the function
  signature}
 \item{$n$}{is the number of observations denoted by the line}
 \item{$i$}{is the minimum number of observations denoted by a line}
 \item{$a$}{is the maximum number of observations denoted by a line}

  }
}
\value{
  
  The image parallel coordinates plot with overlayed lines and a legend for
  the lines, the traditional parallel coordinates plot without the
  image, and histograms of the variables and the
  transitions are displayed upon user request as well as a list of the
  following:
  
  \item{image.block}{a matrix denoting the number of observations in
    each cell of the image plot}
  \item{line.info}{list of matrices in which each matrix corresponds to the
    the line information between a pair of variables.  Each matrix has three
    columns.  The first two columns are the values of unique bin
    patterns between the pair of column variables, and the third column
    is the number of observations with that particular pattern.}
\item{breaks}{vector of breaks for binning on the vertical axis for the
values of the variables}
}

\author{A.J. Rossini and J.Y. Wan}
\note{
Other color images can be used (see the example), but please be advised of the color
scheme.

Probability binning can be incorporated by using the signature option break10 to denote the
breaks from probability binning.


}

\section{WARNING}{On some workstations, some colors may not be able to
  be allocated using \code{rainbow} or \code{heat.colors} as the
  image.color.}

\seealso{
  \code{\link{parallelCoordinates}},
  \code{\link[grDevices:palettes]{rainbow}},
  \code{\link[grDevices:palettes]{heat.colors}},
  \code{\link{ContourScatterPlot}},
  \code{\link{ProbBin.FCS}},
  \code{\link{gate.IPC}}
}


\examples{

  if (require(rfcdmin)){

    data.there<-is.element(c("st.1829", "unst.1829", "unst.DRT", "st.DRT"),objects())
    if ( ( sum(data.there) != length(data.there) )){
      ## obtaining the FCS objects from VRC data
      data(VRCmin)
    }

    if (interactive()==TRUE){
    par(mfrow=c(3,3))

    ImageParCoord(unst.1829@data[1:1000, 1:3], num.bins=16,
              title="1000 obs 16 bins 5 trans", ntrans=5)
    ## joint line plot
    ImageParCoord(unst.1829@data[1:1000,c(1,2,3)], num.bins=16,joint=TRUE,
              title="1000 obs 16 bins 5 trans", ntrans=5,legend.plotted=FALSE)

    ## color image is changed
    ImageParCoord(unst.1829@data[1:1000,c(1,2,3)], num.bins=20,
              title="1000 obs 20 bins 5 trans", color.image=rainbow(16,
              start=.4, end=.1), ntrans=5)

    par(mfrow=c(3,3))
    ImageParCoord(unst.1829@data[1:1000,c(1,2,3)], num.bins=20,
              title="1000 obs 20 bins 10 trans", ntrans=10)
    ## joint line plot

    ImageParCoord(unst.1829@data[1:1000,c(1,2,3)], num.bins=20,joint=TRUE,
              title="1000 obs 20 bins 10 trans", ntrans=10)

    ## plot the parallel coordinates plot also
    par(mfrow=c(2,2))
    ImageParCoord(unst.1829@data[1:1000,c(1,2,3)], 1:1000, num.bins=16,
              color.image=gray((25:5/25)[-c(1, 2, 3, 4, 5, 6,7)]),
              title="1000 obs 16 bins 5 trans", ntrans=5,
              para.plotted=TRUE)

    ## plot the parallel coordinates plot also
    par(mfrow=c(2,2))
    ImageParCoord(unst.1829@data[1:1000,c(1,2,3)],joint=TRUE,
              1:1000, num.bins=16,
              color.image=gray((25:5/25)[-c(1, 2, 3, 4, 5, 6,7)]),
              title="1000 obs 16 bins 5 trans", ntrans=5,
              para.plotted=TRUE)

    ##histograms only
    par(mfrow=c(3,3))
    ImageParCoord(unst.1829@data[1:1000,c(1,2,3)], num.bins=10,
             title="1000 obs 10 bins 1 trans",
             ntrans=1, hist.plotted=TRUE,
             image.plotted=FALSE, legend.plotted=FALSE,
             lines.plotted=FALSE)

    ## histograms and images
    par(mfrow=c(3,3))
    ImageParCoord(unst.1829@data[1:1000,c(1,2,3)],
           num.bins=10,
           title="1000 obs 10 bins 5 trans",
           ntrans=5, hist.plotted=TRUE)

    ## legend only
    ImageParCoord(unst.1829@data[1:1000,c(1,2,3)], num.bins=10,
             title="1000 obs 10 bins 5 trans", ntrans=5, legend.plotted=TRUE,
             image.plotted=FALSE, lines.plotted=FALSE)

   ImageParCoord(unst.1829@data[1:1000,c(1,2,3)],joint=TRUE,
             num.bins=10,
             title="1000 obs 10 bins 5 trans",
             ntrans=5, legend.plotted=TRUE,
             image.plotted=FALSE, lines.plotted=FALSE)
    }
  }

}
\keyword{hplot}