Differences between revisions 2 and 3

Name

mri_surfcluster - This tool allows you to cluster surface data.

Synopsis

This program assigns each vertex on a cortical surface to a cluster based on the distribution of intensity values in the source file. A vertex must meet two criteria to be part of a cluster. First, its intensity must fall within a certain range (the intensity threshold criteria). Second, it must be part of a contiguous set of vertices that meet the threshold criteria and whose surface area is greater than a minimum.

There are three types of output. (1) Summary file - simple text file with a list of clusters found including maximum value, area, and talairach coordinate. (2) Filtered - identical to the input except that vertices not assigned to a cluster are set to 0. (3) Cluster number surface - this has the same format as the input and filtered output except that the value at each vertex is the cluster number assigned to it.

Arguments

--hemi hemi : lh or rh
- Specify the cortical hemisphere that the input represents. Valid values are lh and rh.
--src srcid <fmt> : source of surface values
- Input data to the clustering program. Fmt is the format specification. Currently, only paint format is supported.
--srcsubj subjid : source surface subject (can be ico) --srcsurf surface : get coorindates from surface (white)
- Surface to use when computing the talairach coordinates. Default is white.
--srcframe frameno : 0-based frame number
- Zero-based frame number of the input file. Default is 0. For paint format, zero is the only possible value.
--thmin threshold : minimum intensity threshold
- Minimum threshold in the intensity threshold criteria. See setting the cluster intensity threshold criteria below.
--thmax threshold : maximum intensity threshold
- Maximum threshold in the intensity threshold criteria. If negative, then the maximum threshold is infinity. See setting the cluster intensity threshold criteria below.
--thsign sign : <abs>, pos, neg
- This is used to control the sign of the threshold criteria. Legal values are pos, neg, and abs. See setting the cluster intensity threshold criteria below.
--minarea area : area threshold for a cluster (mm^2)
- Minimum surface area (in mm^2) that a set of contiguous vertices must achieve in order to be considered a cluster.
--sum sumfile : text summary file
- Text file in which to store the cluster summary. See Summary File Output below.
--o outid <fmt> : input with non-clusters set to 0
- File in which to store the surface values after setting the non-cluster vertices to zero. Fmt is the format (currently, only paint format is supported). Note: make sure to put a ./ in front of outputid or else it will attempt to write the output to the subject's surf directory.
--ocn ocnid <fmt> : value is cluster number
- File in which to store the cluster number of each vertex. This can be useful for determining to which cluster a particular vertex belongs. It can be viewed as with any other surface value file. Fmt is the format (currently, only paint format is supported). Note: make sure to put a ./ in front of outputid or else it will attempt to write the output to the subject's surf directory.
--olab outlabelbase : output clusters as labels
- Save output clusters as labels. There will be a label file for each cluster. The name will be outlabelbase-XXXX.label, where XXXX is the 4-digit, zero-paded cluster number. The stat field in the label will be the value of the input statistic at that vertex.
--cht chtfile nithr ithrlo ithrhi ithrsign nsthr sthrlo sthrhi --xfm xfmfile : talairach transform (def is talairach.xfm)
- This is a transform file that is used to compute the Talairach coordinates of a vertex for the summary file. The file must be found in subjects_dir/subjectid/transforms. The default is talairach.xfm which is based on the MNI atlas (see --fixmni).
--<no>fixmni : <do not> fix MNI talairach coordinates
- Fix (or do not fix) MNI Talairach coordinates based on Matthew Brett's
  transform. See http://www.mrc-cbu.cam.ac.uk/Imaging/mnispace.html. Default is to fix. The user may elect not to fix if the xfm file is not talairach.xfm (see --xfm).
--sd subjects_dir : (default is env SUBJECTS_DIR)
- This allows the user to change the FreeSurfer subjects's directory from the command-line. If unspecified, it will be set to the environment variable SUBJECTS_DIR
--help : answers to ALL your questions

Outputs

--sum sumfile : text summary file
--o outid <fmt> : input with non-clusters set to 0 --ocn ocnid <fmt> : value is cluster number --olab labelbase : output clusters as labels

SUMMARY FILE OUTPUT

The summary file (the argument of the --sum flag) will contain a summary of the result of the clustering as well as a summary of the conditions under which the clustering was performed. It will list the clusters (1 to N) along with the maximum value found in the cluster (Max), the vertex at which this maximum value was found (VtxMax), the surface area of the cluster (Size), and the Talaiarach coordinates of the maximum (based on talairach.xfm). A sample summary file is shown below.

Cluster Growing Summary (mri_surfcluster) $Id: mri_surfcluster.c,v 1.13 2004/10/19 23:32:42 greve Exp $ Input : minsig-0-lh.w Frame Number: 0 Minimum Threshold: 5 Maximum Threshold: infinity Threshold Sign: pos Area Threshold: 40 mm^2 NClusters 37 Total Cortical Surface Area 115576 (mm^2) FixMNI = 1

ClusterNo Max VtxMax Size(mm^2) TalX TalY TalZ

1 44.6 6370 636.79 -33.6 -69.8 49.2 2 40.3 48234 518.50 -2.9 -10.5 62.4 3 39.5 54239 103.19 -51.1 -13.3 45.3 4 39.5 55350 47.31 -50.1 -11.0 46.8

Bugs

Currently only supports paint (or w) format for input and output.

-Deletions are marked like this.
+Additions are marked like this.
 Line 14:
-mri_surfcluster - This tool allows you to cluster surface data. Specifically,
+mri_surfcluster - This tool allows you to cluster surface data.
-Line 17:
+Line 18:
-command argA argB -flag1 arg1 -flag2 arg2 [-flag3 arg3] [-flag4 arg4]
+This program assigns each vertex on a cortical surface to a cluster 

based on the distribution of intensity values in the source file. 

A vertex must meet two criteria to be part of a cluster. First, 

its intensity must fall within a certain range (the intensity threshold 

criteria). Second, it must be part of a contiguous set of vertices 

that meet the threshold criteria and whose surface area is greater  

than a minimum.  



There are three types of output. (1) Summary file - simple text file

with a list of clusters found including maximum value, area, and 

talairach coordinate. (2) Filtered - identical to the input except that

vertices not assigned to a cluster are set to 0. (3) Cluster number

surface - this has the same format as the input and filtered output

except that the value at each vertex is the cluster number assigned

to it.
-Line 20:
+Line 37:
-== Positional Arguments ==

|| argA || brief description || detailed description (eg, help file information)  ||

|| argB || brief description || detailed description (eg, help file information)  ||
-Line 24:
+Line 38:
-== Required Flagged Arguments ==

|| -flag1 arg1 || brief description || detailed description (eg, help file information) ||

|| -flag2 arg2 || brief description || detailed description (eg, help file information) ||
+   --hemi hemi : lh or rh 

         Specify the cortical hemisphere that the input represents. Valid values

         are lh and rh.
-Line 28:
+Line 42:
-== Optional Flagged Arguments ==

|| -flag3 arg3 || brief description ||detailed description (eg, help file information) ||

|| -flag4 arg4 || brief description ||detailed description (eg, help file information) ||
+   --src srcid <fmt> : source of surface values    

         Input data to the clustering program. Fmt is the format 

         specification. Currently, only paint format is supported.



   --srcsubj  subjid    : source surface subject (can be ico)

        

   --srcsurf  surface   : get coorindates from surface (white)

         Surface to use when computing the talairach coordinates.

         Default is white.



   --srcframe frameno   : 0-based frame number

         Zero-based frame number of the input file. Default is 0. For paint

         format, zero is the only possible value.



   --thmin    threshold : minimum intensity threshold

         Minimum threshold in the intensity threshold criteria. See 

         setting the cluster intensity threshold criteria below.



   --thmax    threshold : maximum intensity threshold

         Maximum threshold in the intensity threshold criteria. If negative,

         then the maximum threshold is infinity.  See setting the cluster

         intensity threshold criteria below.



   --thsign   sign      : <abs>, pos, neg

         This is used to control the sign of the threshold criteria. Legal

         values are pos, neg, and abs. See setting the cluster intensity

         threshold criteria below.



   --minarea  area      : area threshold for a cluster (mm^2)

       Minimum surface area (in mm^2) that a set of contiguous vertices

       must achieve in order to be considered a cluster.



   --sum sumfile     : text summary file

       Text file in which to store the cluster summary. See Summary File Output below.



   --o outid <fmt>   : input with non-clusters set to 0

       File in which to store the surface values after setting the

       non-cluster vertices to zero. Fmt is the format (currently, only

       paint format is supported). Note: make sure to put a ./ in front

       of outputid or else it will attempt to write the output to the

       subject's surf directory.



   --ocn ocnid <fmt> : value is cluster number 

       File in which to store the cluster number of each vertex. This can be

       useful for determining to which cluster a particular vertex

       belongs. It can be viewed as with any other surface value file. Fmt is

       the format (currently, only paint format is supported). Note: make

       sure to put a ./ in front of outputid or else it will attempt to write

       the output to the subject's surf directory.



   --olab outlabelbase  : output clusters as labels 

       Save output clusters as labels. There will be a label file for each

       cluster. The name will be outlabelbase-XXXX.label, where XXXX is the

       4-digit, zero-paded cluster number. The stat field in the label will

       be the value of the input statistic at that vertex.



   --cht chtfile nithr ithrlo ithrhi ithrsign nsthr sthrlo sthrhi



   --xfm xfmfile     : talairach transform (def is talairach.xfm) 

       This is a transform file that is used to compute the Talairach 

       coordinates of a vertex for the summary file. The file must be

       found in subjects_dir/subjectid/transforms. The default is

       talairach.xfm which is based on the MNI atlas (see --fixmni).



     

   --<no>fixmni      : <do not> fix MNI talairach coordinates

       Fix (or do not fix) MNI Talairach coordinates based on Matthew Brett's

       transform. See http://www.mrc-cbu.cam.ac.uk/Imaging/mnispace.html.

       Default is to fix. The user may elect not to fix if the xfm file

       is not talairach.xfm (see --xfm).



   --sd subjects_dir : (default is env SUBJECTS_DIR)

      This allows the user to change the FreeSurfer subjects's directory

      from the command-line. If unspecified, it will be set to the 

      environment variable SUBJECTS_DIR



   --help : answers to ALL your questions
-Line 33:
+Line 122:
-|| volume1 || description ||

|| volume2 || description ||
+   --sum sumfile     : text summary file

   --o outid <fmt>   : input with non-clusters set to 0

   --ocn ocnid <fmt> : value is cluster number 

   --olab labelbase  : output clusters as labels
-Line 36:
+Line 127:
-= Description =

description
+SUMMARY FILE OUTPUT
-Line 39:
+Line 129:
-= Examples =

== Example 1 ==

command foo -i f -o out
+The summary file (the argument of the --sum flag) will contain a 

summary of the result of the clustering as well as a summary of the

conditions under which the clustering was performed. It will list

the clusters (1 to N) along with the maximum value found in the

cluster (Max), the vertex at which this maximum value was found

(VtxMax), the surface area of the cluster (Size), and the Talaiarach

coordinates of the maximum (based on talairach.xfm). A sample 

summary file is shown below.
-Line 43:
+Line 138:
-description
+Cluster Growing Summary (mri_surfcluster)

$Id: mri_surfcluster.c,v 1.13 2004/10/19 23:32:42 greve Exp $

Input :      minsig-0-lh.w

Frame Number:      0

Minimum Threshold: 5

Maximum Threshold: infinity

Threshold Sign:    pos

Area Threshold:    40 mm^2

NClusters          37

Total Cortical Surface Area 115576 (mm^2)

FixMNI = 1
-Line 45:
+Line 150:
-== Example 2 ==

command foo -i f -o out -f fvalue
+ClusterNo   Max  VtxMax  Size(mm^2)   TalX   TalY   TalZ

   1       44.6    6370    636.79    -33.6  -69.8   49.2

   2       40.3   48234    518.50     -2.9  -10.5   62.4

   3       39.5   54239    103.19    -51.1  -13.3   45.3

   4       39.5   55350     47.31    -50.1  -11.0   46.8
-Line 48:
+Line 156:
-description
-Line 51:
+Line 160:
-None
+Currently only supports paint (or w) format for input and output.
-Line 53:
+Line 162:
-= See Also =

["othercommand1"], ["othercommand2"]
-Line 56:
+Line 163:
-= Links =

FreeSurfer, FsFast



= Methods Description =

{{{

description

description

}}}



= References =

["References/Lastname###"]



= Reporting Bugs =

Report bugs to <analysis-bugs@nmr.mgh.harvard.edu>



= Author/s =

JaneSmith