AFNI program: SurfClust

Usage: A program to perform clustering analysis surfaces.
  SurfClust <-spec SpecFile> 
            <-surf_A insurf> 
            <-input inData.1D dcol_index> 
            <-rmm rad>
            [-amm2 minarea]
            [-prefix OUTPREF]  
            [-out_clusterdset] [-out_roidset] 
            [-out_fulllist]
            [-sort_none | -sort_n_nodes | -sort_area]

  The program can outputs a table of the clusters on the surface,
  a mask dataset formed by the different clusters and a clustered
  version of the input dataset.

  Mandatory parameters:
     -spec SpecFile: The surface spec file.
     -surf_A insurf: The input surface name.
     -input inData.1D dcol_index: The input 1D dataset
                                  and the index of the
                                  datacolumn to use
                                  (index 0 for 1st column).
                                  Values of 0 indicate 
                                  inactive nodes.
     -rmm rad: Maximum distance between an activated node
               and the cluster to which it belongs.
               Distance is measured on the surface's graph (mesh).

  Optional Parameters:
     -thresh_col tcolind: Index of thresholding column.
                          Default is column 0.
      -thresh tval: Apply thresholding prior to clustering.
                   A node n is considered if thresh_col[n] > tval.
     -athresh tval: Apply absolute thresholding prior to clustering.
                    A node n is considered if | thresh_col[n] | > tval.
     -amm2 minarea: Do not output resutls for clusters having
                    an area less than minarea.
     -prefix OUTPREF: Prefix for output.
                      Default is the prefix of 
                      the input dataset.
                      If this option is used, the
                      cluster table is written to a file called
                      OUTPREF_ClstTable_rXX_aXX.1D. Otherwise the
                      table is written to stdout. 
                      You can specify the output format by adding
                      extensions to OUTPREF. For example, 
                      OUTPREF.1D.dset will force the output to be 
                      in the .1D format. 
                      See ConvertDset for many more format options.
     -out_clusterdset: Output a clustered version of inData.1D 
                       preserving only the values of nodes that 
                       belong to clusters that passed the rmm and amm2
                       conditions above.
                       The clustered dset's prefix has
                       _Clustered_rXX_aXX affixed to the OUTPREF
     -out_roidset: Output an ROI dataset with the value
                   at each node being the rank of its
                   cluster. The ROI dataset's prefix has
                   _ClstMsk_rXX_aXX affixed to the OUTPREF
                   where XX represent the values for the
                   the -rmm and -amm2 options respectively.
                   The program will not overwrite pre-existing
                   dsets.
     -prepend_node_index: Force the output dataset to have node
                    indices in column 0 of output. Use this option
                    if you are parsing .1D format datasets.
     -out_fulllist: Output a value for all nodes of insurf.
                    This option must be used in conjuction with
                    -out_roidset and/or out_clusterdset.
                    With this option, the output files might
                    be mostly 0, if you have small clusters.
                    However, you should use it if you are to 
                    maintain the same row-to-node correspondence
                    across multiple datasets.
     -sort_none: No sorting of ROI clusters.
     -sort_n_nodes: Sorting based on number of nodes
                    in cluster.
     -sort_area: Sorting based on area of clusters 
                 (default).
     -update perc: Pacify me when perc of the data have been
                   processed. perc is between 1% and 50%.
                   Default is no update.
     -no_cent: Do not find the central nodes.
               Finding the central node is a 
               relatively slow operation. Use
               this option to skip it.

  The cluster table output:
  A table where ach row shows results from one cluster.
  Each row contains 13 columns:   
     Col. 0  Rank of cluster (sorting order).
     Col. 1  Number of nodes in cluster.
     Col. 2  Total area of cluster. Units are the 
             the surface coordinates' units^2.
     Col. 3  Mean data value in cluster.
     Col. 4  Mean of absolute data value in cluster.
     Col. 5  Central node of cluster (see below).
     Col. 6  Weighted central node (see below).
     Col. 7  Minimum value in cluster.
     Col. 8  Node where minimum value occurred.
     Col. 9  Maximum value in cluster.
     Col. 10 Node where maximum value occurred.
     Col. 11 Variance of values in cluster.
     Col. 12 Standard error of the mean ( sqrt(variance/number of nodes) ).
   The CenterNode n is such that: 
   ( sum (Uia * dia * wi) ) - ( Uca * dca * sum (wi) ) is minimal
     where i is a node in the cluster
           a is an anchor node on the surface
           sum is carried over all nodes i in a cluster
           w. is the weight of a node 
              = 1.0 for central node 
              = value at node for the weighted central node
           U.. is the unit vector between two nodes
           d.. is the distance between two nodes on the graph
              (an approximation of the geodesic distance)
   If -no_cent is used, CenterNode columns are set to 0.

   [-novolreg|-noxform]: Ignore any Rotate, Volreg, Tagalign, 
                or WarpDrive transformations present in 
                the Surface Volume.
  Common Debugging Options:
   [-trace]: Turns on In/Out debug and Memory tracing.
             For speeding up the tracing log, I recommend 
             you redirect stdout to a file when using this option.
             For example, if you were running suma you would use:
             suma -spec lh.spec -sv ... > TraceFile
             This option replaces the old -iodbg and -memdbg.
   [-TRACE]: Turns on extreme tracing.
   [-nomall]: Turn off memory tracing.
   [-yesmall]: Turn on memory tracing (default).
  NOTE: For programs that output results to stdout
    (that is to your shell/screen), the debugging info
    might get mixed up with your results.
 

++ SUMA version 2006_7_3

CVS tag:
   SUMA_2005_04_29_1733

Compile Date:
   Jan 29 2009

       Ziad S. Saad SSCC/NIMH/NIH saadz@mail.nih.gov