Region-of-Interests (ROIs) in AFNI 2.20
---------------------------------------
A few tools for selecting voxel subsets and extracting their data for
external analysis are included with AFNI 2.20.  These tools are quite
new and crude, and (God willing) will be improved as time goes on.
Nonetheless, it is possible to do some useful work with them now.

The ROI stuff is mostly implemented as a set of plugins.  These all have
extensive help, so I won't give all the details here.  You may need to
write some C programs to calculate useful results after extracting the
data you want.

Selecting an ROI: plugin "Draw Dataset" [author: RW Cox]
--------------------------------------------------------
This plugin lets you draw values into a dataset brick.  The idea is to
start with a dataset that is all zeros and then draw nonzero values over
the desired regions.  An all zero dataset of a size equivalent to an
existing dataset can be created using the "Dataset Copy" plugin.
Another way to create a starting point for a mask dataset would be
to use the "Edit Dataset" plugin or the "3dmerge" program (e.g., to
pick out all voxels with a correlation coefficient above a threshold).

Normally, you would create the mask dataset as type "fim".  This would
allow it to be displayed as a functional overlay on the anatomical
background.

Mask datasets tend to be mostly zeros.  You can use the ability of AFNI to
read/write compressed datasets to save disk space.  See the file
"README.compression" and the plugin "BRIK compressor" for details.

To be useful, a mask dataset must be created at the resolution of the
datasets it will be used with.  This means that if you create a mask
at the anatomical resolution, the functional datasets to which you apply
it must be at that resolution also.

Averaging Data Defined by a ROI Mask: program "3dmaskave" [author: RW Cox]
--------------------------------------------------------------------------
This program lets you compute the average over a ROI of all voxel values
from an input dataset.  The ROI is defined by a mask dataset.  The average
value is computed for each sub-brick in the input, so you can use this to
create an average time series.  The output is written to stdout -- it can
be redirected (using '>') into a file.  For more information, try
"3dmaskave -help".  An alternative to this command-line program is the
similar plugin "ROI Average", which you can use interactively from
within AFNI.

Making a Dump File: plugin "3D Dump98" [author: Z Saad]
-------------------------------------------------------
This plugin lets you write to disk a list of all voxels in a dataset with
values in a certain range.  The ROI application is to list out the voxels
in the mask dataset.

Extracting Data Using a Dump File: plugin "3D+t Extract" [author: Z Saad]
-------------------------------------------------------------------------
This file lets you save all the time series from voxels listed in a mask
file.  They are in an ASCII format, which is designed to make them easier
to import into programs such as Matlab.

Converting a Mask File to a Different Resolution [author: RW Cox]
-----------------------------------------------------------------
It is most convenient to draw the ROI as a functional overlay on the same
grid as a high resolution anatomical dataset.  Applying this to a low
resolution functional dataset can be problematic.  One solution is given
below.  Another solution is to use the new (07 Feb 1999) program
"3dfractionize".  This will resample an input mask dataset created at high
resolution to the same resolution as another dataset (the "template").
See the output of "3dfractionize -help" for usage details.

=========================================================================
** The following documentation is by Michael S. Beauchamp of the NIMH. **
=========================================================================

Making Average Time Series Defined by a ROI -- MSB 7/21/98
----------------------------------------------------------
  One of the most useful ways to visualize FMRI data is an average MR time
series from a group of voxels. AFNI makes this easy, with the "ROI Average"
plug-in or the "maskave" stand-alone program. The user inputs a mask BRIK
specifying which voxels to average, and a 3d+time BRIK containing the time
series data. AFNI then outputs a text file with the average value at each
time point (and standard deviation, if desired) which can be graphed in
Excel or any other plotting program.
  Some difficulties arise when the mask BRIK and the 3d+time BRIK have
different coordinate spaces or voxel dimensions. For instance, when the
"Draw Dataset" plug-in is used to define an anatomical region of interest
(like a specific gyrus) on a high-resolution (e.g. SPGR) anatomical
dataset. The user then wishes to find the average time-series from all
voxels in this region. However, the echo-planar functional dataset is
collected at a lower spatial resolution (e.g. 4 mm x 4mm x 4 mm voxel size)
and a smaller volume (e.g. 24 cm x 24 cm x 12 cm) than the anatomical
dataset (e.g. 1 mm x 1 mm x 1.2 mm in a 24 x 24 x 17 cm volume). Because of
the differing voxel sizes and image volumes, the mask dataset cannot be
directly applied to the 3d+time dataset.
  To solve this problem, both the mask and 3d+time datasets are converted to
the same image volume by translation to Talairach space. 
Simplest Method:
  For the mask dataset, After the Talairach transformation is performed on
the hi-res anatomical, a transformed BRIK is written to disk (with the
"Write Anat" button), a copy made, and "draw dataset" performed on the
duplicate Talairach BRIK to make a mask in Talairach space.
Next, "Switch Underlay"/"Talairach View"/"Write Anat" is used to make a
Talairach version of the 3d+time BRIK. Then, "maskave" or "ROI Average" can
be used to make the average time series.
  Problem: the problem with this method is that a Talairach 3d+time BRIK at
the default 1 mm resolution can be enormous-- c. 1 GB. It is therefore
impractical if average time series from many subjects or tasks are needed.
Therefore, the anatomical and functional BRIKs can be sampled at a lower
resolution to decrease the disk space demands.
  More Complex Method: 
Create a duplicate of the original anatomical BRIK with 3ddup; click "Warp
Anat on Demand", and set Resam (mm) to 4. Click "Write Anat" to make a 4 mm
resampled dataset. "Draw Dataset" can be used to draw on the original
dataset before "Write Anat", or on the resampled Talaraich BRIK after
"Write Anat". However, after "Write Anat" is performed, drawing on the
original or Talaraich BRIKs will not change the other one.
Write out a Talaraich BRIK of the 3d+time dataset resampled at 4 mm (as
above). Then, "maskave" or "ROI Average" can be used to make the average
time series.
