createGate {rflowcyt}R Documentation

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 createGate or interactively by icreateGate, a 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)

Arguments

x a FCS object
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)
gatingrange gating threshold range in one of the following formats for each type of gating:
"uniscut"
univariate single cut; gatingrange$=$x1 (will select/include all points $>=$ x1), x1 is numeric value
"bidcut"
bivariate double cut: gatingrange$=$c(x1,x2, y1,y2), a numeric vector of lowerbound, upperbound cutoffs for x and y variables
"biscut"
bivariate single cut:gatingrange$=$c(x1,y1), a numeric vector of the cutoffs for x and y variables
"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)
type character string of the type of cut/gating:
"uniscut"
univariate single cut: selects datapoints that are greater than or equal to the cutoff value denoted in gatingrange
"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)
"biscut"
bivariate single cut: cuts graph into quadrants (selects datapoints in the quadrant denoted by biscut.quadrant)
"bipcut"
bivariate polygonal cut: selects the datapoints in a polygon
biscut.quadrant character string value denoting the (x,y) quadrant that is to be selected; Values are one of the following:
"$+$/$+$"
selects the upper right quadrant, where x is positive and y is positive
"$-$/$+$"
selects the upper left quadrant, where x is negative and y is positive
"$+$/$-$"
selects the lower right quadrant, where x is positive and y is negative
"$-$/$-$"
selects the lower left quadrant, where x is negative and y is negative
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. NOTE: The datapoints not selected in the index specified by prev.colNum will not be selected in this gate either
prev.IndexValue.In the value of inclusion for the gating index specified by "prev.gateNum"
comment character string denoting the importance of the gating; default is the empty string
pchtype The type of point to plot observations that have been selected using showgate.FCS; default is using "."
MY.DEBUG If TRUE, prints out debugging statements; otherwise if FALSE, the debugging statements are surpressed; default is TRUE
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 icreateGate are not specified, then these options are prompted for the user to input values.

Use extractGateHistory to obtain information about the particular gating/selection index from the "history" string.

Usually the function extractGatedData is used to row reduce the data of the FCS object.

For an example of a sequential interactive gating scheme please use FHCRC.HVTNFCS for the FCS objects in data(FHCRC) of the 'rfcdorig' package and use VRC.HVTNFCS for the FCS objects in data(VRC) of the 'rfcdorig' library.

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

When all gating parameters are input in 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 FCSgate S4 object is returned that extends the FCS object to contain additional slots:

gate a matrix whose columns are the gating indices for the original data
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
extractGatedData.msg vector of strings to specify what if any extraction has been implemented using extractGatedData; "NONE" specifies no extraction has been implemented on the data for that particular corresponding gating index
current.data.obs vector of the original data row positions that are currently still in the data matrix

Author(s)

A.J. Rossini and J.Y. Wan

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.

See Also

extractGatedData, 'FHCRC' data in the 'rfcdorig' package, FHCRC.HVTNFCS, 'VRC' data in the 'rfcdorig' package, VRC.HVTNFCS,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)
      }
    }

[Package rflowcyt version 1.4.0 Index]