ROI Toolbox Docs

Documentation: roi_process (roi_process.m)
--------------------------------------------
Jeff Cooper
12/16/02

1. Summary

roi_process is a mishmash of a script designed to apply several 
steps of processing at once to ROI image files.  Mostly, its
designed to take ROI image files straight from the Generate Tal
ROIs button and process them into a useful state to be used
in SPM, all at one stroke.
	The script takes ROI .img files in Talairach space and
does the following to them: 1) convert them into MNI space 
(see tal2mni_readme.txt for information about the Talairach-
MNI space issue), 2) spatially smooth them, 3) truncate them.
This renders the images nice and smooth, completely binary, and
ready to be applied to SPM-normalized images.
	This button is essentially a shorthand for the following
button commands: a) img2txt, b) tal2mni on the new .tal files, c)
txt2img on the new MNI-space tal files, d) Smooth on those
new MNI-space image files, e) Truncate on the newly smoothed
files.  No real new functionality is introduced with this 
script; its merely a way of saving a lot of file selection and
compressing five functions into one path.

2. Usage

roi_process

roi_process can be run either from the command line with no arguments,
or the roi_process button in the ROI Toolbox.  The user will be asked
to select the .img files that he or she wants to process, and an
output directory for the processed files. 
	Since .img files cant be directly converted to MNI space  only
.tal files work in the tal2mni conversion  the .img files are then 
transformed into .tal files and converted.  They then are converted back
into .img files, but in order to do this conversion, the script must
ask the user for a template image to make a txt2img conversion (see
txt2img_readme.txt for more details).  The user may safely select their
old, non-processed ROI .img file as a template if they would like  the 
only thing that will be looked at is voxel size and dimensions, and so
the processing will still take place correctly.  Alternatively, they can
select an image with different dimensions as a template if they want 
the new image to have new dimensions.  The user is then asked for an 
output directory for the newly converted .img files.
       The user will then be asked to specify a smoothing kernel to 
be applied to the new files, in standard SPM smoothing fashion.  Please
see smooth_readme.txt or SPMs instructions for smoothing for further
details on why this is desirable.
	Finally, one of the newly smoothed ROIs will be displayed in
the SPM graphics window, and the user will be asked to select a 
truncation threshold.  See truncate_readme.txt for details on the
truncation process, but in a nutshell, the truncation process
divides all voxels in the image into two categories: those whose
intensity is above the truncation threshold and those below it.  Any
voxels below the threshold have their intensity set to zero, and any
above it are set to one.
	Therefore, the user should examine the intensity values near the
edges of their smoothed ROI in the graphics window, and set the 
truncation threshold such that voxels that they think are outside their
region of interest are below the threshold number.
	After selecting a threshold and pressing return in the text box,
the images are truncated, and the script informs the user the processing
is finished.
 

3. Output

roi_process primarily produces one processed ROI image for 
each input ROI image, where the processed ROI image has been 
converted from Talairach space into MNI space, smoothed, and
truncated, so it now consists of a nicely rounded binary ROI
.img mask in MNI space.
	(NOTE: Users should take care to ensure their input files
are in Talairach space, or else they may end up with badly
warped output files.)
	The filenames for these output images are based on the
original .img files names, with ts appended to the front 
(for truncated, smoothed, in keeping with the SPM convention),
and _mni appended to the back, as a flag that the images are 
in MNI space.
	The script as a byproduct also produces two sets of .tal
files for each input file (one in Talairach space and one in 
MNI space), as well as unsmoothed *_mni.img files and 
untruncated s*_mni.img files for each input file.
	All of these files will appear in the specified output
directory.  If the user somehow specifies two different output
directories in the two queries, the .tal files will appear
in the first output directory, and all the new .img files
will appear in the second output directory.


4. Last Bits

tal_roi.m was written as part of the Gabrieli Lab ROI Toolbox,
a package of utilities to examine ROI data in SPM99.  It requires 
several functions in both of those packages to be run. 

This code is in a very fluid state of development, and any suggested
modifications are welcomed and invited.  Please contact Jeff Cooper
in the Stanford Psychology Department at jcooper@stanford.edu with 
any questions about usage, bug reports, or suggestions for further
revision.  Good luck...

