createGate             package:rflowcyt             R Documentation

_G_a_t_i_n_g _o_f _a _F_C_S _o_b_j_e_c_t: _M_a_k_i_n_g _a _G_a_t_i_n_g/_S_e_l_e_c_t_i_o_n _i_n_d_e_x
_c_o_l_u_m_n _f_o_r _s_u_b_s_e_q_u_e_n_t _e_x_t_r_a_c_t_i_o_n

_D_e_s_c_r_i_p_t_i_o_n:

     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.

_U_s_a_g_e:

     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)

_A_r_g_u_m_e_n_t_s:

       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:

     "_u_n_i_s_c_u_t" univariate single cut; gatingrange$=$x1 (will
          select/include all  points $>=$ x1), x1 is numeric value

     "_b_i_d_c_u_t" bivariate double cut:  gatingrange$=$c(x1,x2, y1,y2), a
          numeric vector of lowerbound, upperbound cutoffs for x and y
          variables

     "_b_i_s_c_u_t" bivariate single cut:gatingrange$=$c(x1,y1), a numeric
          vector of the cutoffs for x and y variables 

     "_b_i_p_c_u_t" 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:

     "_u_n_i_s_c_u_t" univariate single cut: selects datapoints that are
          greater than or equal to the cutoff value denoted in
          gatingrange

     "_b_i_d_c_u_t" bivariate double cut: selects datapoints in the central
          rectangle formed by two vertical lines (x variable cutoffs)
          and two horizontal lines (y variable cutoffs)

     "_b_i_s_c_u_t" bivariate single cut: cuts graph into quadrants (selects
          datapoints in the quadrant denoted by biscut.quadrant)

     "_b_i_p_c_u_t" 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

_D_e_t_a_i_l_s:

     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.

_V_a_l_u_e:

     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

_A_u_t_h_o_r(_s):

     A.J. Rossini and J.Y. Wan

_R_e_f_e_r_e_n_c_e_s:

     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.

_S_e_e _A_l_s_o:

     'extractGatedData', 'FHCRC' data in the 'rfcdorig' package,
     'FHCRC.HVTNFCS', 'VRC' data in the 'rfcdorig' package,
     'VRC.HVTNFCS','extractGateHistory'

_E_x_a_m_p_l_e_s:

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

