.. _Making_ROIs:
*****************************************
**3dROIMaker: making (networks of) ROIs**
*****************************************
.. contents:: :local:
Overview
========
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.
The program ``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
about. ``3dROIMaker`` can also be applied to multibrick data sets
simultaneously, as several other AFNI programs (e.g., ``3dNetCorr``
and ``3dTrackID``) can analyze networks simultaneously, with each one
defined as a separate brick.
|
Operation
=========
For historical reasons, the terminology of several ``3dROIMaker``
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.
Broadly, ``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*
(``-thresh *``):
* thresholding can be further refined to keep a set of
maximal-valued voxels per ROI (``-only_some_top *``);
* subtract away other maps (e.g., tissue-defined skeletons) from the
input images:
* subtraction can be done before or after thresholding the input
image (``-csf_skel *``, ``-wm_skel *``, ``-trim_off_wm``);
* an other map can itself be thresholded from the command line
(``-skel_thr *``);
* eliminate blobs based on a volume threshold (``-volthr *``);
* uniformly inflate blobs (``-inflate *``):
* 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_stop`` or the newer ``-skel_stop_strict``).
* 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 (``-refset *``);
* 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. (``-preinfl_inset *``,
``-preinfl_inflate *``)
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 ``3dNetCorr`` and ``3dTrackID``.
**Important notes**
-------------------
#. 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.
#. If mapping ``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 NN`` option when applying
linear transforms (``3dAllineate``), or likely ``-ainterp NN``
after nonlinear transforms (``3dNwarpApply`` following
``3dQwarp``).
#. 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
:ref:`ROI_Example_Connectome`.
#. 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).
|
Multiple bricks and multiple networks
-------------------------------------
Each input brick in an ``-inset *`` file is treated as a separate
network in terms of expansion, skeleton subtraction, and default
integer labeling.
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 *i*\ th brick in the reference set is
applied to the *i*\ th 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.
.. _ROI_info_Neighbors:
Getting to know your neighbors
------------------------------
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:
.. figure:: media/ROIS/ROI_neigh_img.png
:width: 80%
:align: center
:name: media/ROIS/ROI_neigh_img.png
*Basic voxel terminology, and its use in defining three standard,
symmetric (nearest-)neighborhoods for an individual voxel. The
central voxel is darkened, with each type of neighborhood colored
in a 3D, high-tec, separated image.* :ref:`(link)`
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
implementing switches:
* for face+edge (18 neighbors), use ``-neigh_face_edge``;
* for face+edge+node (26 neighbors), use ``-neigh_upto_vert``.
.. note:: 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.1\ *L*, for face only;
* 1.7\ *L*, for face+edge;
* 1.9\ *L*, for face+edge+node.
These values are not exclusive, but they should work fine.
|
Using anatomical tissues and diffusion maps
===========================================
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):
.. list-table::
:header-rows: 1
:widths: 50 50
* - Correlation (*r*>0.4) map on *b*\=0
- Correlation (*r*>0.4) map on tissue masks
* - .. image:: media/ROIS_EX2/ax_corr04_on_b0.png
:width: 100%
- .. image:: media/ROIS_EX2/ax_corr04_on_tiss.png
:width: 100%
* - .. image:: media/ROIS_EX2/sag_corr04_on_b0.png
:width: 100%
- .. image:: media/ROIS_EX2/sag_corr04_on_tiss.png
:width: 100%
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:
.. note:: 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
.. list-table::
:header-rows: 1
:widths: 50 50
* - \*_GM+orig\* images (10 ROIs)
- \*_GMI+orig\* images
* - .. image:: media/ROIS_EX2/ax_tiss_WM_GM.png
:width: 100%
- .. image:: media/ROIS_EX2/ax_tiss_WM_GMI.png
:width: 100%
* - .. image:: media/ROIS_EX2/sag_tiss_WM_GM.png
:width: 100%
- .. image:: media/ROIS_EX2/sag_tiss_WM_GMI.png
:width: 100%
|
#. 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
.. list-table::
:header-rows: 1
:widths: 50 50
* - \*_GM+orig\* images (9 ROIs)
- \*_GMI+orig\* images
* - .. image:: media/ROIS_EX2/ax_tiss_WM_TRIM_GM.png
:width: 100%
- .. image:: media/ROIS_EX2/ax_tiss_WM_TRIM_GMI.png
:width: 100%
* - .. image:: media/ROIS_EX2/sag_tiss_WM_TRIM_GM.png
:width: 100%
- .. image:: media/ROIS_EX2/sag_tiss_WM_TRIM_GMI.png
:width: 100%
|
#. 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
.. list-table::
:header-rows: 1
:widths: 50 50
* - \*_GM+orig\* images (8 ROIs)
- \*_GMI+orig\* images
* - .. image:: media/ROIS_EX2/ax_tiss_WMCSF_TRIM_GM.png
:width: 100%
- .. image:: media/ROIS_EX2/ax_tiss_WMCSF_TRIM_GMI.png
:width: 100%
* - .. image:: media/ROIS_EX2/sag_tiss_WMCSF_TRIM_GM.png
:width: 100%
- .. image:: media/ROIS_EX2/sag_tiss_WMCSF_TRIM_GMI.png
:width: 100%
|
#. 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
.. list-table::
:header-rows: 1
:widths: 50 50
* - \*_GM+orig\* images (9 ROIs)
- \*_GMI+orig\* images
* - .. image:: media/ROIS_EX2/ax_tiss_FA02_TRIM_GM.png
:width: 100%
- .. image:: media/ROIS_EX2/ax_tiss_FA02_TRIM_GMI.png
:width: 100%
* - .. image:: media/ROIS_EX2/sag_tiss_FA02_TRIM_GM.png
:width: 100%
- .. image:: media/ROIS_EX2/sag_tiss_FA02_TRIM_GMI.png
:width: 100%
|
#. 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
.. list-table::
:header-rows: 1
:widths: 50 50
* - \*_GM+orig\* images (10 ROIs)
- \*_GMI+orig\* images
* - .. image:: media/ROIS_EX2/ax_tiss_FA02_GM.png
:width: 100%
- .. image:: media/ROIS_EX2/ax_tiss_FA02_GMI.png
:width: 100%
* - .. image:: media/ROIS_EX2/sag_tiss_FA02_GM.png
:width: 100%
- .. image:: media/ROIS_EX2/sag_tiss_FA02_GMI.png
:width: 100%
|
#. And, finally, use **no** tissue information, either for subtraction
or inflation::
-prefix ROIMADE_nada
.. list-table::
:header-rows: 1
:widths: 50 50
* - \*_GM+orig\* images (10 ROIs)
- \*_GMI+orig\* images
* - .. image:: media/ROIS_EX2/ax_tiss_notiss_GM.png
:width: 100%
- .. image:: media/ROIS_EX2/ax_tiss_notiss_GMI.png
:width: 100%
* - .. image:: media/ROIS_EX2/sag_tiss_notiss_GM.png
:width: 100%
- .. image:: media/ROIS_EX2/sag_tiss_notiss_GMI.png
:width: 100%
|
Comment 1
---------
Out of interest, one could compare the inflation maps of the previous
two examples, in order to see the potential benefits of using the FA
map to restrict inflation. Consider the subtraction of the inflated
(\*_GMI+orig\*) maps::
3dcalc \
-a ROIMADE_nada_GMI+orig \
-b ROIMADE_FA02_GMI+orig \
-expr 'b-a' \
-prefix DIFF_FA02_and_nada
The resulting differences highlight that unconstrained inflation
pushes the target regions much further into the WM, which may lead to
association of targets with unrealistic WM when tracking:
.. list-table::
:header-rows: 1
:widths: 100
* - Difference of \*_GMI+orig\* images
* - .. image:: media/ROIS_EX2/ax_tiss_DIFF_FA02.png
:width: 60%
:align: center
* - .. image:: media/ROIS_EX2/sag_tiss_DIFF_FA02.png
:width: 60%
:align: center
Comment 2
---------
As might be apparent from above examples, thresholded GM ROIs can be
further split up when trimming with WM and CSF skeletons. For
instance, this might be useful in separating left and right hemisphere
regions. Also, users might have to re-evaluate what volume threshold
is reasonable to use, depending on their own criteria.
Comment 3
---------
While using the T1w- and FA-derived WM maps may produce very similar
ROIs, it would make the most sense to use the exact map in
`3dROIMaker` that will be used to guide the actual tractography (NB:
`3dTrackID` *can* use non-FA maps to define regions for tracking, see
the help therein for the `-dti_extra *` option). This is for the sake
of consistency.
|
.. _ROI_Example_Connectome:
Connectome Parcellation
=======================
This is a case where the dataset being input to ``3dROIMaker`` likely
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 ``Do_11_RUNdti_Connectome_Examp.tcsh``.
Such a dataset is shown here:
.. list-table::
:header-rows: 1
:widths: 30 70
:stub-columns: 1
* - Description
- FreeSurfer parcellation
* - (Sagittal) WB parcellation overlaid on T1w anatomical scan.
Each color shows a different ROI (ROI_i256 colormap).
- .. image:: media/ROIS/aparc_sag85.png
:width: 100%
* - (Axial) WB parcellation overlaid on T1w anatomical scan.
- .. image:: media/ROIS/aparc_axi173.png
:width: 100%
First, ``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:
.. list-table::
:header-rows: 1
:widths: 70 30
:stub-columns: 0
* - GM ROIs from FreeSurfer parcellation -> Inflation
- Description
* - .. image:: media/ROIS/aparcGM_axi173.png
:width: 100%
- Cortical ROIs overlaid on T1w anatomical image.
* - .. image:: media/ROIS/aparcGM_onFA_axi48.png
:width: 100%
- Cortical ROIs (translucent) overlaid on a DTI parameter
(FA>0.2) mask.
* - .. image:: media/ROIS/aparcGMI_onFA_axi48.png
:width: 100%
- Inflated ROIs (translucent; ``3dROIMaker`` output file name
``*_GMI*``) overlaid on a DTI parameter (FA>0.2) mask.
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
well::
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.