\name{showgate.FCS}
\alias{showgate.FCS}
%- Also NEED an `\alias' for EACH other topic documented here.
\title{Showing the gate and the datapoints within the gate on a prevous plot}
\description{
  On an exisiting plot, the gate specified will be plotted and the
  datapoints lying within the gating range will be colored (default is
  the color purple).  
}
\usage{
showgate.FCS(data.mat, gatingrange, Index,
       type = c("uniscut", "biscut", "bidcut", "bipcut"),
       IndexValue.In = 1,
       coltype = 12, pchtype = 8,
       biscut.quadrant = c("+/-","-/-", "+/+", "-/+")) 
}
%- maybe also `usage' for other objects documented here.
\arguments{
   \item{data.mat}{the data to be gated:
    \describe{
    \item{univariate case}{single column of values: a (m X 1) data
      vector where m is the number of cells/rows}
    \item{bivariate case}{matrix of two column variables: a (m X 2) data
      matrix where m is the number or cells/rows}
    }
  }
   \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 with 
      gatingrange = cbind(c(x1, x2, ..., xn, x1),
      c(y1, y2, ..., yn, y1)),
      a vector of vectors which denote the outer points of the polygonal
      vertices}
    }
   } 
  \item{Index}{a vector of 0's and 1's denoting the selection of row
    observations of 'data.mat'}
  \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{IndexValue.In}{The value of 'Index' to be selected; default is 1}
    
  \item{coltype}{a character string or a numerical value describing the
    option for the color of the data point inside the gating range}
  \item{pchtype}{a character string or a numerical value describing the
    option for the point size and type of data point inside the gating range}
   \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}
    }
  }
}


\value{
 The gating range or gate will be displayed and the data points within 
 the gating range will be colored.
}

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

\note{
  The coloring in of data points may take a while to process.  The gate
  selection can only be shown using rectangular binning of the image
  plots using \code{\link{ContourScatterPlot}}.  The
  \code{\link{showgate.FCS}} does not work with hexagonal binning.
}

\seealso{\code{\link{FHCRC.HVTNFCS}},\code{\link{VRC.HVTNFCS}},
  \code{\link{plotvar.FCS}},\code{\link{createGate}},
  \code{\link{icreateGate}} }

\examples{

  if (interactive()){
  if (require(rfcdmin)){
    ## obtaining the FCS objects from VRC data
    if ( !(is.element("unst.1829", objects())
                    & is.element("st.1829", objects())) ){
      data(VRCmin)
    }

    ## univariate plot
    plotvar.FCS(unst.1829, type="uni", varpos=1, plotType=hist)
    ## show cut off at 350
    showgate.FCS(unst.1829@data[,1], type="uniscut", gatingrange=350)
    ## show different cutoff at 500
    showgate.FCS(unst.1829@data[,1], type="uniscut", gatingrange=500,
                 coltype="green")

    ## bivariate plot : rectanglar bins in which the gate can be shown
    plotvar.FCS(unst.1829, type="bi", varpos=c(1,2), hexbin.CSPlot=FALSE)
    ## show cutoff at 275 to 600 for both variables
    ## may take a while
    ## create the gate index as the first column entry of the "gate" matrix
    unst.1829.gt<-createGate(unst.1829, varpos=1:2, type="bidcut",
          gatingrange=c(275, 600, 275, 600))

    ## show the gate
    showgate.FCS(unst.1829.gt@data[,c(1,2)], unst.1829.gt@gate[,1],
       type="bidcut", gatingrange=c(275, 600, 275, 600))

    }
  }

}
\keyword{aplot}