:orphan: .. _ahelp_3dROIMaker: ********** 3dROIMaker ********** .. contents:: :local: | .. code-block:: none ROIMaker, written by PA Taylor (Nov, 2012), part of FATCAT (Taylor & Saad, 2013) in AFNI. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * THE GENERAL PURPOSE of this code is to create a labelled set of ROIs from input data. It was predominantly written with a view of aiding the process of combining functional and tractographic/structural data. Thus, one might input a brain map (or several, as subbricks) of functional parameters (e.g., correlation coefficients or ICA maps of Z-scores), set a value threshold and/or a cluster-volume threshold, and this program will find distinct ROIs in the data and return a map of them, each labelled with an integer. One can also provide a reference map so that, for example, in group studies, each subject would have the same number label for a given region (i.e., the L motor cortex is always labelled with a `2'). In order to be prepared for tractographic application, one can also enlarge the gray matter ROIs so that they intersect with neighboring white matter. One can either specify a number of voxels with which to pad each ROI, and/or input a white matter skeleton (such as could be defined from a segmented T1 image or an FA map) and use this as an additional guide for inflating the GM ROIs. The output of this program can be used directly for guiding tractography, such as with 3dTrackID. If an input dataset ('-inset INSET') already contains integer delineation, such as using a parcellation method, then you can preserve these integers *even if the ROIs are contiguous* by using the same set as the reference set (-> '-refset INSET', as well). Otherwise, contiguous blobs defined will likely be given a single integer value in the program. Labeltable functionality is now available. If an input '-refset REFSET' has a labeltable attached, it will also be attached to the output GM and inflated GMI datasets by default (if you don't want to do this, you can use the '-dump_no_labtab' to turn off this functionality). If either no REFSET is input or it doesn't have a labeltable, one will be made from zeropadding the GM and GMI map integer values-- this may not add a lot of information, but it might make for more useful output. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * OUTPUTS: + `GM' map of ROIs :based on value- and volume-thresholding, would correspond most closely to gray matter regions of activation. The values of each voxel are an integer, distinct per ROI. + `GMI' map of ROIs :map of inflated GM ROIs, based on GM map, with the ROIs inflated either by a user-designed number of voxels, or also possibly including information of the WM skeleton (so that inflation is halted after encountering WM). The values of each voxel are the same integers as in the GM map. + RUNNING, need to provide: -inset INSET :3D volume(s) of values, esp. of functionally-derived quantities like correlation values or ICA Z-scores. -thresh MINTHR :threshold for values in INSET, used to great ROI islands from the 3D volume's sea of values. -prefix PREFIX :prefix of output name, with output files being: PREFIX_GM* and PREFIX_GMI* (see `Outputs', above). and can provide: -refset REFSET :3D (or multi-subbrick) volume containing integer values with which to label specific GM ROIs after thresholding. This can be useful to assist in having similar ROIs across a group labelled with the same integer in the output GM and GMI maps. If an INSET ROI has no corresponding REFSET label, then the former is marked with an integer greater than the max refset label. If an INSET ROI overlaps with multiple REFSET ROIs, then the former is split amongst the latter-- overlap regions get labelled first, and then REFSET labels grow to cover the INSET ROI in question. NB: it is possible to utilize negative-valued ROIs (voxels =-1) to represent NOT- regions for tracking, for example. -volthr MINVOL :integer number representing minimum size a cluster of voxels must have in order to remain a GM ROI after the values have been thresholded. Number might be estimated with 3dAlphaSim, or otherwise, to reduce number of `noisy' clusters. -only_some_top N :after '-volthr' but before any ref-matching or inflating, one can restrict each found region to keep only N voxels with the highest inset values. (If an ROI has it's now default behavior to have facewise-only neighbors, in order to be consistent with the default usage of the clusterize function in the AFNI window. -neigh_face_edge :can loosen the definition of neighbors, so that voxels can share a face or an edge in order to be grouped into same ROI (AFNI default is that neighbors share at least one edge). -neigh_upto_vert :can loosen the definition of neighbors, so that voxels can be grouped into the same ROI if they share at least one vertex (see above for default). -nifti :switch to output *.nii.gz GM and GMI files (default format is BRIK/HEAD). -preinfl_inset PSET :as a possible use, one might want to start with a WM ROI, inflate it to find the nearest GM, then expand that GM, and subtract away the WM+CSF parts. Requires use of a '-wm_skel' and '-skel_stop', and replaces using '-inset'. The size of initial expansion through WM is entered using the option below; then WM+CSF is subtracted. The *_GM+orig* set is returned. In the *_GMI+orig* set, the number of voxels expanded in GM is set using the '-inflate' value (WM+CSF is subtracted again before output). -preinfl_inflate PN :number of voxels for initial inflation of PSET. -dump_no_labtab :switch for turning off labeltable attachment to the output GM and GMI files (from either from a '-refset REFSET' or from automatic generation from integer labels. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + EXAMPLE: 3dROIMaker \ -inset CORR_VALUES+orig. \ -thresh 0.6 \ -prefix ROI_MAP \ -volthr 100 \ -inflate 2 \ -wm_skel WM_T1+orig. \ -skel_stop_strict * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * If you use this program, please reference the introductory/description paper for the FATCAT toolbox: Taylor PA, Saad ZS (2013). FATCAT: (An Efficient) Functional And Tractographic Connectivity Analysis Toolbox. Brain Connectivity 3(5):523-535.