:orphan: .. _ahelp_3dclust: ******* 3dclust ******* .. contents:: :local: | .. code-block:: none 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 = Apr 18 2024 {AFNI_24.1.03:linux_ubuntu_16_64}