ROI Toolbox Docs

Documentation: ROI stats (roi_stats.m)
--------------------------
Jeff Cooper
10/15/02


1. Summary

roi_stats.m is a script intended to extract basic statistics - 
mean, variance, max, min - about image intensity in a region of 
interest from a timecourse of data images.  It returns a structure
containing a timecourse of max, min and average signal intensity in
the ROI across the timecourse of data images, as well as variances
and number of voxels of the ROI present from each image.


2. Usage

[roi G] = roi_stats
[roi G] = roi_stats(roi_imagefile, data_images)

roi_stats can be called either from the ROI Stats button in the 
Toolbox, in which case it is called with no inputs and only the
base output structure.  It can also be called from the MATLAB 
command line as above.
	roi_stats takes in an ANALYZE .img file specifying
an ROI and a vector of filenames or memory-mapped data
image structures (i.e., the output of spm_vol on some filenames).
If either or both of these elements aren't input, the script will 
query the user to specify them.  Note that if the ROI is very large,
and/or there are a lot of images, the sampling process can take some
time.
	Once the user has specified the ROI and timecourse of images,
the script extracts image intensities from the image files and then
performs a series of basic operations on them.


3. Output

The output of roi_stats is a structure containing five vectors and 
an optional vector of global intensities.  The ROI structure has 
the following fields:
- max, min: The maximum (and minimum) image intensity of the voxels
within the ROI at that timepoint in the series of image files, i.e., 
each entry is co-indexed with an image file, and this entry is the max 
(or min) intensity within the ROI in that co-indexed file.
- n: The number of voxels in the specified ROI that were actually 
present in the co-indexed image file (which may vary if the data images
have been masked or have artifacts or something).
- mean: The mean image intensity across the ROI at that timepoint in
the series.
- var: The image intensity variance across that ROI at that timepoint in
the series.
    Additionally, there is an optional output variable, G, which is 
an N x 1 vector (where N is the number of scans / TRs), in which each
entry is the global mean image intensity of the whole image at that 
timepoint.

4. Last Bits

roi_stats.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...

