ROI Toolbox

In the Gabrieli Lab, one major package of custom programs we've written is the ROI Toolbox, which is available to anyone working on a Gablab machine (and someday on the lab website).

This page has a quick description of what all the scripts in the toolbox do, and at some point will hopefully link to their documentation as well (when I get around to updating them and putting them on the web). A couple of the scripts already have their own FAQ pages up - scroll down to find those links.

However, you can always access the documentation for any script from the ROI Toolbox itself, in the upper right-hand corner. Make sure you're running the graphical version of Matlab, or else you won't be able to get to them. They're also available in the Gablab file structure at


You can run the Toolbox by running spm99-6-devel from a terminal prompt at a Gablab machine (which will bring up Matlab), and then typing "roimod1" at the Matlab prompt. The Toolbox is compatible with Matlab 6.0 (R12) or 6.5 (R13), so far as I know.

Toolbox Overview

Global Variate (artdetect4.m)

More info at ArtDetect...

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.

ROI stats (roi_stats.m)

Given an ROI .img file and a set of data or beta 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 image. It optionally writes those values to a text file.

% Signal Change (roi_percent.m)

More info at RoiPercent.

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 (or for a particular condition). 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.

Display ROIs (display_rois.m)

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 (display_slices.m)

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.


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.

img2txt, txt2img (roi_list.m, mm2img.m)

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 “template image” – a .img which defines the space in which the new .img will be made.

mni2tal, tal2mni (mni2talgui.m, tal2mnigui.m)

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 appends _tal to the filename in its translation process; the tal2mni function appends _mni.

Generate Tal ROIs (tal_roi.m)

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 (roi_xyz.m)

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 (roi_process.m)

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 (spm_smooth_ui.m)

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


Truncate (roi_truncate.m)

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 (reverse_norm.m)

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.

ROI Time Series Analysis

An interactive tool which allows the display of intensity and % signal change 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 preprocessing on the data. Sort of like % signal change above, but interactive.

MARSBAR (marsbar_wrap.m)

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.

Generate func ROIs (spm_results.m)

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 (glassbrain.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.

Tal stats summary (sum_coord.m)

This function summarizes an output file generated by the Talairach Daemon

program, giving you a file which tells you how many voxels were in each location.

Display_Tal_Space (TSU_wrap.m)

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 (tbx_roi_wrap.m)

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.