*****************************************************************
ROI Toolbox Overview
*****************************************************************
or: How I Learned To Stop Worrying And Love The Toolbox


	This text is intended as a very quick introduction to what each section and button 
of the ROI toolbox does.  Each of these functions has an individual help file associated 
with it which has an in-depth examination of how to use it, but this introduction should 
give you a sense of what is possible with the Toolbox.  If you have any questions about 
the Toolbox’s functionality or usage, please ask Sue, Jeff, or Pavithra.
    Further documentation is being made available, slowly but surely, in text files in
/usr/fmri_progs/matlab/docs, mostly of the name "[filename or button name]_readme.txt."
Look there for in-depth instructions for a particular function; more files will be added
soon.

************************
Opening/Closing the Toolbox
************************ 
	Opening: Start MATLAB with the spm99-6 or spm99-6-devel commands at a 
UNIX command prompt.  At the MATLAB prompt, type “roimod1.”
      - alternatively, start MATLAB from anywhere and make sure you have 
/usr/fmri_progs/matlab/gablab or /usr/fmri_progs/matlab/devel at the top of your path.  
At the MATLAB prompt, type “roimod1.”
	Closing: Click the “x” button in the upper-right hand corner, like a regular 
window.  

*************************
Section: Artifact Detection (Global Variate, Movement Parameters, Movie of Images)
*************************
	The tools in this section are intended to be used on raw images, before you do 
spatial preprocessing, although they may be used on spatially preprocessed images as 
well.  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.

- Global Variate (artdetect4.m)
	An interactive tool to identify and repair motion-related outlier images in your 
experiment.  The tool displays a plot of global intensity values for each scan, z-scores for 
each of those intensity values, and plots the realignment movement parameters for each 
scan, so you can identify scans whose intensity values are way outside the mean and 
which occurred at the same moment as a large head movement.  The tool then allows you 
to repair the timecourse by replacing outlier scans with a mean functional image or with 
an interpolated image created from the outlier’s neighboring scans.

- Movement Parameters (plot_move.m)
	A simple display tool to look at the realignment movement parameters for a given 
scan session.  Parameters are plotted on two sets of axes; the first displays x,y,z motion 
for the head in mm, while the second plots pitch, roll, and yaw motion for the head in 
radians.

- Movie of Images (spm_movie.m)
	Runs through every image in a given timecourse as a movie, which allows quick 
viewing of all the scans.  Useful to detect bizarre outlier scans that automated methods 
might miss.

*************************
Section: ROI Statistics
*************************
	The tools in this section are intended to extract various statistics and measures of 
activation within a region of interest specified by an .img or .tal file over a whole 
timecourse of images.

- ROI stats (roi_stats.m)
	Given an ROI .img file and a set of data images to extract from, this function 
extracts the number of non-masked voxels in the ROI in each image, the average 
intensity value of all voxels in the ROI from each image, the variance of intensities across 
all voxels in the ROI from each image, and the min and max intensities in the ROI from 
each image, and returns a data structure containing vectors of all those values.

- ROI Extract (roi_extract.m)
	Just like ROI stats, but this function only extracts the mean.  Given an ROI .tal 
and a set of data images to extract from, this function extracts the average intensity value 
across all voxels in the ROI from each data image.  It optionally writes those values to a 
text file.

- % Signal Change (roi_percent.m)
	This function takes ROI .tal files and a set of data files and extracts the % value 
that the mean intensity of all the voxels in the ROI differs at each scan from the mean 
ROI intensity across the whole data set.  It optionally applies a number of temporal 
preprocessing options to the data set before the values are extract to clean up the values.  
It can also be set to an individual voxel mode, in which % signal change is extracted from 
a single voxel.  It writes the values for the whole timecourse out to a text file, as well as 
average signal change values for each condition of the experiment.

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

- Display ROIs
	This button pops up the standard SPM interactive display screen, with three 
orthogonal views, and then allows the user to superimpose up to three ROI images on top 
of the background image in different colors.

- Display Slices
	This button asks for a set of background and ROI images to display, then asks the 
user to select what sort of image (structural or blob) each is, as well as the desired 
orientation for displayed slices and a range to pick slices from; it then pops up a non-
interactive multiple-slice viewing window with any ROI images displayed as blobs, 
suitable for printing.

- Render
	Activates the SPM render facility to create a rendered image of the brain on which 
an ROI image may be superimposed; the results are displayed in a non-interactive 
window suitable for printing.

*************************
Section: Voxel Coordinate Conversion
*************************
	The tools in this section work together to allow .tal (text) files to be transformed 
into .img (image) files and back, and to convert ROIs from Talairach space into MNI 
space and back.
	A QUICK NOTE ABOUT TERMINOLOGY, WHICH IS VERY CONFUSING 
IN THIS SECTION: 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 a bit unfortunately named (due to a 
lack of forethought by some folks writing SPM), because a .tal file may be in EITHER 
Talairach space or MNI space.  The issue arises because SPM results are reported in MNI 
space, whereas anatomical ROIs are commonly generated in Talairach space, which is 
what the mni2tal and tal2mni functions are for.  But a .tal file is NOT necessarily in Tal 
space – it may be an MNI-space .tal file, and so forth.  Thusly, we refer to .tal files as 
“text files” wherever possible, to try and avoid some confusion.  Although I feel as 
though maybe we’re creating even more.  Who knows?

- img2txt, txt2img
	These functions are used to change .img files into .tal files and back again.  
Changing an image into a text file is pretty self-explanatory, but txt2img, used to convert 
a .tal into a .img, is a little trickier; since the coordinates in .tal files are listed in 
millimeters, changing that coordinate list into a voxel-based .img file requires knowing 
what the voxel size and origin coordinates should be.  So txt2img requires an “image 
defining space” – a .img which defines the space in which the new .img will be made.

- mni2tal, tal2mni
	These functions are used to change ROIs, in the form of .tal files, from MNI space 
to Talairach space and back again.  These create new .tal files in the desired output space.  
The mni2tal function creates files of the same name of the old ones; the tal2mni function 
appends _mni to the filename in its translation process.

*****************************
Section: Anatomical ROIs
*****************************
	The tools in this section are intended to generate and manipulate anatomically-
based or cubical regions of interest.

- Generate Tal ROIs
	Uses the Talairach Daemon database to generate ROI .img files based on various 
anatomical landmarks.  ROIs can be generated by intersecting or connecting any gyri, 
Brodmann areas, hemispheres, tissue types, etc. desired – typical results would be “left 
amygdale” or “intersection of right BA 10 and inferior frontal gyrus.”  These .img files 
are in Talairach space, so before they are directly applied to SPM results, they should be 
converted into MNI space with tal2mni.

- XYZ_rois
	Allows the user to generate cubical ROIs based on specified x, y, and z limits in 
millimeters.  The initial output is a .tal file called “roi.tal,” but the program automatically 
enters into the txt2img facility to allow creation of a .img file from the roi.tal file.

- roi_process
	Combines a sequence of steps intended to be applied to .imgs that have come 
right out of the Talairach Daemon or “Generate Tal ROIs” button – the idea would be to 
run that to specify anatomical regions of interest, then immediately run roi_process on 
these raw .imgs to prepare them for SPM.  Roi_process takes a set of ROI .img files and 
converts them into MNI space (by running them through a .img-to-.tal conversion, a 
Talairach-to-MNI conversion and a .tal-to-.img conversion back to images), then smooths 
the ROIs with a specified Gaussian kernel and finally truncates them, converting them 
into black-and-white images suitable for SPM statistical use.

- Smooth
	Activates the SPM smoothing facility to allow spatial smoothing of ROI .img 
files.

- Truncate
	After an ROI is smoothed, its image intensities likely no longer consist of only 
ones and zeros; it may also have been enlarged by the smoothing process.  Truncation 
allows the user to select an intensity threshold, then sets all voxels whose values are 
below the threshold equal to zero and all voxels above the threshold to one.  This creates 
a black-and-white image suitable for use as a mask.

- Reverse Norm
	Given a .tal file containing ROI coordinates and an “_sn3d.mat” file of the sort 
output by SPM’s normalization process, this function inverts the normalization 
parameters used to normalize a particular image and applies the inverted parameters to 
the .tal file.  This can be used to take an ROI in standard, MNI space and convert it to one 
which is precisely fitted to a particular subject’s anatomy.


****************************
Section: ROI Time Series
****************************
	This section contains tools intended to look directly at and manipulate complete 
timecourses of ROI intensity values.

- ROI Time Series Analysis
	An interactive tool which allows the display of timecourses from particular ROIs 
and/or particular voxels; these timecourses can be for a complete experiment, or a given 
condition or number of conditions, and can be updated interactively to examine the 
effects of temporal and/or spatial preprocessing on the data.  COMING SOON.

- MARSBAR
	An outside ROI package developed by Matthew Brett and others which contains 
some of the functionality of this Toolbox as well as a number of other facilities.  See 
MARSBAR documentation for details.


*****************************
Section: Functional ROIs
*****************************
	This section’s tools are intended to allow the generation, display, and 
manipulation of functionally-based regions of interest – that is, ROIs taken from 
activation clusters empirically derived in an experiment.

- Generate func ROIs
	This button calls the SPM results facility (just as if you’d hit “Results” in SPM), 
in order to call up activations for a particular contrast and threshold level.  The “S.V.C.” 
button in the results control panel can be used to isolate a particular cluster and save it out 
as a .tal file.

- SPM Tal Stats
	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.

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

- Display_TalSpace
	This function displays selected functional clusters on an illustrated Talairach 
atlas, allowing them to be lined up precisely with Talairach-space anatomy, and allows 
them to be rendered into 3-D on the Talairach brain.

- tbx_roi
	This button calls up Russ Poldrack’s ROI Toolbox, an outside package developed 
to work with SPM’s functional ROI capabilities.  Provides a number of ways to generate 
multiple functional ROIs and ROIs of different shapes based around functional clusters.  
See tbx_roi documentation for more details.
