tmixFilter             package:flowClust             R Documentation

_C_r_e_a_t_i_n_g _F_i_l_t_e_r_s _a_n_d _F_i_l_t_e_r_i_n_g _F_l_o_w _C_y_t_o_m_e_t_r_y _D_a_t_a

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

     The 'tmixFilter' function creates a filter object which is then
     passed to the 'filter' method that performs filtering on a
     'flowFrame' object.  This method pair is provided to let
     'flowClust' highly integrate with the 'flowCore' package.

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

     tmixFilter(filterId="tmixFilter", parameters="", ...)

     ## S4 method for signature 'flowFrame, tmixFilter':
     filter(x, filter)

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

filterId: A character string that identifies the filter created.

parameters: A character vector specifying the variables to be used in
          filtering.  When it is left unspecified, all the variables of
          the 'flowFrame' object will be used when running 'filter'. 
          Note that its content will be passed to the 'varNames'
          argument of 'flowClust' when running 'filter'.

     ...: Other arguments passed to the 'flowClust' function when
          running 'filter', namely, 'expName', 'K', 'B', 'tol', 'nu',
          'lambda', 'trans', 'min.count', 'max.count', 'min', 'max',
          'level', 'u.cutoff', 'z.cutoff' and 'randomStart'.  All
          arguments are optional except 'K' that specifies the number
          of clusters.

       x: Object of class 'flowFrame'.

  filter: Object returned from 'tmixFilter'.

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

     The 'tmixFilter' function returns an object of class 'tmixFilter'
     that stores all the settings required for performing the 'filter'
     operations.

     The 'filter' method returns an object of class 'tmixFilterResult'
     that stores the filtering results.

_N_o_t_e:

     The 'tmixFilter' function returns an object of class 'tmixFilter'
     that extends the virtual parent 'filter' class in the 'flowCore'
     package.  Hence, the filter operators, namely, '&', '|', '!' and
     '%subset%', also work for the 'tmixFilter' class.

     The 'filter' method returns an object of class 'tmixFilterResult'.
      This class extends both the 'filterResult' class (in the
     'flowCore' package) and the 'flowClust' class.  Operations defined
     for the 'filterResult' class, like '%in%', 'Subset' and 'split',
     also work for the 'tmixFilterResult' class.  Likewise, methods or
     functions designed to retrieve filtering (clustering) information
     from a 'flowClust' object can also be applied on a
     'tmixFilterResult' object.  These include 'ruleOutliers',
     'ruleOutliers<-', 'Map', 'posterior', 'importance', 'uncertainty'
     and 'getEstimates'.  Various functionalities for plotting the
     filtering results are also available (see the links below).

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

     Raphael Gottardo <raph@stat.ubc.ca>, Kenneth Lo <c.lo@stat.ubc.ca>

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

     Lo, K., Brinkman, R. R. and Gottardo, R. (2008) Automated Gating
     of Flow Cytometry Data via Robust Model-based Clustering.
     _Cytometry A_ *73*, 321-332.

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

     'flowClust', 'summary', 'plot', 'density', 'hist', 'Subset',
     'split', 'ruleOutliers', 'Map'

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

     ### The example below largely resembles the one in the flowClust
     ### man page.  The main purpose here is to demonstrate how the
     ### entire cluster analysis can be done in a fashion highly
     ### integrated into flowCore.

     data(rituximab)

     ### create a filter object
     s1filter <- tmixFilter("s1", c("FSC.H", "SSC.H"), K=1)
     ### cluster the data using FSC.H and SSC.H
     res1 <- filter(rituximab, s1filter)

     ### remove outliers before proceeding to the second stage
     # %in% operator returns a logical vector indicating whether each
     # of the observations lies inside the gate or not
     rituximab2 <- rituximab[rituximab %in% res1,]
     # a shorthand for the above line
     rituximab2 <- rituximab[res1,]
     # Subset has an optional select argument to select columns
     Subset(rituximab, res1, select=c("FSC.H", "SSC.H", "FL1.H", "FL3.H"))

     ### cluster the data using FL1.H and FL3.H (with 3 clusters)
     s2filter <- tmixFilter("s2", c("FL1.H", "FL3.H"), K=3)
     res2 <- filter(rituximab2, s2filter)

     show(s2filter)
     show(res2)
     summary(res2)

     # to demonstrate the use of the split method
     split(rituximab2, res2)
     split(rituximab2, res2, split=list(sc1=c(1,2), sc2=3))

     # to show the cluster assignment of observations
     table(Map(res2))

     # to show the cluster centres (i.e., the mean parameter estimates
     # transformed back to the original scale) and proportions
     getEstimates(res2)

     ### demonstrate the use of various plotting methods
     # a scatterplot
     plot(rituximab2, res2, level=0.8)
     # a contour / image plot
     res2.den <- density(res2, data=rituximab2)
     plot(res2.den)
     plot(res2.den, type="image", nlevels=100)
     # a histogram (1-D density) plot
     plot(rituximab2, res2, "FL1.H")

     # the following line illustrates how to select a subset of data 
     # to perform cluster analysis through the min and max arguments;
     # also note the use of level to specify a rule to call outliers
     # other than the default
     s2t <- tmixFilter("s2t", c("FL1.H", "FL3.H"), K=3, B=100, 
         min=c(0,0), max=c(400,800), level=0.95, z.cutoff=0.5)
     filter(rituximab2, s2t)

