7.4. 3dROIMaker: making (networks of) ROIs¶
There are many contexts for making one or more regions of interest (ROIs) in MRI:
forming functional (GM) networks,
preparing targets (bordering on WM) for tractography,
preparing theoretical studies,
parcellating the whole brain or cortex for connectomics,
and more. In each case, the details of the ROI-making procedure depend on what inputs are available and on what the resulting analysis will be. However, the primary purpose of the process is typically the same: to delineate brain regions which are as physiologically meaningful and relevant as possible.
3dROIMaker is designed to be useful in extracting
regions from subject data itself, with the ability to combine
information from several modalities. Reference templates may also be
included for extra guidance. Given the prominence of networks in
modern brain research, the focus of this program is to allow for
(hopefully) easy regionalization of data maps, such as listed
3dROIMaker can also be applied to multibrick data sets
simultaneously, as several other AFNI programs (e.g.,
3dTrackID) can analyze networks simultaneously, with each one
defined as a separate brick.
For historical reasons, the terminology of several
option names and descriptions comes from a scenario where the input
image is FMRI-related and one is looking to extract GM ROIs, while
perhaps using CSF and WM to eliminate voxels and/or inform ROI
inflation. However, the functionality (masking, thresholding, etc.)
can be applied generally to any type of input and supporting
data. Hopefully this naming convention does not create confusion.
3dROIMaker can be used to:
threshold input images, in order to define a set of individual regions, which are sometimes colloquially referred to as blobs (
thresholding can be further refined to keep a set of maximal-valued voxels per ROI (
subtract away other maps (e.g., tissue-defined skeletons) from the input images:
subtraction can be done before or after thresholding the input image (
an other map can itself be thresholded from the command line (
eliminate blobs based on a volume threshold (
uniformly inflate blobs (
for a given network (brick) of regions, the epansion is done layer by layer, aiming to limit biases among growing ROIs;
inflation can be controlled to stop at boundaries of guiding maps (
-skel_stopor the newer
numbering of thresholded ROIs can be guided by a reference set, to keep similar regions in different data sets having the same integer or text labels (
perform ‘preinflation’, which was designed for a special case of*starting* with an input WM map, then expanding to GM and subtracting away the WM, and finally using the generated GM ROIs for further expansion, thresholding, etc. (
Each ROI is defined as a set of voxels with a given nonzero integer
value within dataset volume (what is referred to as its integer
label). Typically, the integers are >0, though for tractography
purposes, negative voxel values show where anti-masks that exclude
tracts are located. Additionally, this information can be combined
with (NIML-formatted) labeltables to allow for text-labels to be
associated with each ROI. These labeltable names can track through to
further analysis programs, such as
When ROIs are being inflated, they will not write over other ROIs in the same brick. Thus, a network of ROIs should always be inflated while in the same brick, for greater consistency, rather than inflated individually and ‘summed’ together.
In general, it should be possible to do much of the ROI processing (inflating, threshold, etc.) with all the network ROIs in a single brick, rather than individually. This should hopefully lead to both greater time-saving, as well as consistency within the output. If the below notes, examples or existing Message Board posts don’t help to keep analysis scripts short, then please enquire before spending ages on complicated pipelines.
3dROIMaker-produced output files to another space (for example, from standard to DTI), then one can make sure that the integer-nature of the files is preserved when applying the transform. One can use the
-interp NNoption when applying linear transforms (
3dAllineate), or likely
-ainterp NNafter nonlinear transforms (
If the input dataset already has integer labels that the user wishes to preserve, then one should enter the same dataset as a reference set:
3dROIMaker -inset FILE_A -refset FILE_A ...
This action will preserve labels even if some of the ROIs are contiguous, such as is likely to occur in the case of a Connectome Parcellation.
When an aim of using 3dROIMaker is to produce target regions for tractography, then the inflation should be performed in diffusion space, where one can use the actual WM proxy map (such as FA>0.2) to delimit inflation.
This may lead to scenarios where multiple iterations of 3dROIMaker are called for. For example, one may threshold a group map of functional data and get rid of tiny/noisy regions, and then transform the networks to each individual’s diffusion space, in order to perform the ROI inflation there (as well as the eventual tractography).
Each input brick in an
-inset * file is treated as a separate
network in terms of expansion, skeleton subtraction, and default
If an input file has N bricks, then an input
-refset * file (for
applying user-defined ROI integer labels) can have either 1 or N
bricks. In the former case the same integer labels are applied to
each brick, and in the latter the ith brick in the reference set is
applied to the ith brick in the input set.
Currently, when an input dat set has a single NIML-formatted labeltable (*.niml.lt) attached to it, the labels are applied to each brick. That is, there are not subsets of labels applicable to different bricks.
An important consideration in determining ROIs is how a neighborhood is defined at a voxel level. For most applications, these are symmetric around a given voxel (though, near the edge of a dataset or mask it may be clipped). The categories are typically described in terms of what basic features must be shared in order to make two voxels neighbors: nodes, edges or faces.
Different software packages have different default definitions of a voxel neighborhood. The three main categories are:
face only (6 neighboring voxels);
face+edge (18 neighboring voxels);
face+edge+node (26 neighboring voxels).
Depictions of ways of defining voxel neighborhoods are shown below; listed for each are examples of basic software distributions using the given method as a typical default:
For example, the default in each of AFNI’s
3dClustSim and the
Clusterize function is a face-wise neighbor definition. The same is
currently true for
3dROIMaker, and one can use other methods by
for face+edge (18 neighbors), use
for face+edge+node (26 neighbors), use
Even though an overall software distribution has a general
method for defining voxel neighborhoods, individual programs
themselves may differ or vary over time. For example
3dROIMaker started life using a face+edge neighborhood
default. Therefore, it is advisable to always check a given
program for notes regarding neighborhoods.
As a slightly related appendix to this discussion, we note that some
programs define ROI neighborhoods in terms of a ‘cluster radius’
(generally in units of ‘mm’). In such a system, when measuring from
the center of the focal voxel, all voxels whose centers are within the
specified radial distance are included in the neighborhood. For
instance, AFNI’s AlphaSim does this with the
-rmm * option. In
the case of isotropic voxels (all edges of the same length, L), this
system meshes with the above by setting the radius to be:
1.1L, for face only;
1.7L, for face+edge;
1.9L, for face+edge+node.
These values are not exclusive, but they should work fine.
For this example, the input data is a seed-based correlation map (Pearson r values) of resting state FMRI data, where the seed voxel was located in the posterior cingulate cortex, a known part of the default mode network. We look at a few ways of including tissue information from anatomical/structural data, namely that of a T1-weighted (T1w) image and DTI parameter maps, when parcellating a dataset into a network of ROIs.
There are several ways of doing using the T1w and DTI data, greatly dependent on things like the user’s goals for final analyses, quality of data, etc. One may be interested in many things, such as:
functional correlation matrices among ROIs with high functional connectivity (which is usually defined as r> some threshold); or,
further restriction of the functional ROI voxels to be in a GM mask; and/or
inflation of these GM ROIs to the nearest WM for tractography; and then likely
restriction of the inflation using tissue information to find only associated ‘local’ WM.
Here, the T1w image has been skull-stripped and segmented into major tissue types (CSF, GM and WM). Because some of the goals might include linking the functional data to tractographic analysis, both the functional correlation map and the T1w tissue masks have been mapped to native diffusion space. Thresholded functional correlation maps are shown in the following figure, overlaid on diffusion (first column) and tissue segmentation masks (second column; WM, CSF and GM in order of decreasing brightness):
Correlation (r>0.4) map on b=0
Correlation (r>0.4) map on tissue masks
In all the following cases, the same root is used for the
3dROIMaker command, which employs a correlation map thresholding
of r>0.4, a volume thresholding of 100 voxels, an inflation of two
voxels, default neighborhood definitions (now AFNI-standard, facewise
voxel neighbors), and the whole brain diffusion mask:
3dROIMaker \ -inset SEED_CORRMAP+orig. \ -thresh 0.4 \ -volthr 100 \ -mask mask_DWI+orig. \ -inflate 2 \ ...
where possible continuations are given by the following variations:
CSF must be input as a mask (i.e., a volume of all zeros or ones), and it does not restrict inflation. WM may be input as a map, whose values can be thresholded (-skel_thr *) and used to restrict inflation (-skel_stop, -skel_stop_strict). Any WM and CSF skeletons can be cut away from the input map (-trim_off_wm) before regionalizing.
Use T1w-WM to stop inflation:
... -wm_skel tiss_WM_in_B0.nii.gz \ -skel_thr 0.5 \ -skel_stop \ -prefix ROIMADE_WM
*_GM+orig* images (10 ROIs)
Use T1w-WM first to trim away voxels and then to stop inflation:
... -wm_skel tiss_WM_in_B0.nii.gz \ -skel_thr 0.5 \ -skel_stop \ -trim_off_wm \ -prefix ROIMADE_WM_TRIM
*_GM+orig* images (9 ROIs)
Start by trimming away T1w-WM and -CSF, and use the former to stop inflation:
... -wm_skel tiss_WM_in_B0.nii.gz \ -skel_thr 0.5 \ -skel_stop \ -csf_skel tiss_CSF_in_B0.nii.gz \ -trim_off_wm \ -prefix ROIMADE_WMCSF_TRIM
*_GM+orig* images (8 ROIs)
Start by trimming away ‘FA>0.2’ WM, and then use it to stop inflation:
... -wm_skel DTI/DT_FA+orig \ -skel_thr 0.2 \ -skel_stop \ -trim_off_wm \ -prefix ROIMADE_FA02_TRIM
*_GM+orig* images (9 ROIs)
Don’t trim ‘FA>0.2’ WM, but use it to stop inflation:
... -wm_skel DTI/DT_FA+orig \ -skel_thr 0.2 \ -skel_stop \ -prefix ROIMADE_FA02
*_GM+orig* images (10 ROIs)
And, finally, use no tissue information, either for subtraction or inflation:
*_GM+orig* images (10 ROIs)
This is a case where the dataset being input to
has the following properties:
it is already parcellated into integer-labelled ROIs;
its ROIs are contiguous;
a labeltable is attached.
The FATCAT_DEMO contains an example of such a set (output from
FreeSurfer) in the script
Such a dataset is shown here:
(Sagittal) WB parcellation overlaid on T1w anatomical scan. Each color shows a different ROI (ROI_i256 colormap).
(Axial) WB parcellation overlaid on T1w anatomical scan.
3dcalc was used to select ROIs with an integer above a
maximum to select only cortical GM regions. The following images show
the remaining ROIs as colored ROIs; all the ROIs are in a single
brick. In the first and second rows the individual ROIs are shown
overlaid on a T1w anatomical image and a FA>0.2 mask, respectively:
In the third row the input ROIs have been inflated by 1 voxel. Note
that the output contains several individual ROIs, even though the
input data contains several contiguous, nonzero voxels. Moreover, the
output data set has retained the numerical labeling of the input (as
denoted by the local color consistency). Both of these features are a
result of utilizing the same
-inset * file as a
-refset * as
3dROIMaker \ -inset ROI_MAP \ -refset ROI_MAP \ -wm_skel FA_MAP \ -skel_thr 0.2 \ -skel_stop \ -inflate 1 \ -prefix o.ROIS
Volume thresholding was not necessary in this case. Here, the WM mask, defined as where the FA_MAP contained values were >0.2, was used only for controlling expansion of the ROIs, and not subtracted away.