\name{extractGateHistory}
\alias{extractGateHistory}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Extracting the gating information from the history}
\description{
   The history string corresponding to a specific gating Index specified
  by 'gateNum' is retrieved and output as a list of specific components.
}
\usage{
extractGateHistory(x, gateNum)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
  \item{x}{ a "FCSgate" object created after using \code{\link{createGate}}}
  \item{gateNum}{the numeric column position of the gating index in
      the 'gate' matrix }
}

\value{
 \item{gateNum}{the numeric column position of the gating index in
      the 'gate' matrix}
    
    \item{gateName}{character name of the gating index specified in the
      'gate' matrix}
    
    \item{type}{type of gating (ie, "biscut", "uniscut", "bipcut",
      "bidcut")}
    
    \item{biscut.quadrant}{the quadrant specified (ie, ("+/+", "-/-",
      "+/-", "-/+"))}
    
    \item{data.colpos}{the gated parameter column positions in the
      'data' matrix}
    
    \item{data.colnames}{the gated parameter column names in the 'data'
      matrix}
    
    \item{IndexValue.In}{the value of the index that specifies inclusion
      or selection}
    
    \item{gatingrange}{the vector of gating threshold(s)}
    
    \item{prev.gateNum}{the previous or most prior gating index column
      position in the 'gate' matrix}
    
    \item{prev.gateName}{the previous or most prior gating index column
      name in the 'gate' matrix}
    
    \item{comment}{character string of the user-defined comment} 
}
\references{

  Trevor Hastie, Robert Tibshirani, and Jerome Friedman. The
  Elements of Statistical Learning: Data Mining, Inference, and
  Prediction. Springer Series in Statistics : New York, 2001. pp.279-283.

  Jerome H. Friedman and Nicholas I. Fisher. Bump Hunting in
  High-Dimensional Data. Tech Report. October 28, 1998.

  J. Paul Robinson, et al. Current Protocols in Cytometry.  John Wiley
  \& Sons, Inc : 2001.

  Mario Roederer and Richard R. Hardy. Frequency Difference Gating: A
  Multivariate Method for Identifying Subsets that Differe between
  Samples. Cytometry, 45:56-64, 2001.

  Mario Roederer and Adam Treister and Wayne Moore and Leonore
  A. Herzenberg. Probability Binning Comparison: A Metric for
  Quantitating Univariate Distribution Differences. Cytometry, 45:37-46,
  2001.

  Keith A. Baggerly. Probability Binning and Testing Agreement between
  Multivariate Immunofluorescence Histograms: Extending the Chi-Squared
  Test. Cytometry, 45:141-150, 2001.
}

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

\seealso{\code{\link{FCS-class}}, \code{\link{FCSgate-class}},
  \code{\link{createGate}, \code{\link{extractGatedData}}}
}
\examples{
 if (require(rfcdmin)) {
      data.there<-is.element("MC.053",objects())
      if ((sum(data.there) != length(data.there))) {
        ## obtaining the FCS objects from VRC data
        data(MC.053min)
      }
  
####  foo1 : Gating type: uniscut, univariate single cut
foo1 <- createGate(MC.053, varpos=4, gatingrange=256,
                    type="uniscut", MY.DEBUG=TRUE)


#### foo2.3 : Gating type : biscut -/-
foo2.3 <- createGate(foo1, varpos=c(1,2),
                      gatingrange=c(256, 300),
                      type="biscut",
                      biscut.quadrant="-/-",
                      prev.gateNum=NULL,
                      MY.DEBUG=TRUE)

## obtain gate information for first uniscut gate
gate.info1<-extractGateHistory(foo1, gateNum=1)

## obtain gate information for the second biscut gate
gate.info2<-extractGateHistory(foo2.3, gateNum=2)

### foo2.3.1 : extraction
foo2.3.1 <- extractGatedData(foo2.3, gateNum=2,
                              IndexValue.In=1,
                              MY.DEBUG=TRUE)
## obtain the second biscut gate information after
## subset/extraction of row observations
gate.info2.1<-extractGateHistory(foo2.3.1, gateNum=2)
}
}
\keyword{data}
\keyword{manip}