4mmclcm24m(1)                        USER COMMANDS                         4mmclcm24m(1)

  1mNAME0m
      mclcm - hierarchical clustering of graphs with mcl

  1mSYNOPSIS0m
      1mmclcm 22m<-|fname> [mclcm-options] [-- "mcl options"*]

      1mmclcm 22m<-|fname> -a "-I 4 --shadow=vl"
      1mmclcm 22m<-|fname> -a "-I 3" -- "-I 5"
      1mmclcm 22m<-|fname> -a "-I 3" -b1 "" -- "-ph 3 --shadow=vl -I 5"

      1mmclcm  22m<-fname>  1m[--contract  22m(4mcontraction24m  4mmode24m)1m] [--dispatch 22m(4mdispatch0m
      4mmode24m)1m] [--integrate 22m(4mintegrate24m 4mmode24m)1m] [--subcluster  22m(4msubcluster24m  4mmode24m)1m]0m
      1m[-a  22m<opts>  (4mshared24m 4mmcl24m 4moptions24m)1m] [-b1 22m<opts> (4mdedicated24m 4mbase24m 4m124m 4mmcl24m 4mop-0m
      4mtions24m)1m] [-b2 22m<opts> (4mdedicated24m 4mbase24m 4m224m 4mmcl24m 4moptions24m)1m] [-tf 22mspec (4mapply24m 4mtf-0m
      4mspec24m 4mto24m 4minput24m 4mmatrix24m)1m] [-c 22m<fname> (4minput24m 4mclustering24m)1m] [-n 22m<num> (4mitera-0m
      4mtion24m 4mlimit24m)1m] [--root 22m(4mensure24m 4muniverse24m 4mroot24m 4mclustering24m)1m]  [-cone  22m<fname>
      (4mnested24m  4mcluster24m  4mstack24m  4mfile24m)1m]  [-stack 22m<fname> (4mexpanded24m 4mcluster24m 4mstack0m
      4mfile24m)1m]   [-coarse   22m<fname>    (4mcoarsened24m    4mgraphs24m    4mfile24m)1m]    [-write0m
      (4mstack,cone,coarse,steps24m)1m]  [-write-base  22m<fname>  (4mwrite24m  4mbase24m 4mmatrix24m)1m]0m
      1m[-stem 22m<str> (4mprefix24m 4mfor24m 4mall24m 4moutputs24m)1m] [--mplex=22my/n  (4mwrite24m  4mclusterings0m
      4mseparately24m)1m] [-annot 22mstr (4mdummy24m 4mannotation24m 4moption24m)1m] [-h 22m(4mprint24m 4msynopsis,0m
      4mexit24m)1m]  [--apropos  22m(4mprint24m  4msynopsis,24m  4mexit24m)1m] [--version 22m(4mprint24m 4mversion,0m
      4mexit24m)1m] [-q 22mspec (4mlog24m 4mlevels24m)1m] [-z 22m(4mshow24m  4mdefault24m  4mshared24m  4moptions24m)1m]  22m[--
      "mcl options"*]

  1mDESCRIPTION0m
      The  mclcm  options  may  be followed by a number of trailing arguments.
      The trailing arguments should be separated from the mclcm options by the
      separator --.  Normally each trailing argument should consist of  a  set
      of  zero, one, or more mcl arguments enclosed in quotes or double quotes
      to group them together.  These arguments are passed  to  the  successive
      stages  of  hierarchical  clustering. They are combined with the default
      options. If an option is specified both in the default options list  and
      in  a  trailing options list the latter specification overrides the for-
      mer.  When the 1m--integrate 22moption is specified  the  trailing  arguments
      must  be  names  of files containing mcl clusterings; see further below.
      1mmclcm 22mhas four major modes of operation, namely  4mcontraction24m  (default),
      4mintegration24m,  4mdispatch24m,  and 4msubcluster24m. Each mode is described a little
      below. Note though that 4mdispatch24m mode is not the best mode  to  use  for
      hierarchical  clustering.  It  is mostly useful to generate multiple mcl
      clusterings in a single run.

      In all modes 1mmclcm 22mwill generate a file,  by  default  called  4mmcl.cone24m.
      This is a representation of a hierarchical clustering that is particular
      to mcl. It can be converted to 4mnewick24m format like this:

               mcxdump -imx-tree mcl.cone --newick -o NEWICKFILE
         OR    mcxdump -imx-tree mcl.cone --newick -o NEWICKFILE -tab TABFILE

      In  the last example, TABFILE should be a file containing a mapping from
      mcl labels to application labels. Refer to 1mmcxio(5) 22mfor more information
      about tab files and mcl input/ouput formats.

  1mOPTIONS0m
      1m--contract 22m(4mrepeated24m 4mcontraction24m 4mmode24m)
        This is the default mode of operation.  At  each  successive  step  of
        constructing  the  hierarchy on top of the first level mcl clustering,
        mclcm uses a matrix derived from the input matrix and  the  last  com-
        puted  clustering to compute a contracted graph.  The contracted graph
        is a graph where the nodes represent the clusters of the last cluster-
        ing. The matrix derived from the input graph that is used to construct
        the contracted graph is called the 4mbase24m 4mmatrix24m. The base matrix can be
        either the 4mstart24m 4mmatrix24m or the 4mexpansion24m 4mmatrix24m.  The 4mstart24m 4mmatrix24m  is
        the  input  matrix  after  transformations have been applied to it (if
        any).  The 4mexpansion24m 4mmatrix24m is the first expanded matrix of  some  mcl
        process applied to the input graph.

        By default the base matrix is constructed from either the start matrix
        or  the  expansion  matrix obtained from the first mcl process.  It is
        possible to use a start matrix derived from special purpose mcl trans-
        formation parameters (such as 1m-ph 22mand 1m-tf22m) or an expansion matrix  de-
        rived  from a special purpose mcl process.  The 1m-b1 22mand 1m-b2 22mparameters
        provide the interfaces to this functionality.

        You are advised to start with a high inflation  value  for  the  input
        graph  and  to use shadowing, e.g. include --shadow=vl in the 1m-a 22margu-
        ment.  This generally leads to hierarchies that are  better  balanced.
        Shadowing is a transformation where nodes are added to the graph, pre-
        venting relatively distant nodes from unwanted chaining.  For more in-
        formation  refer to the 1mmcl 22mmanual.  The invocations in 1mSYNOPSIS 22mare a
        good starting point.

      1m--dispatch 22m(4mdifferent24m 4mmcl24m 4mprocesses24m)
        In this mode each trailing argument is specified as a set  of  options
        to  pass  to an mcl process. For each trailing argument an mcl process
        is thus computed. The set of resulting clusterings is integrated  into
        a hierarchy.

      1m--integrate 22m(4mexisting24m 4mclusterings24m)
        This  mode  is  similar  to 4mdispatch24m mode. The difference is that with
        this option mclcm simply integrates a set of already existing cluster-
        ings.  Each trailing argument must be the name of a file containing  a
        clustering.   The set of clusterings thus specified is integrated into
        a hierarchy.

      1m--subcluster 22m(4mrepeated24m 4msub-clustering24m)
        In this mode each trailing argument specifies a set of options to pass
        to an mcl process. The second clustering process  is  applied  to  the
        graph  of  components  induced by the first clustering, resulting in a
        further subdivision of the first clustering. This approach is repeated
        with each further trailing argument. With  this  approach,  the  first
        clustering  will  be  the  most  coarse  clustering. Hence, subsequent
        trailing arguments will typically specify increasingly  higher  infla-
        tion  values,  pre-inflation  values,  and  optionally  more stringent
        transformation parameters in order to achieve further subdivsions.

      1m-a 22m<opts> (4mshared24m 4mmcl24m 4moptions24m)
        Use this to change and/or set the default mcl options for  all  itera-
        tions. Use quotes if necessary.  Example of usage: -a "-I 5".

      1m-b1 22m<opts> (4mdedicated24m 4mbase24m 4m124m 4mmcl24m 4moptions24m)
        This  will apply the mcl options 4mopts24m to the input matrix. The result-
        ing start matrix is used as the  base  matrix  for  constructing  con-
        tracted graphs.

      1m-b2 22m<opts> (4mdedicated24m 4mbase24m 4m224m 4mmcl24m 4moptions24m)
        This  will  apply the mcl options 4mopts24m to the input matrix and compute
        the first iterand of the corresponding mcl process. The first iterand,
        aka the expansion matrix, is used as the base matrix for  constructing
        contracted graphs.

      1m-tf 22m<tf-spec> (4mtransform24m 4minput24m 4mmatrix24m 4mvalues24m)
        Transform the input matrix values according to the syntax described in
        1mmcxio(5)22m.

      1m-c 22m<fname> (4minput24m 4mclustering24m)
        The hierarchical clustering process will be kicked off by the cluster-
        ing found in 4m<fname>24m.

      1m-n 22m<num> (4miteration24m 4mlimit24m)
        This  puts  an  upper bound to the number of contractions that will be
        performed.

      1m--root 22m(4mensure24m 4muniverse24m 4mroot24m 4mclustering24m)
        In case the graph consists of different connected components, the last
        clustering computed by the mclcm process will  correspond  with  those
        connected components. This option simply adds an artificial clustering
        where all nodes have been joined into a single cluster.

      1m-cone 22m<fname> (4mnested24m 4mcluster24m 4mstack24m 4mfile24m)
        File  to  write the nested cluster stack to.  The nested cluster stack
        contains a sequence of clusterings, each written  as  an  MCL  matrix.
        The  first (bottom) clustering is a clustering of the nodes in the in-
        put graph. Each subsequent clustering is a clustering where the  nodes
        are  the  clusters  of the previous clustering.  1mmcxdump 22mcan dump this
        format if the file name is given as the 1m-imx-stack 22moption. The  expla-
        nation  for  the cone/stack discrepancy is simple. To mcxdump the con-
        tents are simply a stack of matrices. It does  not  care  whether  the
        stack is cone shaped, cylindrical, or yet another shape.

      1m-stack 22m<fname> (4mexpanded24m 4mcluster24m 4mstack24m 4mfile24m)
        File  to  write  the  expanded  cluster stack to. The expanded cluster
        stack is similar to the nested cluster stack except that each  cluster
        lists  all the nodes in the input graph it contains.  1mmcxdump 22mcan dump
        this format if the file name is given as the 1m-imx-stack 22moption.

      1m-coarse 22m<fname> (4mcoarsened24m 4mgraphs24m 4mfile24m)
        File to write the sequence of coarsened graphs to. Each clustering in-
        duces a coarsened graph where the nodes represent the clusters and  an
        edge  between two nodes represents the connectivity between the corre-
        sponding two clusters. The computation of this connectivity takes into
        account all edges between the two clusters in in the original graph.

      1m-write 22m<tag> (4mselect24m 4moutput24m 4mmodes24m)
        Use this option to explicitly specify all of the output types you want
        written in a comma-separated string. 4m<tag>24m  may  contain  any  of  the
        strings  4mstack24m,  4mcone24m, 4mcoarse24m, 4msteps24m.  The current default is to write
        all of these except 4mcoarse24m.  The latter dumps the intermediate  coars-
        ened (aka contracted) graphs to a single file.

      1m-write-base 22m<fname> (4mwrite24m 4mbase24m 4mmatrix24m)
        Write the base matrix to file. This can be useful for debugging expec-
        tations.

      1m-stem 22m<str> (4mprefix24m 4mfor24m 4mall24m 4moutputs24m)
        All  output files share the same prefix. The default is mcl and can be
        changed with this option.

      1m--mplex22m=y/n (4mwrite24m 4mclusterings24m 4mseparately24m)
        If turned on each clustering is written in a separate file. The  first
        clustering  is written to the file 4m<stem>24m.3 where 4m<stem>24m is determined
        by the 1m-stem 22moption. For each subsequent clustering the index  is  in-
        cremented  by  two,  so clusterings are written to files for which the
        name ends with an odd index.

      1m-annot 22mstr (4mdummy24m 4mannotation24m 4moption24m)
        1mmclcm 22mwrites the command line with which it was invoked to the  output
        file  (either  of the 4mcone24m or 4mstack24m files). Use this option to include
        any additional information. mclcm does nothing with this option except
        copying it as just described.

      1m-q 22mspec (4mlog24m 4mlevels24m)
        Set the quiet level. Read 1mtingea.log(7) 22mfor syntax and semantics.

      1m-z 22m(4mshow24m 4mdefault24m 4mshared24m 4moptions24m)
        Show the default mcl options. These are used for each  mcl  invocation
        as  successively  applied to the input graph and succeeding contracted
        graphs.

  1mAUTHOR0m
      Stijn van Dongen.

  1mSEE ALSO0m
      1mmclfamily(7) 22mfor an overview of all the documentation and the  utilities
      in the mcl family.

  mclcm 22-282                      9 Oct 2022                          4mmclcm24m(1)
