AFNI program: 3dROIMaker

Output of -help


  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 <N voxels, then all would be kept.)
                       This option can result in unconnected pieces.
     -only_conn_top N :similar-ish to preceding option, but instead of just
                       selecting only N max voxels, do the following
                       algorithm: start the ROI with the peak voxel; search
                       the ROI's neighbors for the highest value; add that
                       voxel to the ROI; continue until either the ROI has 
                       reached N voxels or whole region has been  added.
                       The returned ROI is contiguous and 'locally' maximal
                       but not necessarily globally so within the original
                       volume.
     -inflate  N_INFL :number of voxels which with to pad each found ROI in
                       order to turn GM ROIs into inflated (GMI) ROIs.
                       ROIs won't overlap with each other, and a WM skeleton
                       can also be input to keep ROIs from expanding through
                       a large amount of WM ~artificially (see below).
     -trim_off_wm     :switch to trim the INSET to exclude voxels in WM,
                       by excluding those which overlap an input WM
                       skeleton, SKEL (see `-wm_skel', below; to trim off
                       CSF, see separate `-csf_skel').  NB: trimming is done
                       before volume thresholding the ROIs, so fewer ROIs
                       might pass, or some input regions might be split
                       apart creating a greater number of regions.
     -wm_skel  SKEL   :3D volume containing info of WM, as might be defined
                       from an FA map or anatomical segmentation.  Can be
                       to guide ROI inflation with `-skel_stop'.
     -skel_thr THR    :if the skeleton is not a mask, one can put in a 
                       threshold value for it, such as having THR=0.2 if 
                       SKEL were a FA map.
     -skel_stop       :switch to stop inflation at locations which are 
                       already on WM skeleton (default: off; and need
                       `-wm_skel' to be able to use).
   -skel_stop_strict  :similar to '-skel_stop', but this also does not
                       allow any inflation *into* the skel-region.  The
                       '-skel_stop' let's the inflation go one layer
                       *into* the skel-region, so this is stricter. This
                       option might be my preference these days.
     -csf_skel CSF_SK :similar to SKEL, a 3D volume containing info of CSF.
                       NB: however, with CSF_SK, info must just be a binary
                       mask already, and it will only be applied in trimming
                       procedure (no affect on inflation); if input, INSET
                       is automatically trimmed of CSF, independent of
                       using `-trim_off_wm'.  Again, trimming done before
                       volume thresholding, so may decrease/separate regions
                       (though, that may be useful/more physiological).
     -mask   MASK     :can include a mask within which to apply threshold.
                       Otherwise, data should be masked already. Guess this
                       would be useful if the MINTHR were a negative value.
                       It's also useful to ensure that the output *_GMI*
                       ROI masks stay within the brain-- this probably won't
                       often matter too much.
                       For an N-brick inset, one can input an N- or 1-brick
                       mask.
    -neigh_face_only  : **DEPRECATED SWITCH** -> 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.
____________________________________________________________________________
This page auto-generated on Thu Oct 31 09:42:31 PM EDT 2024