consensus                package:clue                R Documentation

_C_o_n_s_e_n_s_u_s _P_a_r_t_i_t_i_o_n_s _a_n_d _H_i_e_r_a_r_c_h_i_e_s

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

     Compute the consensus clustering of an ensemble of partitions or
     hierarchies.

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

     cl_consensus(x, method = NULL, weights = 1, control = list())

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

       x: an ensemble of partitions or hierarchies, or something
          coercible to that (see 'cl_ensemble').

  method: a character string specifying one of the built-in methods for
          computing consensus clusterings, or a function to be taken as
          a user-defined method, or 'NULL' (default value).  If a
          character string, its lower-cased version is matched against
          the lower-cased names of the available built-in methods using
          'pmatch'.  See *Details* for available built-in methods and
          defaults.

 weights: a numeric vector with non-negative case weights. Recycled to
          the number of elements in the ensemble given by 'x' if
          necessary.

 control: a list of control parameters.  See *Details*.

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

     Consensus clusterings "synthesize" the information in the elements
     of a cluster ensemble into a single clustering, often by
     minimizing a criterion function measuring how dissimilar consensus
     candidates are from the (elements of) the ensemble (the so-called
     "optimization approach" to consensus clustering).  

     The most popular criterion functions are of the form L(x) = sum
     w_b d(x_b, x)^p, where d is a suitable dissimilarity measure (see
     'cl_dissimilarity'), w_b is the case weight given to element x_b
     of the ensemble, and p >= 1.  If p = 1 and minimization is over
     all possible base clusterings, a consensus solution is called a
     _median_ of the ensemble; if minimization is restricted to the
     elements of the ensemble, a consensus solution is called a
     _medoid_ (see 'cl_medoid').  For p = 2, we obtain _least squares_
     consensus partitions and hierarchies (generalized means). See also
     Gordon (1999) for more information.

     If all elements of the ensemble are partitions, the built-in
     consensus methods compute soft least squares consensus partitions
     for Euclidean and co-membership dissimilarities (i.e., minima of
     L(x) = sum w_b d(x_b, x)^2 over all soft partitions with k
     classes).

     Available methods are as follows.

     '"_D_W_H"' an extension of the greedy algorithm in Dimitriadou,
          Weingessel and Hornik (2002) for approximately minimizing L
          with d being Euclidean dissimilarity. The reference provides
          some structure theory relating finding the consensus
          partition to an instance of the multiple assignment problem,
          which is known to be NP-hard, and suggests a simple heuristic
          based on successively matching an individual partitions x_b
          to the current approximation to the consensus partition, and
          compute the memberships of the next approximation as a
          weighted average of those of the current one and of x_b after
          permuting its columns for the optimal matching of class ids.

          The following control parameters are available for this
          method.

          '_k' an integer giving the number of classes to be used for
               the least squares consensus partition.  By default, the
               maximal number of classes in the ensemble is used.

          '_o_r_d_e_r' a permutation of the integers from 1 to the size of
               the ensemble, specifying the order in which the
               partitions in the ensemble should be aggregated. 
               Defaults to using a random permutation (unlike the
               reference, which does not permute at all).


     '"_G_V_1"' the fixed-point algorithm for the "first model" in Gordon
          and Vichi (2001) for minimizing L with d again being
          Euclidean dissimilarity.  This iterates between individually
          matching all partitions to the current approximation to the
          consensus partition, and computing the next approximation as
          a weighted average of the memberships of all partitions after
          permuting their columns for the optimal matchings of class
          ids.

          The following control parameters are available for this
          method.

          '_k' an integer giving the number of classes to be used for
               the least squares consensus partition.  By default, the
               maximal number of classes in the ensemble is used.

          '_m_a_x_i_t_e_r' an integer giving the maximal number of iterations
               to be performed.  Defaults to 100.

          '_r_e_l_t_o_l' the relative convergence tolerance. Defaults to
               'sqrt(.Machine$double.eps)'.

          '_s_t_a_r_t' a matrix with number of rows equal to the size of the
               cluster ensemble, and k columns, to be used as a
               starting value.  By default, suitable random membership
               matrices are used.

          '_v_e_r_b_o_s_e' a logical indicating whether to provide some output
               on minimization progress.  Defaults to
               'getOption("verbose")'.


     '"_G_V_3"' a SUMT algorithm for the "third model" in Gordon and Vichi
          (2001) for minimizing L with d being co-membership
          dissimilarity.  See 'ls_fit_ultrametric' for more information
          on the SUMT approach.  This optimization problem is
          equivalent to finding the membership matrix m for which the
          sum of the squared differences between C(m) = m m' and the
          weighted average co-membership matrix sum_b w_b C(m_b) of the
          partitions is minimal.

          Availabe control parameters are 'method', 'control', 'eps',
          'q', and 'verbose', which have the same roles as for
          'ls_fit_ultrametric', and the following.

          '_k' an integer giving the number of classes to be used for
               the least squares consensus partition.  By default, the
               maximal number of classes in the ensemble is used.

          '_s_t_a_r_t' a matrix with number of rows equal to the size of the
               cluster ensemble, and k columns, to be used as a
               starting value.  By default, a membership based on a
               rank k approximation to the weighted average
               co-membership matrix is used.


     By default, method '"DWH"' is used.

     If all elements of the ensemble are hierarchies, the built-in
     method (named '"cophenetic"') for computing consensus hierarchies
     is based on minimizing L(u) = sum w_b d(x_b, u) ^ 2 over all
     ultrametrics, where d is Euclidean dissimilarity.  This is
     equivalent to finding the best least squares ultrametric
     approximation of the weighted average d = sum w_b u_b of the
     ultrametrics u_b of the hierarchies x_b, which is attempted by
     calling 'ls_fit_ultrametric' on d with appropriate control
     parameters.

     If a user-defined agreement method is to be employed, it must be a
     function taking the cluster ensemble, the case weights, and a list
     of control parameters as its arguments.

     All built-in methods use heuristics for solving hard optimization
     problems, and cannot be guaranteed to find a global minimum. 
     Standard practice would recommend to use the best solution found
     in "sufficiently many" replications of the methods.

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

     The consensus partition or hierarchy.

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

     E. Dimitriadou and A. Weingessel and K. Hornik (2002). A
     combination scheme for fuzzy clustering. _International Journal of
     Pattern Recognition and Artificial Intelligence_, *16*, 901-912.

     A. D. Gordon and M. Vichi (2001). Fuzzy partition models for
     fitting a set of partitions. _Psychometrika_, *66*, 229-248.

     A. D. Gordon (1999). _Classification_ (2nd edition). Boca Raton,
     FL: Chapman & Hall/CRC.

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

     'cl_medoid'

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

     ## Consensus partition for the Rosenberg-Kim kinship terms partition
     ## data based on co-membership dissimilarities.
     data("Kinship82")
     m1 <- cl_consensus(Kinship82, method = "GV3",
                        control = list(k = 3, verbose = TRUE))
     ## (Note that one should really use several replicates of this.)
     ## Value for criterion function to be minimized:
     sum(cl_dissimilarity(Kinship82, m1, "comem") ^ 2)
     ## Compare to the consensus solution given in Gordon & Vichi (2001).
     data("Kinship82_Consensus")
     m2 <- Kinship82_Consensus[["JMF"]]
     sum(cl_dissimilarity(Kinship82, m2, "comem") ^ 2)
     ## Seems we get a better solution ...
     ## How dissimilar are these solutions?
     cl_dissimilarity(m1, m2, "comem")
     ## How "fuzzy" are they?
     cl_fuzziness(cl_ensemble(m1, m2))
     ## Do the "nearest" hard partitions fully agree?
     cl_dissimilarity(as.cl_hard_partition(m1),
                      as.cl_hard_partition(m2))
     ## Hmm ...

     ## Consensus partition for the Gordon and Vichi (2001) macroeconomic
     ## partition data based on Euclidean dissimilarities.
     data("GVME")
     set.seed(1)
     m1 <- cl_consensus(GVME, method = "GV1",
                        control = list(k = 2, verbose = TRUE))
     ## (Note that one should really use several replicates of this.)
     ## Value of criterion function to be minimized:
     sum(cl_dissimilarity(GVME, m1) ^ 2)
     ## Compare to the consensus solution given in Gordon & Vichi (2001).
     data("GVME_Consensus")
     m2 <- GVME_Consensus[["MF1"]]
     sum(cl_dissimilarity(GVME, m2) ^ 2)
     ## Seems we get a better solution ...
     ## (But note that for partitions with different numbers of classes,
     ## they only use the matches classes for computing dissimilarities.)
     ## And in fact, it is qualitatively different:
     table(as.cl_hard_partition(m1),
           as.cl_hard_partition(m2))
     ## Hmm ...

