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' integrate with the 'flowCore' package.

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

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

_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 are 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', 'nu.est', 'trans', 'min.count', 'max.count', 'min',
          'max', 'level', 'u.cutoff', 'z.cutoff', 'randomStart',
          'B.init', 'tol.init', 'seed' and 'criterion'.  All arguments
          are optional except 'K' that specifies the number of
          clusters.

_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 is defined in package 'flowCore' and returns
     an object of class 'tmixFilterResult' (or 'tmixFilterResultList'
     if 'filter@K' has a length >1) 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.

     If 'filter@K' is of length 1, the 'filter' method returns an
     object of class 'tmixFilterResult'.  This class extends both the
     'multipleFilterResult' class (in the 'flowCore' package) and the
     'flowClust' class.  Operations defined for the
     'multipleFilterResult' 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 'criterion',
     'ruleOutliers', 'ruleOutliers<-', 'Map', 'posterior',
     'importance', 'uncertainty' and 'getEstimates'.  Various
     functionalities for plotting the filtering results are also
     available (see the links below).

     If 'filter@K' has a length >1, the function returns an object of
     class 'tmixFilterResultList'.  This class extends both the
     'flowClustList' class and the 'multipleFilterResult' class.  Note
     that when a 'tmixFilterResultList' object is used in place of a
     'tmixFilterResult' object, in most cases the list element
     corresponding to the best model will be extracted and passed to
     the method/function call.

_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,]
     # this can also be done using the Subset method
     rituximab2 <- Subset(rituximab, res1)

     ### 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, population=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)
     plot(rituximab2, res2, level=0.8, include=c(1,2), grayscale=TRUE,
         pch.outliers=2)
     # a contour / image plot
     res2.den <- density(res2, data=rituximab2)
     plot(res2.den)
     plot(res2.den, scale="sqrt", drawlabels=FALSE)
     plot(res2.den, type="image", nlevels=100)
     plot(density(res2, include=c(1,2), from=c(0,0), to=c(400,600)))
     # a histogram (1-D density) plot
     plot(rituximab2, res2, "FL1.H")

     ### to demonstrate the use of the ruleOutliers method
     summary(res2)
     # change the rule to call outliers
     ruleOutliers(res2) <- list(level=0.95)
     # augmented cluster boundaries lead to fewer outliers
     summary(res2)

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

