\name{createGate}
\alias{createGate}
\alias{icreateGate}


\title{Gating of a FCS object: Making a Gating/Selection index
  column for subsequent extraction}
\description{
  
  After the gating procedure, which can be implemented either
  non-interactively by \code{\link{createGate}} or interactively
  by \code{\link{icreateGate}}, a \code{\link{FCSgate}} class object is returned with a
  column variable of indices in
  which 1 denotes inclusion and 0 denotes inclusion or exclusion, respectively, from the
  gating ranges or thresholds added as a column to the "gate"
  matrix, and information: \$PnR (gating range),
  \$PnS (longname of the gating index), \$PnN (shortname of the gating
  index) will be added in the "history" string. The message "NONE" is
  added or updated in the corresponding "extractGatedData.msg" slot.
  The "current.data.obs" vector is not changed.
  The interactive gating here will provide contour-image plots and
  allow the user to input the gatingrange after viewing these plots.

}
\usage{
createGate(x, varpos = NULL, gatingrange = NULL, type = c("uniscut",
"bidcut", "biscut", "bipcut"),
biscut.quadrant = c("+/+", "-/-", "-/+", "+/-"),
prev.gateNum = NULL, prev.IndexValue.In = NULL,
comment = "", MY.DEBUG = FALSE)

icreateGate(x, varpos = NULL, gatingrange = NULL, type = NULL,
biscut.quadrant = NULL, prev.gateNum = NULL,
prev.IndexValue.In = NULL,
comment = NULL,
pchtype=".",
MY.DEBUG = TRUE,
prompt.all.options=TRUE)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
  \item{x}{ a \code{FCS} object}
  \item{varpos}{one numeric position or vector of two positions of
    the column variable(s) to gate upon (note: x is the horizontal axis/variable
    and y is the vertical axis/variable) }
  \item{gatingrange}{gating threshold range in one of the following
    formats for each type of gating:
   \describe{
    \item{"uniscut"}{univariate single cut; gatingrange$=$x1 (will
      select/include all  points $>=$ x1), x1 is numeric value}
    \item{"bidcut"}{bivariate double cut: 
      gatingrange$=$c(x1,x2, y1,y2), a numeric vector of lowerbound,
      upperbound cutoffs for x and y variables}
    \item{"biscut"}{bivariate single cut:gatingrange$=$c(x1,y1),
      a numeric vector of the cutoffs for x and y variables }
    \item{"bipcut"}{bivariate polygonal cut: polygonal thresholds
      for an n$-$sided polygon has:
      (gatingrange$=$c(c(x1, x2, ...,xn, x1), c(y1, y2, ...,yn, y1)),
      a vector of vectors which denote the outer points of the polygonal
      vertices)}
   }
  }
  \item{type}{character string of the type of cut/gating:
   \describe{
    \item{"uniscut"}{univariate single cut: selects datapoints that are
      greater than or equal to the cutoff value denoted in gatingrange}
    \item{"bidcut"}{bivariate double cut: selects datapoints in
      the central rectangle formed by two vertical lines
      (x variable cutoffs) and two horizontal lines (y variable cutoffs)}
    \item{"biscut"}{bivariate single cut: cuts graph into quadrants
      (selects datapoints in the quadrant denoted by biscut.quadrant)}
    \item{"bipcut"}{bivariate polygonal cut: selects the datapoints in a
      polygon}
   }
  }
  \item{biscut.quadrant}{character string value denoting the (x,y)
    quadrant that is to be selected; Values are one of the following:
    \describe{
    \item{"$+$/$+$"}{selects the upper right quadrant, where x is positive
      and y is positive}
    \item{"$-$/$+$"}{selects the upper left quadrant, where x is negative
      and y is positive}
    \item{"$+$/$-$"}{selects the lower right quadrant, where x is positive
      and y is negative}
    \item{"$-$/$-$"}{selects the lower left quadrant, where x is negative
      and y is negative}
    }
  }
  \item{prev.gateNum}{numeric column number of the previous subset/gate
    index in the "gate" matrix of x that
    should be carried over to this gate. \emph{NOTE: The datapoints not
      selected in the index specified by prev.colNum will not be
      selected in this gate either}}
  \item{prev.IndexValue.In}{the value of inclusion for the gating index
    specified by "prev.gateNum"}
  
  \item{comment}{character string denoting the importance of the gating;
    default is the empty string}
  \item{pchtype}{The type of point to plot observations that have been
    selected using \link{showgate.FCS}; default is using "."}
  \item{MY.DEBUG}{If TRUE, prints out debugging statements; otherwise if
    FALSE, the debugging statements are surpressed; default is TRUE}
  \item{prompt.all.options}{boolean; if TRUE all other options about the
    display of plots are prompted for user input in the interactive
    gating; otherwise, if FALSE, these prompts are surpressed; default
    is TRUE}
}
\details{
  If any options in the signature for \code{\link{icreateGate}} are not specified,
  then these options are prompted for the user to input values.

  Use \code{\link{extractGateHistory}} to obtain information about the
  particular gating/selection index from the "history" string.
  
  Usually the function \code{\link{extractGatedData}} is used to row reduce
  the data of the FCS object.
  
  For an example of a sequential interactive gating scheme
  please use \code{\link{FHCRC.HVTNFCS}}
  for the FCS objects in data(FHCRC) of the 'rfcdorig' package and use
  \code{\link{VRC.HVTNFCS}} for the FCS objects in
  data(VRC) of the  'rfcdorig' library.

  For basic, non-interactive gating, use \code{\link{createGate}}, and
  for basic, non-interactive subsetting or data extraction after gating use
  \code{\link{extractGatedData}}.  For basic, non-interactive plotting, use
  \code{\link{plotvar.FCS}} to plot column variables in
  an FCS object and \code{\link{showgate.FCS}} to graph the gate and
  color-in the selected datapoints.

  When all gating parameters are input in \code{\link{icreateGate}},
  and "prompt.all.options" is set to FALSE, then a gating index is
  created and appended to the 'gate' matrix and the corresponding plot
  is shown with the gate without any user input prompts.  See 'examples'
  for details.
 
}
\value{
  A \code{\link{FCSgate}} S4 object is returned that extends the
  \code{\link{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{\link{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{extractGatedData}}, 'FHCRC' data in the 'rfcdorig' package,
  \code{\link{FHCRC.HVTNFCS}}, 'VRC' data in the 'rfcdorig' package,
  \code{\link{VRC.HVTNFCS}},\code{\link{extractGateHistory}}
}
\examples{

## example of interactive gating

    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)
      }
  
      if (interactive()==TRUE) {
        ## icreateGate: The following will prompt the user for
        ## plotting and gating information.

        ## put two plots on one row 
        par(mfrow=c(2,2))

        ## uniscut: univariate single cut
        MC.053.iuniscut<-icreateGate(MC.053, varpos=2,
               gatingrange=250, type="uniscut")
        ## IndexValue.In = 1

        ## bidcut: bivariate double cut
        MC.053.ibidcut<-icreateGate(MC.053.iuniscut,
            prev.gateNum=1,prev.IndexValue.In=1, type="bidcut")
  
        ## biscut: bivariate single cut
        MC.053.ibiscut<-icreateGate(MC.053.ibidcut, type="biscut")
        ## prev.gateNum=2
         
  
        ## bipcut: bivariate polygonal cut
        MC.053.ibipcut<-icreateGate(MC.053.ibiscut, type="bipcut")
        ## prev.gateNum=3

        ## user-chosen gate
        MC.053.iuser<-icreateGate(MC.053)
      
    }
  
      ## example of creating a gate when parameters are known

      ## uniscut: univariate single cut

      MC.053.gated<-createGate(MC.053, varpos=2, type="uniscut",
                             gatingrange=300, comment="Example")

      if (interactive()){
      ## corresponding icreateGate with a plot and no prompts
      MC.053.igated<-icreateGate(MC.053, varpos=2, type="uniscut",
                             gatingrange=300, comment="plot and gate shown",
                             prompt.all.options=FALSE)
      }
      ## bidcut: bivariate double cut

      MC.053.gated1<-createGate(MC.053, varpos=c(1,2), type="bidcut", 
                              gatingrange=c(250, 500, 0,250),
                              comment="Example")
      if (interactive()){
      ## corresponding icreateGate with a plot and no prompts
      MC.053.igated1<-icreateGate(MC.053, varpos=c(1,2), type="bidcut",
                             gatingrange=c(250, 500, 0,250),
                             comment="plot and gate shown",
                             prompt.all.options=FALSE)
      }
      ## biscut: bivariate single cut

      MC.053.gated<-createGate(MC.053, varpos=c(3,4), type="biscut", 
                             gatingrange=c(250, 500),
                             biscut.quadrant="+/-", comment="Example")

      if (interactive()){
      ## corresponding icreateGate with a plot and no prompts
      MC.053.igated<-icreateGate(MC.053, varpos=c(1,2), type="biscut",
                             gatingrange=c(250, 500),
                             biscut.quadrant="+/-",
                             comment="plot and gate shown",
                             prompt.all.options=FALSE)
      }
      ## bipcut: bivariate polygonal cut

      x.coord<-c(200, 200, 600, 600, 200)
      y.coord<-c(200, 600, 600, 200, 200)
      MC.053.gated2<-createGate(MC.053, varpos=1:2, type="bipcut", 
                              gatingrange=cbind(x.coord, y.coord),
                              comment="Example")
      if (interactive()){
      ## corresponding icreateGate with a plot and no prompts
      MC.053.igated2<-icreateGate(MC.053, varpos=c(1,2), type="bipcut",
                             gatingrange=c(x.coord, y.coord),
                             comment="plot and gate shown",
                             prompt.all.options=FALSE)
      }
    }
}
  


\keyword{iplot}
\keyword{manip}
\keyword{data}