Usage: A program to perform clustering analysis surfaces.
SurfClust <[-spec SpecFile -surf_A insurf] [-i insurf]>
<-input inData.dset dcol_index>
<-rmm rad>
[-amm2 minarea]
[-n minnodes]
[-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:
Surface Input can be done with:
-spec SpecFile: The surface spec file.
-surf_A insurf: The input surface name.
or with:
-i insurf: With insurf being the full name of the surface.
-input inData.dset dcol_index: The input 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).
If you want the distance to be in number of edges,
set rad to -N for an N edge max distance.
For example -rmm -2 means that nodes connected
by 1 or two edges are in a cluster.
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.
-ir_range R0 R1: Apply thresholding in range.
A node n is considered if
thresh_col[n] >= R0 && thresh_col[n] <= R1
-ex_range R0 R1: Apply thresholding outside of range.
A node n is considered if
thresh_col[n] < R0 || thresh_col[n] > R1
-amm2 minarea: Do not output results for clusters having
an area less than minarea.
If minarea < 0 AND -n is not set (or < 0)
then minnodes = -minarea . See option -n below.
-n minnodes: Do not output results for clusters having
less nodes than minnodes.
minnodes can get set with negative minarea above.
-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.
-cent: Do find the central nodes (default)
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) ).
Col. 13 = Minimum |value|
Col. 14 = |Minimum| node
Col. 15 = Maximum |value|
Col. 16 = |Maximum| node
Col. 17 = Center of Mass x
Col. 18 = Center of Mass y
Col. 19 = Center of Mass z
Col. 20 = Centroid x
Col. 21 = Centroid y
Col. 22 = Centroid z
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]: Ignore any Rotate, Volreg, Tagalign,
or WarpDrive transformations present in
the Surface Volume.
[-noxform]: Same as -novolreg
[-setenv "'ENVname=ENVvalue'"]: Set environment variable ENVname
to be ENVvalue. Quotes are necessary.
Example: suma -setenv "'SUMA_BackgroundColor = 1 0 1'"
See also options -update_env, -environment, etc
in the output of 'suma -help'
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.
Global Options (available to all AFNI/SUMA programs)
-h: Mini help, at time, same as -help in many cases.
-help: The entire help output
-HELP: Extreme help, same as -help in majority of cases.
-h_view: Open help in text editor. AFNI will try to find a GUI editor
-hview : on your machine. You can control which it should use by
setting environment variable AFNI_GUI_EDITOR.
-h_web: Open help in web browser. AFNI will try to find a browser.
-hweb : on your machine. You can control which it should use by
setting environment variable AFNI_GUI_EDITOR.
-h_find WORD: Look for lines in this programs's -help output that match
(approximately) WORD.
-h_raw: Help string unedited
-h_spx: Help string in sphinx loveliness, but do not try to autoformat
-h_aspx: Help string in sphinx with autoformatting of options, etc.
-all_opts: Try to identify all options for the program from the
output of its -help option. Some options might be missed
and others misidentified. Use this output for hints only.
Compile Date:
Oct 13 2022
