ROI Toolbox Docs

Documentation: ROI Extract (roi_extract.m)
--------------------------
Jeff Cooper
12/12/02


1. Summary

roi_extract is a script intended to extract the mean image 
intensity of a whole region of interest from a timecourse of images.
It is similar to roi_stats, but only extracting the mean, and with 
the option to write the mean values directly to a text file for 
further use.


2. Usage

data = roi_extract
data = roi_extract(images, roi_file, textFlag)

roi_extract can be run either from the command line or with the 
ROI Extract button in the ROI Toolbox.  If it is run from the 
command line, it can be optionally supplied with up to three
arguments, although if any argument isn’t supplied, the program
will ask for them.  The first argument must be a vector of image
filenames from which to extract; the second must be a .tal (coordinate)
file containing the coordinates for a region of interest.  The third
argument should be a string, either ‘y’ or ‘n’; this controls 
whether the program will output the mean values to the console or just
write them out to a text file (‘y’ means the program will write to a 
text file and not to the console; ‘n’ means the program won’t write a
text file but will write to the console (or to a specified output
variable like ‘data,’ above)).
	If the program is run from the Toolbox button, it is run in the
no-input form, and thus queries the user for three things.  The first
query is for a set of data images from which intensities are to be
extracted; the second is for a .tal file defining the ROI in question.
Finally, the program asks whether or not the user would like to write 
its output values to a text file; NOTE that this query is in the MATLAB
window, NOT in a popup box like the two before it.  If the user chooses
no, the output will go to the console window; if the user chooses yes,
the extracted variables will be written to a text file in the present
working directory, but won’t be written to the console.   


3. Output

The script outputs one (and only one) of two things: either a vector
of average intensity values in the MATLAB window, or that same vector as
a text file (whose name is posted in the MATLAB window).  The choice of 
output modality (console or text file) doesn’t affect what the values of 
the output are.
	The output vector contains as many values as there are data images,
and each entry is co-indexed with a data image.  At each point in the vector,
the entry is the average image intensity, across all the coordinates in the  
region of interest, from the co-indexed image file.  
       So the vector as a whole is a timecourse of the average intensity 
value across the whole ROI, where each image is one point in time.  As usual, 
the units reported are the somewhat abstract “MR Intensity” units.
	The script is sensitive to the order that the data images are selected;
it does not sort the filenames alphabetically or otherwise before extracting
mean values from them.  So be careful in the order that you select your image
files.
	If the user chooses to output a text file, that file will have a filename
based on the filename of the ROI file, and will be saved into the present
working directory.  It should be saved in true-number (i.e., not-scientific)
notation.


4. Last Bits

roi_extract.m was written as part of the Gabrieli Lab ROI Toolbox,
a package of utilities to examine ROI data in SPM.  It requires 
several functions from SPM 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...

