\name{extractGatedData}
\alias{extractGatedData}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Extract the data of a FCS object using a specified Gating Index}
\description{
   This function will subset/reduce the rows of the data of an FCS object 
  according to a column index of the "gate" matrix, which is created
  by using the function \code{createGate-methods}.  
}
\usage{
extractGatedData(x, gateNum = NULL, IndexValue.In = 1, MY.DEBUG = FALSE)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
  \item{x}{ an "FCSgate" object obtained from \code{\link{createGate}} }
  \item{gateNum}{the column position of the gating index that is specified in the "gate"
    matrix }
  \item{IndexValue.In}{ either 0 or 1 depending on what value should be set for
    inclusion in the extraction. The default is the value 1. }
  \item{MY.DEBUG}{ a boolean value that prints out debugging comments
    The default is FALSE and no debugging comments are printed.}
}
\details{
  A "FCSgate"
  object with data having a reduced row length will be output along with an update
  to the following slots: "extractGatedData.msg" (The gateNum along with
  the inclusion value will be noted as a string), "current.data.obs"
  (the index of original data row positions that are currently in the
  data will be noted), and
  "metadata" (data dimension information will be updated along with the
  original status being changed to FALSE).
}
\value{
   A "FCSgate" S4 object is returned that extends the "FCS" object to contain
  additional slots: 
  \item{gate}{a matrix whose columns are the gating indices for the
    original data}
  \item{history}{ vector which corresponds to each column
    gating index in "gate" and holds information about what variables and
    type of gate that was implemented and for what ranges of values}
  \item{extractGatedData.msg}{vector of strings to specify what if
    any extraction has been implemented using \code{extractGatedData};
    "NONE" specifies no extraction has been implemented on the data for
    that particular corresponding gating index}
  \item{current.data.obs}{vector of the original data row positions
    that are currently still in the data matrix} 
}
\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}}
}
\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)
      }
  
####  test1 : Gating type: uniscut, univariate single cut
test1 <- createGate(MC.053, varpos=1, gatingrange=256,
                    type="uniscut", MY.DEBUG=TRUE)

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

### test 2.3.1 : extraction
test2.3.1 <- extractGatedData(test2.3, gateNum=2,
                              IndexValue.In=1,
                              MY.DEBUG=TRUE)
}
}
\keyword{data}
\keyword{manip}