\name{gate.IPC}
\alias{gate.IPC}
%- Also NEED an `\alias' for EACH other topic documented here.
\title{Interactive gating of an Image Parallel Coordinates Plot }
\description{
  This function will plot an image parallel coordinates plot and allows
  to user to click on the plot to indicate the cutoff value of the variable
  that is to be gated.  On this single variable, the plot will be
  divided and two subsequent subplots (ie, two image parallel
  coordinates plots) will be shown.  
}
\usage{
gate.IPC(myFCSobj, var.gate,
      var.pos=1:(dim(myFCSobj@data)[2]),
      num.bins=10,
      joint=FALSE,
      range.var=range(myFCSobj@data[,var.pos]),
      break10 =seq(range.var[1]-1, range.var[2],
                       by=range.var[2]/num.bins),
      title="",
      use.shortnames=FALSE,
      color.image=gray((25:5/25)[-c(1,2,3, 4, 5, 6)]), 
      xwidth.scale=5,
      ntrans=1,
      hist.plotted=FALSE,
      image.plotted=TRUE,
      para.plotted=FALSE,
      lines.plotted=TRUE,
      legend.plotted=TRUE,
      lwd.vec=1:7,
      lty.vec=rep(1,7),
      col.vec=7:1,
      range.image=c(0, dim(myFCSobj@data)[1]),
      shrink.legend=TRUE,
      horizontal.legend = TRUE,
      offset.legend=0.03,
      nlevel.legend=length(color.image),
      xlab.image="",
      ylab.image="Bins",
      MY.DEBUG=FALSE,...)

}
%- maybe also `usage' for other objects documented here.
\arguments{
  \item{myFCSobj}{FCS object to be gated/subsetted on an image parallel
    coordinates plot}
  \item{var.gate}{numerical column position of the variable to be gated
    in the data component of myFSobj}
  \item{var.pos}{a vector of the column positions of the variables of
    interest in the data of the FCS object to be shown in the image
    parallel coordinates plot;default is all the columns
    will be shown in the plots }
 
  \item{num.bins}{a vector consisting of the row positions of the cells
  to be analyze; default is 10}
  \item{joint}{Boolean; If TRUE, then the joint image parallel
    coordinate plots will be shown for the pre-gated and post-gated
    data; if FALSE, then the mariginal lines for the image parallel
    coordinate plots will be displayed; default is FALSE}
  \item{range.var}{a 2-dimensional vector denoting the minimum value and
    the maximum value of the variables to be plotted; default is
    c(0,1024), where 0 is the minimum value and 1024 is the max value}
  \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{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{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 the image plot with the
     superimposed lines displayed; otherwise if FALSE, the plot is
     surpressed}

    \item{legend.plotted}{Boolean; if TRUE, then the legend for the
      superimposed lines denoting particular counts will be diplayed;
      otherwise if FALSE, the legend display is
      surpressed}
   
  \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{shrink.legend}{boolean; if TRUE then the legend will be ;
    default value is TRUE}
  
  \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}{boolean value; if TRUE, debugging statements are
    printed, otherwise if FALSE, the statements are surpressed; default
    is FALSE}
  \item{...}{graphical parameters for \code{\link{plot}} may also be
    passed as arguments to this function}
}
\details{
  The gating will be made on the image parallel coordinates plot without
  the lines drawn; this plot is the last plot to be displayed.  The user
  should make a right click on the variable value displayed on the
  vertical axis.  This variable value will denote the cutoff.  The
  subsequent plots of the subsets will be made
  on the data such that the first subset will include row observations
  whose gated variable values are less
  than or equal to the cutoff of the gated variable across all other
  variables of interest and that the second subset/subplot will include
  row observations of whose gated variable's values are strictly greater than the
  cutoff.
}
\value{
  The first series of histograms, and parallel
  coordinates plots, and image parallel coordinates plots with
  superimposed lines and legends are displayed optionally by the user.
  
  The second single image parallel coordinates plot is the one, in which the
  gating or threshold in which to subset is obtained by right clicking on the plot.

  \item{info.total }{ 
    \item{image.block}{a matrix denoting the number of observations in
      each cell of the total image plot}
    \item{line.info}{total plot's 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}{total plot's vector of breaks for binning on the vertical axis for the
      values of the variables}Description of `comp1'}
  \item{info.sub1}{ 
    \item{image.block}{a matrix denoting the number of observations in
      each cell of the first subsetted image plot}
    \item{line.info}{first subset's 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}{first subset's vector of breaks for binning on the vertical axis for the
      values of the variables}Description of `comp2'}
  \item{info.sub2}{ 
    \item{image.block}{a matrix denoting the number of observations in
      each cell of the second subsetted image plot}
    \item{line.info}{second subset's 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}{second subset's vector of breaks for binning on the vertical axis for the
      values of the variables}Description of `comp1'}
  \item{obspos.sub1}{first subset's vector of numerical row observation
    positions of the data component of myFCSobj}
  
  \item{obspos.sub2}{second subset's vector of numerical row observation
    positions of the data component of myFCSobj}
  \item{FCSgateobj}{An FCS gate object that resulted from the gating}

}

\author{A.J. Rossini & J.Y. Wan}

 \seealso{
   \code{\link{ImageParCoord}},
   \code{\link{JointImageParCoord}},
   \code{\link{hist}},
   \code{\link{plot}}

 }

 \examples{

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)
}

## make a smaller data for example
## first 1000 row observations
example.fcs<-unst.DRT[1:1000,]
if (!checkvars(example.fcs)){
example.fcs<-fixvars(example.fcs)
}

if (interactive()==TRUE){

## Joint parallel coordinates image
par(mfrow=c(4,3))
## gating the first column variable
## showing the image parallel coordinates
##    for column variables 1 through 5
gate.IPC(example.fcs, 1, var.pos=1:5, num.bins=10,joint=TRUE,
              title="Joint 10 bins 5 trans", ntrans=5)


## marginal parallel coordinate image
## gating the second column variable
par(mfrow=c(4,3))
gate.IPC(example.fcs, 2, var.pos=1:5, num.bins=10,joint=FALSE,
              title="Marginal 10 bins 5 trans", ntrans=5)
}
}

}
\keyword{hplot}% at least one, from doc/KEYWORDS