:orphan: .. _ahelp_3dClusterize: ************ 3dClusterize ************ .. contents:: :local: | PURPOSE ======= .. code-block:: none This program is for performing clusterizing: one can perform voxelwise thresholding on a dataset (such as a statistic), and then make a map of remaining clusters of voxels larger than a certain volume. The main output of this program is a single volume dataset showing a map of the cluster ROIs. As of Apr 24, 2020, this program now behaves less (unnecessarily) guardedly when thresholding non-stat volumes. About time, right? This program is specifically meant to reproduce behavior of the muuuch older 3dclust, but this new program: + uses simpler syntax (hopefully); + includes additional clustering behavior such as the '-bisided ...' variety (essentially, two-sided testing where all voxels in a given cluster come from either the left- or right- tail, but not mixed); + a mask (such as the whole brain) can be entered in; + voxelwise thresholds can be input as statistic values or p-values. This program was also written to have simpler/more direct syntax of usage than 3dclust. Some minor options have been carried over for similar behavior, but many of the major option names have been altered. Please read the helps for those below carefully. This program was cobbled together by PA Taylor (NIMH, NIH), but it predominantly uses code written by many legends: RW Cox, BD Ward, MS Beauchamp, ZS Saad, and more. USAGE ===== Input: ++++++ .. code-block:: none + A dataset of one or more bricks + Specify an index of the volume to threshold + Declare a voxelwise threshold, and optionally a cluster-volume threshold + Optionally specify the index an additional 'data' brick + Optionally specify a mask Output: +++++++ .. code-block:: none + A report about the clusters (center of mass, extent, volume, etc.) that can be dumped into a text file. + Optional: A dataset volume containing a map of cluster ROIs (sorted by size) after thresholding (and clusterizing, if specified). That is, a data set where the voxels in the largest cluster all have a value 1, those in the next largest are all 2, etc. + Optional: a cluster-masked version of an input data set. That is, the values of a selected data set (e.g., effect estimate) that fall within a cluster are output unchanged, and those outside a cluster are zeroed. + Optional: a mask. Explanation of 3dClusterize text report: ++++++++++++++++++++++++++++++++++++++++ .. code-block:: none Nvoxel : Number of voxels in the cluster 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, maxIS : 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 * CM values use the absolute value of the voxel values as weights. * The program does not work on complex- or rgb-valued datasets! * 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. * Some summary or 'global' values are placed at the bottoms of report columns, by default. These include the 'global' volume, CM of the combined cluster ROIs, and the mean+SEM of that Pangaea. COMMAND OPTIONS =============== .. code-block:: none -inset III :Load in a dataset III of one or more bricks for thresholding and clusterizing; one can choose to use either just a single sub-brick within it for all operations (e.g., a 'statistics' brick), or to specify an additional sub-brick within it for the actual clusterizing+reporting (after the mask from the thresholding dataset has been applied to it). -mask MMM :Load in a dataset MMM to use as a mask, within which to look for clusters. -mask_from_hdr :If 3dClustSim put an internal attribute into the input dataset that describes a mask, 3dClusterize will use this mask to eliminate voxels before clustering, if you give this option (this is how the AFNI Clusterize GUI works by default). If there is no internal mask in the dataset header, then this doesn't do anything. -out_mask OM :specify that you wanted the utilized mask dumped out as a single volume dataset OM. This is probably only really useful if you are using '-mask_from_hdr'. If not mask option is specified, there will be no output. -ithr j :(required) Uses sub-brick [j] as the threshold source; 'j' can be either an integer *or* a brick_label string. -idat k :Uses sub-brick [k] as the data source (optional); 'k' can be either an integer *or* a brick_label string. If this option is used, thresholding is still done by the 'threshold' dataset, but that threshold map is applied to this 'data' set, which is in turn used for clusterizing and the 'data' set values are used to make the report. If a 'data' dataset is NOT input with '-idat ..', then thresholding, clustering and reporting are all done using the 'threshold' dataset. -1sided SSS TT :Perform one-sided testing. Two arguments are required: SSS -> either 'RIGHT_TAIL' (or 'RIGHT') or 'LEFT_TAIL' (or 'LEFT') to specify which side of the distribution to test. TT -> the threshold value itself. See 'NOTES' below to use a p-value as threshold. -2sided LL RR :Perform two-sided testing. Two arguments are required: LL -> the upper bound of the left tail. RR -> lower bound of the right tail. *NOTE* that in this case, potentially a cluster could be made of both left- and right-tail survivors (e.g., both positive and negative values). For this reason, probably '-bisided ...' is a preferable choice. See 'NOTES' below to use a p-value as threshold. -bisided LL RR :Same as '-2sided ...', except that the tails are tested independently, so a cluster cannot be made of both. See 'NOTES' below to use a p-value as threshold. -within_range AA BB :Perform a kind of clustering where a different kind of thresholding is first performed, compared to the above cases; here, one keeps values within the range [AA, BB], INSTEAD of keeping values on the tails. Is this useful? Who knows, but it exists. See 'NOTES' below to use a p-value as threshold. -NN {1|2|3} :Necessary option to specify how many neighbors a voxel has; one MUST put one of 1, 2 or 3 after it: 1 -> 6 facewise neighbors 2 -> 18 face+edgewise neighbors 3 -> 26 face+edge+cornerwise neighbors If using 3dClustSim (or any other method), make sure that this NN value matches what was used there. (In many AFNI programs, NN=1 is a default choice, but BE SURE YOURSELF!) -clust_nvox M :specify the minimum cluster size in terms of number of voxels M (such as output by 3dClustSim). -clust_vol V :specify the minimum cluster size in terms of volume V, in microliters (requires knowing the voxel size). Probably '-clust_nvox ...' is more useful. -pref_map PPP :The prefix/filename of the output map of cluster ROIs. The 'map' shows each cluster as a set of voxels with the same integer. The clusters are ordered by size, so the largest cluster is made up of 1s, the next largest of 2s, etc. (def: no map of clusters output). -pref_dat DDD :Including this option instructs the program to output a cluster-masked version of the 'data' volume specified by the '-idat ..' index. That is, only data values within the cluster ROIs are included in the output volume. Requires specifying '-idat ..'. (def: no cluster-masked dataset output). -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. -summarize :Write out only the total nonzero voxel count and volume for each dataset -nosum :Suppress printout of the totals -quiet :Suppress all non-essential output -outvol_if_no_clust: flag to still output an (empty) vol if no clusters are found. Even in this case, no report is is produced if no clusters are found. This option is likely used for some scripting scenarios; also, the user would still need to specify '-pref_* ...' options as above in order to output any volumes with this opt. (def: no volumes output if no clusters found). -orient OOO :in the output report table, make the coordinate order be 'OOO' (def: RAI, the DICOM standard); alternatively, one could set the environment variable AFNI_ORIENT (see the file README.environment). NB: this only affects the coordinate orientation in the *text table*; the dset orientation of the output cluster maps and other volumetric data will match that of the input dataset. -abs_table_data :(new, from Apr 29, 2021) Use the absolute value of voxel intensities (not the raw values) for calculation of the mean and Standard Error of the Mean (SEM) in the report table. Prior to the cited date, this was default behavior (with '-noabs' switching out of it) but no longer. ### -noabs :(as of Apr 29, 2021, this option is no longer needed) Previously this option switched from using default absolute values of voxel intensities for calculation of the mean and Standard Error of the Mean (SEM). But this has now changed, and the default is to just use the signed values themselves; this option will not cause an error, but is not needed. See '-abs_table_data' for reporting abs values. -binary :This turns the output map of cluster ROIs into a binary (0 or 1) mask, rather than a cluster-index mask. If no clusters are found, the mask is not written! (def: each cluster has separate values) NOTES ===== Saving the text report ++++++++++++++++++++++ .. code-block:: none To save the text file report, use the redirect '>' after the 3dClusterize command and dump the text into a separate file of your own naming. Using p-values as thresholds for statistic volumes ++++++++++++++++++++++++++++++++++++++++++++++++++ .. code-block:: none By default, numbers entered as voxelwise thresholds are assumed to be appropriate statistic values that you have calculated for your desired significance (e.g., using p2dsetstat). HOWEVER, if you just want to enter p-values and have the program do the conversion work for you, then do as follows: prepend 'p=' to your threshold number. - For one-sided tests, the *_TAIL specification is still used, so in either case the p-value just represents the area in the statistical distribution's tail (i.e., you don't have to worry about doing '1-p'). Examples: -1sided RIGHT_TAIL p=0.005 -1sided LEFT_TAIL p=0.001 - For the two-sided/bi-sided tests, the a single p-value is entered to represent the total area under both tails in the statistical distribution, which are assumed to be symmetric. Examples: -bisided p=0.001 -2sided p=0.005 If you want asymmetric tails, you will have to enter both threshold values as statistic values (NB: you could use p2dsetstat to convert each desired p-value to a statistic, and then put in those stat values to this program). You will probably NEED to have negative signs for the cases of '-1sided LEFT_TAIL ..', and for the first entries of '-bisided ..' or '-2sided ..'. You cannot mix p-values and statistic values (for two-sided things, enter either the single p-value or both stats). You cannot use this internal p-to-stat conversion if the volume you are thresholding is not recognized as a stat. Performing appropriate testing ++++++++++++++++++++++++++++++ .. code-block:: none Don't use a pair of one-sided tests when you *should* be using a two-sided test! EXAMPLES ======== .. code-block:: none 1. Take an output of FMRI testing (e.g., from afni_proc.py), whose [1] brick contains the effect estimate from a statistical model and whose [2] brick contains the associated statistic; use the results of 3dClustSim run with NN=1 (here, a cluster threshold volume of 157 voxels) and perform one-sided testing with a threshold at an appropriate value (here, 3.313). 3dClusterize \ -inset stats.FT+tlrc. \ -ithr 2 \ -idat 1 \ -mask mask_group+tlrc. \ -NN 1 \ -1sided RIGHT_TAIL 3.313 \ -clust_nvox 157 \ -pref_map ClusterMap 2. The same as Ex. 1, but using bisided testing (two sided testing where the results of each tail can't be joined into the same cluster). Note, the tail thresholds do NOT have to be symmetric (but often they are). Also, here we output the cluster-masked 'data' volume. 3dClusterize \ -inset stats.FT+tlrc. \ -ithr 2 \ -idat 1 \ -mask mask_group+tlrc. \ -NN 1 \ -bisided -3.313 3.313 \ -clust_nvox 157 \ -pref_map ClusterMap \ -pref_dat ClusterEffEst 3. The same as Ex. 2, but specifying a p-value to set the voxelwise thresholds (in this case, tails DO have to be symmetric). 3dClusterize \ -inset stats.FT+tlrc. \ -ithr 2 \ -idat 1 \ -mask mask_group+tlrc. \ -NN 1 \ -bisided p=0.001 \ -clust_nvox 157 \ -pref_map ClusterMap \ -pref_dat ClusterEffEst 4. Threshold a non-stat dset. 3dClusterize \ -inset anat+orig \ -ithr 0 \ -idat 0 \ -NN 1 \ -within_range 500 1000 \ -clust_nvox 100 \ -pref_map ClusterMap \ -pref_dat ClusterEffEst