\HeaderA{extractGatedData}{Extract the data of a FCS object using a specified Gating Index}{extractGatedData}
\keyword{data}{extractGatedData}
\keyword{manip}{extractGatedData}
\begin{Description}\relax
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}.
\end{Description}
\begin{Usage}
\begin{verbatim}
extractGatedData(x, gateNum = NULL, IndexValue.In = 1, MY.DEBUG = FALSE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] an "FCSgate" object obtained from \code{\LinkA{createGate}{createGate}} 
\item[\code{gateNum}] the column position of the gating index that is specified in the "gate"
matrix 
\item[\code{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[\code{MY.DEBUG}] a boolean value that prints out debugging comments
The default is FALSE and no debugging comments are printed.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
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).
\end{Details}
\begin{Value}
A "FCSgate" S4 object is returned that extends the "FCS" object to contain
additional slots: 
\begin{ldescription}
\item[\code{gate}] a matrix whose columns are the gating indices for the
original data
\item[\code{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[\code{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[\code{current.data.obs}] vector of the original data row positions
that are currently still in the data matrix
\end{ldescription}
\end{Value}
\begin{Author}\relax
A.J. Rossini and J.Y. Wan
\end{Author}
\begin{References}\relax
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.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{FCS-class}{FCS.Rdash.class}}, \code{\LinkA{FCSgate-class}{FCSgate.Rdash.class}},
\code{\LinkA{createGate}{createGate}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
 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)
}
\end{ExampleCode}
\end{Examples}

