\HeaderA{showgate.FCS}{Showing the gate and the datapoints within the gate on a prevous plot}{showgate.FCS}
\keyword{aplot}{showgate.FCS}
\begin{Description}\relax
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).
\end{Description}
\begin{Usage}
\begin{verbatim}
showgate.FCS(data.mat, gatingrange, Index,
       type = c("uniscut", "biscut", "bidcut", "bipcut"),
       IndexValue.In = 1,
       coltype = 12, pchtype = 8,
       biscut.quadrant = c("+/-","-/-", "+/+", "-/+")) 
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{data.mat}] the data to be gated:
\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[\code{gatingrange}] gating threshold range in one of the following
formats for each type of gating:
\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[\code{Index}] a vector of 0's and 1's denoting the selection of row
observations of 'data.mat'
\item[\code{type}] character string of the type of cut/gating:
\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[\code{IndexValue.In}] The value of 'Index' to be selected; default is 1
\item[\code{coltype}] a character string or a numerical value describing the
option for the color of the data point inside the gating range
\item[\code{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[\code{biscut.quadrant}] character string value denoting the (x,y)
quadrant that is to be selected; Values are one of the following:
\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

\end{ldescription}
\end{Arguments}
\begin{Value}
The gating range or gate will be displayed and the data points within 
the gating range will be colored.
\end{Value}
\begin{Note}\relax
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{\LinkA{ContourScatterPlot}{ContourScatterPlot}}.  The
\code{\LinkA{showgate.FCS}{showgate.FCS}} does not work with hexagonal binning.
\end{Note}
\begin{Author}\relax
A.J. Rossini and J.Y. Wan
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{FHCRC.HVTNFCS}{FHCRC.HVTNFCS}},\code{\LinkA{VRC.HVTNFCS}{VRC.HVTNFCS}},
\code{\LinkA{plotvar.FCS}{plotvar.FCS}},\code{\LinkA{createGate}{createGate}},
\code{\LinkA{icreateGate}{icreateGate}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}

  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))

    }
  }

\end{ExampleCode}
\end{Examples}

