AFNI program: 3dclust

Output of -help




Program: 3dclust 
Author:  RW Cox et alii 
Date:    12 Jul 2017 

3dclust - performs simple-minded cluster detection in 3D datasets       

         *** PLEASE NOTE THAT THE NEWER PROGRAM 3dClusterize ***
         *** IS BETTER AND YOU SHOULD USE THAT FROM NOW ON!! ***
                                                                        
     This program can be used to find clusters of 'active' voxels and   
     print out a report about them.                                     
      * 'Active' refers to nonzero voxels that survive the threshold    
         that you (the user) have specified                             
      * Clusters are defined by a connectivity radius parameter 'rmm'   
        *OR*
        Clusters are defined by how close neighboring voxels must
        be in the 3D grid:
          first nearest neighbors  (-NN1)
          second nearest neighbors (-NN2)
          third nearest neighbors  (-NN3)
                                                                        
      Note: by default, this program clusters on the absolute values    
            of the voxels                                               
----------------------------------------------------------------------- 
Usage:
                                                                        
   3dclust [editing options] [other options] rmm vmul dset ...          
                                                                        
 *OR*
                                                                        
   3dclust [editing options] -NNx dset ...
     where '-NNx' is one of '-NN1' or '-NN2' or '-NN3':
      -NN1 == 1st nearest-neighbor (faces touching) clustering
      -NN2 == 2nd nearest-neighbor (edges touching) clustering
      -NN2 == 3rd nearest-neighbor (corners touching) clustering
     Optionally, you can put an integer after the '-NNx' option, to
     indicate the minimum number of voxels to allow in a cluster;
     for example: -NN2 60
----------------------------------------------------------------------- 
Examples:                                                               
---------                                                               
                                                                        
    3dclust         -1clip   0.3  5 2000 func+orig'[1]'                 
    3dclust -1noneg -1thresh 0.3  5 2000 func+orig'[1]'                 
    3dclust -1noneg -1thresh 0.3  5 2000 func+orig'[1]' func+orig'[3]   
                                                                        
    3dclust -noabs  -1clip 0.5   -dxyz=1  1  10 func+orig'[1]'          
    3dclust -noabs  -1clip 0.5            5 700 func+orig'[1]'          
                                                                        
    3dclust -noabs  -2clip 0 999 -dxyz=1 1  10 func+orig'[1]'           
                                                                        
    3dclust                   -1clip 0.3  5 3000 func+orig'[1]'         
    3dclust -quiet            -1clip 0.3  5 3000 func+orig'[1]'         
    3dclust -summarize -quiet -1clip 0.3  5 3000 func+orig'[1]'         
    3dclust -1Dformat         -1clip 0.3  5 3000 func+orig'[1]' > out.1D
----------------------------------------------------------------------- 
                                                                        
Arguments (must be included on command line):                           
---------                                                               
                                                                        
THE OLD WAY TO SPECIFY THE TYPE OF CLUSTERING

   rmm            : cluster connection radius (in millimeters).         
                    All nonzero voxels closer than rmm millimeters      
                    (center-to-center distance) to the given voxel are  
                    included in the cluster.                            
                     * If rmm = 0, then clusters are defined by nearest-
                       neighbor connectivity                            
                                                                        
   vmul           : minimum cluster volume (micro-liters)               
                    i.e., determines the size of the volume cluster.    
                     * If vmul = 0, then all clusters are kept.         
                     * If vmul < 0, then the absolute vmul is the minimum
                          number of voxels allowed in a cluster.        

  If you do not use one of the '-NNx' options, you must give the
  numbers for rmm and vmul just before the input dataset name(s)

THE NEW WAY TO SPECIFY TYPE OF CLUSTERING [13 Jul 2017]

   -NN1 or -NN2 or -NN3

  If you use one of these '-NNx' options, you do NOT give the rmm
  and vmul values.  Instead, after all the options that start with '-',
  you just give the input dataset name(s).
  If you want to set a minimum cluster size using '-NNx', put the minimum
  voxel count immediately after, as in '-NN3 100'.

FOLLOWED BY ONE (or more) DATASETS
                                                                        
   dset           : input dataset (more than one allowed, but only the  
                    first sub-brick of the dataset)                     
                                                                        
 The results are sent to standard output (i.e., the screen):            
 if you want to save them in a file, then use redirection, as in

   3dclust -1thresh 0.4 -NN2 Elvis.nii'[1]' > Elvis.clust.txt
                                                                        
----------------------------------------------------------------------- 
                                                                        
Options:                                                                
-------                                                                 
                                                                        
  Editing options are as in 3dmerge (see 3dmerge -help)                 
  (including -1thresh, -1dindex, -1tindex, -dxyz=1 options)             

  -NN1        => described earlier;
  -NN2        => replaces the use of 'rmm' to specify the
  -NN3        => clustering method (vmul is set to 2 voxels)
                                                                        
  -noabs      => Use the signed voxel intensities (not the absolute     
                 value) for calculation of the mean and Standard        
                 Error of the Mean (SEM)                                
                                                                        
  -summarize  => Write out only the total nonzero voxel                 
                 count and volume for each dataset                      
                                                                        
  -nosum      => Suppress printout of the totals                        
                                                                        
  -verb       => Print out a progress report (to stderr)                
                 as the computations proceed                            
                                                                        
  -1Dformat   => Write output in 1D format (now default). You can       
                 redirect the output to a .1D file and use the file     
                 as input to whereami for obtaining Atlas-based         
                 information on cluster locations.                      
                 See whereami -help for more info.                      
 -no_1Dformat => Do not write output in 1D format.                      
                                                                        
  -quiet      => Suppress all non-essential output                      
                                                                        
  -mni        => If the input dataset has the +tlrc view, this option   
                 will transform the output xyz-coordinates from TLRC to 
                 MNI space.
                                                                        
           N.B.0: Only use this option if the dataset is in Talairach   
                  space, NOT when it is already in MNI space.           
           N.B.1: The MNI template brain is about 5 mm higher (in S),   
                  10 mm lower (in I), 5 mm longer (in PA), and tilted   
                  about 3 degrees backwards, relative to the Talairach- 
                  Tournoux Atlas brain.  For more details, see, e.g.:   
                  https://imaging.mrc-cbu.cam.ac.uk/imaging/MniTalairach
           N.B.2: If the input dataset does not have the +tlrc view,    
                  then the only effect is to flip the output coordinates
                  to the 'LPI' (neuroscience) orientation, as if you    
                  gave the '-orient LPI' option.)                       
                                                                        
  -isovalue   => Clusters will be formed only from contiguous (in the   
                 rmm sense) voxels that also have the same value.       
                                                                        
           N.B.:  The normal method is to cluster all contiguous        
                  nonzero voxels together.                              
                                                                        
  -isomerge   => Clusters will be formed from each distinct value       
                 in the dataset; spatial contiguity will not be         
                 used (but you still have to supply rmm and vmul        
                 on the command line).                                  
                                                                        
           N.B.:  'Clusters' formed this way may well have components   
                   that are widely separated!                           

  -inmask  =>    If 3dClustSim put an internal attribute into the       
                 input dataset that describes a mask, 3dclust will      
                 use this mask to eliminate voxels before clustering,   
                 if you give this option.  '-inmask' is how the AFNI    
                 AFNI Clusterize GUI works by default.                  
                   [If there is no internal mask in the dataset]        
                   [header, then '-inmask' doesn't do anything.]        

           N.B.: The usual way for 3dClustSim to have put this internal 
                 mask into a functional dataset is via afni_proc.py.    
                                                                        
  -prefix ppp => Write a new dataset that is a copy of the              
                 input, but with all voxels not in a cluster            
                 set to zero; the new dataset's prefix is 'ppp'         
                                                                        
           N.B.:  Use of the -prefix option only affects the            
                  first input dataset.                                  

  -savemask q => Write a new dataset that is an ordered mask, such      
                 that the largest cluster is labeled '1', the next      
                 largest '2' and so forth.  Should be the same as       
                 '3dmerge -1clust_order' or Clusterize 'SaveMsk'.       
  -binary     => This turns the output of '-savemask' into a binary     
                 (0 or 1) mask, rather than a cluster-index mask.       
          **-->> If no clusters are found, the mask is not written!     

----------------------------------------------------------------------- 
 N.B.: 'N.B.' is short for 'Nota Bene', Latin for 'Note Well';          
       also see http://en.wikipedia.org/wiki/Nota_bene                  
----------------------------------------------------------------------- 
                                                                        
E.g., 3dclust -1clip 0.3  5  3000 func+orig'[1]'                        
                                                                        
  The above command tells 3dclust to find potential cluster volumes for 
  dataset func+orig, sub-brick #1, where the threshold has been set     
  to 0.3 (i.e., ignore voxels with activation threshold >0.3 or <-0.3). 
  Voxels must be no more than 5 mm apart, and the cluster volume        
  must be at least 3000 micro-liters in size.                           
                                                                        
Explanation of 3dclust Output:                                          
-----------------------------                                           
                                                                        
   Volume       : Volume that makes up the cluster, in microliters (mm^3)
                  (or the number of voxels, if -dxyz=1 is given)        
                                                                        
   CM RL        : Center of mass (CM) for the cluster in the Right-Left 
                  direction (i.e., the coordinates for the CM)          
                                                                        
   CM AP        : Center of mass for the cluster in the                 
                  Anterior-Posterior direction                          
                                                                        
   CM IS        : Center of mass for the cluster in the                 
                  Inferior-Superior direction                           
                                                                        
   minRL, maxRL : Bounding box for the cluster, min and max             
                  coordinates in the Right-Left direction               
                                                                        
   minAP, maxAP : Min and max coordinates in the Anterior-Posterior     
                  direction of the volume cluster                       
                                                                        
   minIS, max IS: Min and max coordinates in the Inferior-Superior      
                  direction of the volume cluster                       
                                                                        
   Mean         : Mean value for the volume cluster                     
                                                                        
   SEM          : Standard Error of the Mean for the volume cluster     
                                                                        
   Max Int      : Maximum Intensity value for the volume cluster        
                                                                        
   MI RL        : Coordinate of the Maximum Intensity value in the      
                  Right-Left direction of the volume cluster            
                                                                        
   MI AP        : Coordinate of the Maximum Intensity value in the      
                  Anterior-Posterior direction of the volume cluster    
                                                                        
   MI IS        : Coordinate of the Maximum Intensity value in the      
                  Inferior-Superior direction of the volume cluster     
----------------------------------------------------------------------- 
                                                                        
Nota Bene:                                                              
                                                                        
   * The program does not work on complex- or rgb-valued datasets!      
                                                                        
   * Using the -1noneg option is strongly recommended!                  
                                                                        
   * 3D+time datasets are allowed, but only if you use the              
     -1tindex and -1dindex options.                                     
                                                                        
   * Bucket datasets are allowed, but you will almost certainly         
     want to use the -1tindex and -1dindex options with these.          
                                                                        
   * SEM values are not realistic for interpolated data sets!           
     A ROUGH correction is to multiply the SEM of the interpolated      
     data set by the square root of the number of interpolated          
     voxels per original voxel.                                         
                                                                        
   * If you use -dxyz=1, then rmm should be given in terms of           
     voxel edges (not mm) and vmul should be given in terms of          
     voxel counts (not microliters).  Thus, to connect to only          
     3D nearest neighbors and keep clusters of 10 voxels or more,       
     use something like '3dclust -dxyz=1 1.01 10 dset+orig'.            
     In the report, 'Volume' will be voxel count, but the rest of       
     the coordinate dependent information will be in actual xyz         
     millimeters.                                                       
                                                                        
  * The default coordinate output order is DICOM.  If you prefer        
    the SPM coordinate order, use the option '-orient LPI' or           
    set the environment variable AFNI_ORIENT to 'LPI'.  For more        
    information, see file README.environment.                           

++ Compile date = Mar 24 2024 {AFNI_24.0.17:linux_ubuntu_16_64}


This page auto-generated on Sun Mar 24 22:21:26 EDT 2024