\HeaderA{gate.IPC}{Interactive gating of an Image Parallel Coordinates Plot}{gate.IPC}
\keyword{hplot}{gate.IPC}
\begin{Description}\relax
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.
\end{Description}
\begin{Usage}
\begin{verbatim}
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,...)

\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{myFCSobj}] FCS object to be gated/subsetted on an image parallel
coordinates plot
\item[\code{var.gate}] numerical column position of the variable to be gated
in the data component of myFSobj
\item[\code{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[\code{num.bins}] a vector consisting of the row positions of the cells
to be analyze; default is 10
\item[\code{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[\code{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[\code{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[\code{title}] character string denoting the title of the image plot;
default value is an empty string 
\item[\code{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[\code{color.image}] the color scheme for the image plot; default is
gray((25:5/25)[-c(1,2,3, 4, 5, 6)]) 
\item[\code{xwidth.scale}] numeric value denoting the horizontal width of the variable
and the transitions blocks; default value is 5 units of width
\item[\code{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[\code{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[\code{image.plotted}] Boolean; if TRUE, then the image parallel
coordinates plot is displayed; otherwise if FALSE, the plot is
surpressed; default is TRUE
\item[\code{para.plotted}] Boolean; if TRUE, then the parallel
coordinates plot is displayed; otherwise if FALSE, the plot is
surpressed; default is TRUE
\item[\code{lines.plotted}] Boolean; if TRUE, then the image plot with the
superimposed lines displayed; otherwise if FALSE, the plot is
surpressed
\item[\code{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[\code{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[\code{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[\code{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[\code{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[\code{shrink.legend}] boolean; if TRUE then the legend will be ;
default value is TRUE
\item[\code{horizontal.legend}] default value is TRUE
\item[\code{offset.legend}] default value is 0.03
\item[\code{nlevel.legend}] default value is the length of the color.image vector
\item[\code{xlab.image}] a character string denoting the label of the
horizontal x-axis on the image plot; default value is an empty string
\item[\code{ylab.image}] a character string denoting the label of the
vertical y-axis on the image plot; default value is "Bins"
\item[\code{MY.DEBUG}] boolean value; if TRUE, debugging statements are
printed, otherwise if FALSE, the statements are surpressed; default
is FALSE
\item[\code{...}] graphical parameters for \code{\LinkA{plot}{plot}} may also be
passed as arguments to this function
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
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.
\end{Details}
\begin{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.

\begin{ldescription}
\item[\code{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 variablesDescription of `comp1'
\item[\code{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 variablesDescription of `comp2'
\item[\code{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 variablesDescription of `comp1'
\item[\code{obspos.sub1}] first subset's vector of numerical row observation
positions of the data component of myFCSobj
\item[\code{obspos.sub2}] second subset's vector of numerical row observation
positions of the data component of myFCSobj
\item[\code{FCSgateobj}] An FCS gate object that resulted from the gating
\end{ldescription}
\end{Value}
\begin{Author}\relax
A.J. Rossini \& J.Y. Wan
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{ImageParCoord}{ImageParCoord}},
\code{\LinkA{JointImageParCoord}{JointImageParCoord}},
\code{\LinkA{hist}{hist}},
\code{\LinkA{plot}{plot}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}

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

\end{ExampleCode}
\end{Examples}

