*****************************************************************
ROI Toolbox Overview
*****************************************************************

    The ROI Toolbox is a pushbutton user interface to many handy
programs for removing artifacts, generating ROIs, and analyzing data
that is in an ROI. It also contains utility programs to convert
between coordinates systems, and find anatomical names from coordinates.
The functions are briefly summarized below. 

    The toolbox Program Help button contains more information for each 
individual function.

  If you have any questions or comments about the Toolbox’s functionality
or usage, please ask Paul or Sue. 


************************
Opening/Closing the Toolbox
************************ 
  - Opening: Start MATLAB with the spm2-devel command at a 
    UNIX command prompt.  At the MATLAB prompt, type “roimod2.”
    (The command spm2-devel sets all MATLAB paths correctly.
    For Matlab version 7.0, spm3-devel sets the MATLAB paths correctly.)

  - Alternative Open: Start MATLAB from anywhere and make sure you have 
    /usr/fmri_progs/matlab/spm2, including the /devel folder at the top of your path.  
    At the MATLAB prompt, type “roimod2.”

  - Closing: Click the “x” button in the upper-right hand corner, like a regular 
    window.  


*************************
Section: Artifact Detection 
*************************
These tools help you find scanner artifacts or outliers in your data caused by radical 
head motion or scanner mishap, and repair or remove them. The "Artifact protocol" button
in the Toolbox gives a description of how these repairs work with the SPM analysis.

 -Global Variate checks for outlier volumes, and offers repair methods.

 -Contrast Movie allows a user to view all the data, voxel by voxel.

 -Slice Repair checks for outlier slices, and offers repair methods.

 -Movement Parameters allows a user to check for total motion.

 -Task Correlation checks for motion-task confounds.

 -GlmMask repairs errors in SPM Results that were due to a poor SPM mask.

      
*************************
Section: Display
*************************
These tools provide several different ways to visualize your region of 
interest in an interactive fashion or in one suitable for printing.

 -Display ROIs shows one or more ROIs in 3D interactive overlayed on a background image.

 -Display Slices shows the same thing as a montage of slices. Suitable for printing.

 -Render activates SPM rendering, showing ROIs on a brain. Suitable for printing.


*****************************
Section: Anatomical ROIs
*****************************
These tools generate and manipulate anatomically-based or box regions of interest.

 - Tal or MNI ROIs can generate an ROI in MNI space starting from the MNI atlas or the 
   Talaraich atlas. The atlas is the WFU_PickAtlas, which includes the conversion of 
   Talaraich coordinates into MNI coordinates (so Brodmann areas have MNI locations).

 - XYZ_rois generates a box ROI based on specified x, y, and z limits in millimeters. The
   WFU_PickAtlas above can also generate a cube or a sphere.  

 - Tal ROI to MNI converts Talaraich coordinate ROIs from the Talaraich Daemon into MNI
   images. A wonderful program when written, but now it's redundant with WFU_PickAtlas.

*Note on LEFT-RIGHT coordinates
*   In SPM2, it is assumed that all images are stored in radiological format. All the display
*functions flip the image into neurological format for display (but don't change the storage 
*format.) Anatomical ROI's are conceptually in neurological space. The WFU_PickAtlas will
*convert the ROI into radiological format for compatibility with Stanford's SPM2 
*installation. The FlipLock button in the WFU_PickAtlas is set to do this correctly.
*   Be careful if you have old ROI's generated in SPM99. SPM99 processing assumed that images
*were in radiological format up to normalization, and were in neurological format after
*normalization. Hence, anatomical ROIs were written in neurological format to be
*compatible with SPM99 normalized images. These ROIs would be L-R reversed if used in SPM2:
*it's better to generate new ones for SPM2.


*****************************
Section: Utility Programs
*****************************
These programs are automated tools for common user functions.

 - Find Anatomy Names finds names  (hemisphere, lobe, Brodmann area)  for one or more 
   [XYZ] points in MNI space using the WFU_PickAtlas database.
 
 - Contrast Copier collects contrast images from different subjects and puts them in
   a single folder. A good program to correlate fMRI data with behavioral data.

 - Create Head Mask automatically generates a reasonable full-head mask. Designed to 
   eliminate the wrap-around artifact in spiral scan data.
   
 - Fix Bad Pathnames. When files are moved or old files are restored, the names embedded
   in SPM.mat are not valid. This program (modifySPM2.m) can repair the file names.
 
 - Dump SPM to Anatomy dumps voxels from SPM Results/Volumes table, and names all the points.
   Allows the user to identify anatomy locations of active SPM cluster regions.


*****************************
Section: Talairach Atlas
*****************************
These programs allow direct use of Talairach Atlas (instead of WFU_PickAtlas.)

- Dump SPM to Tal  (glassbrain2.m) 
	This button can only be used if an SPM results window is currently up.  If SPM 
results are being displayed and this button is selected, a file (possibly more than one) is 
generated which contains the complete list of the coordinate positions of all the activated 
voxels in the current results, converted into Talairach space – effectively a way to 
“dump” voxel locations from SPM into a text file. Redundant with SPM to Anatomy.

- Tal stats summary (sum_coord.m)
	This function summarizes an output file generated by the Talairach Daemon 
program.

- Display_TalSpace (TSU_wrap.m) makes 3-D images of clusters on the Talairach brain.



*************************
Section: ROI Analysis
*************************
These tools extract statistics, time course histories and measures of activation 
within a region of interest (specified by an .img or .tal file) over an entire timecourse
of images.

- ROI stats finds mean, min, max, and variance of data in an ROI for each image in a series.
  ROI is defined by a .img file.

- ROI Extract finds the mean intensity of an ROI for each point of a timeseries. ROI
  is a .tal list of coordinates.

- Run Xbeta is a utility program to run roi_stats on multiple beta files.

- ROI HRF Estimate can estimate the HRF responses to different conditions within an ROI.

- MARSBAR is an outside package with similar ROI functionality.

- ROI Time Series Analysis is an interactive display of timecourses from an ROI.



*************************
Section: Voxel Coordinate Conversion
*************************
An ROI can be expressed as:
     - An image of 1's and 0's. ( .img file )
     - A list of points in MNI space  ( .txt file ) in mm units.
     - A list of points in Talaraich space ( .tal file ) in mm units.
     - A list of points in single subject space.
The tools in this section work together to allow conversions between these spaces.

- img2txt converts an ROI img ( in MNI space ) into list of points (.txt file.)

- txt2img converts a list of points in MNI space into a .img file. Program asks for
  a sample image in order to set the voxel size and image dimensions.

- mni2tal converTs a list of points in MNI space to a list in Talaraich space (.tal file).

- tal2mni converts a list of points in Talaraich space to a list in MNI space. It
  appends _mni to the filename in its translation process.

- Reverse Norm converts a list of points in MNI space to a list of points in
  single subject space by inverting the normalization (_sn.mat) calculated by SPM.

*Note on COORDINATE TERMINOLOGY.
*       There are two common “spaces” of “normal” brain coordinates commonly used as a 
*   navigation system within the brain – Talairach space, based on the 
*   Talairach/Tournoux atlas, and MNI space, which is based off an “average” brain created 
*   by the Montreal Neurological Institute from hundreds of brains.  
*       There are also two types of files that SPM and this Toolbox use to store regions
*   of interest - .img files, which are directly viewable by SPM, and .tal files, which 
*   are simple text files that list the coordinates in the ROI.  HOWEVER, .tal files are
*   ambiguous , because a .tal file may be in EITHER Talairach space or MNI space. SPM results
*   are reported in MNI space, whereas anatomical ROIs are often generated in Tal space. 
*   To reduce confusion, we refer to .tal files in MNI space as
*   “text files” wherever possible.

