Gablab Toolbox

Gablab Toolbox

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

This page has a quick description of what all the scripts in the toolbox do, and links to the full documentation for each script. A couple of the more complicated scripts additionally have their own FAQ pages, which are linked below under their names.

You can always also 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 /usr/fmri_progs/matlab/spm99/devel/help (and mirrored at /usr/fmri_progs/matlab/spm2/devel/help).

You can run the Toolbox by running spm2-devel (or 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.5 (R13) and 6.0 (R12).

Keep in mind that when using the Toolbox with SPM2, the programs that create image files may be subject to ?SideFlipping problems. Be careful...

Step-by-step directions for using many of these scripts can also be found at RoisHowTos. RoisFaq can also be an invaluable reference for understanding why you want to use many of these scripts, and to what purpose.

Toolbox Overview

Global Variate (artdetect5.m) (full docs: global_variate_readme.txt)

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) (full docs: movement_parameters_readme.txt)

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) (full docs: movie_of_images_readme.txt)

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) (full docs: roi_stats_readme.txt)

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) (full docs: roi_extract_readme.txt)

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) (full docs: percent_signal_change_readme.txt)

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. The end result is similar to that of RoiDeconvolve (see below), but this program is suitable for block and long event-related designs and less do for rapid event-related designs.

roi_deconvolve (roi_deconvolve.m) (full docs: roi_deconvolve_readme.txt)

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 some selected baseline. It optionally applies a number of temporal preprocessing options to the data set before the values are extracted to clean up the values. It runs that % signal timecourse through a finite impulse response model (see PercentSignalChangeFaq) to re-create peristimulus timecourses for each of your conditions, independent of the contributions of other conditions. Essentially, given the data and a model of the neuronal response (your design matrix), roi_deconvolve re-creates the hemodynamic response for each condition. These timecourses are all written out to text files, and an interactive viewer is created to explore them. The end result is similar to that of RoiPercent (see above), but this program is suitable for rapid event-related designs and less so for block and long event-related designs.

Display ROIs (display_rois.m) (full docs: display_rois_readme.txt)

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) (full docs: display_slices_readme.txt)

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 (spm_xbrain.m) (full docs: SpmHowTos or SPM manual)

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) (full docs: img2txt_readme.txt, txt2img_readme.txt)

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) (full docs: mni2tal_readme.txt, tal2mni_readme.txt)

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. See Matt Brett's page on MNI space for info on why these are necessary: http://www.mrc-cbu.cam.ac.uk/Imaging/Common/mnispace.shtml

Generate Tal ROIs (tal_roi.m) (full docs: generate_tal_rois_readme.txt)

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) (full docs: xyz_rois_readme.txt)

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) (full docs: roi_process_readme.txt)

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) (full docs: smooth_readme.txt)

Activates the SPM smoothing facility to allow spatial smoothing of ROI .img files. See SmoothingFaq for more about smoothing.

Truncate (roi_truncate.m) (full docs: truncate_readme.txt)

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) (full docs: reverse_norm_readme.txt)

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.

Timeseries Explorer (full docs: timeseries_explorer_readme.txt)

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) (full docs : http://marsbar.sourceforge.net/)

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 the MarsBaR main page for more details.

Generate func ROIs (spm_results.m) (full docs: RoisHowTos or SPM manual)

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. Check out RoisHowTos for instructions on how to define a functional ROI.

SPM Tal Stats (glassbrain.m) (full docs: spm_tal_stats_readme.txt)

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) (full docs: http://www.ihb.spb.ru/~pet_lab/TSU/TSUMain.html)

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. It was developed by the PET lab at the Institute of the Human Brain in St. Petersburg, Russia.

tbx_roi (tbx_roi_wrap.m) (full docs: http://spm-toolbox.sourceforge.net/)

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 the TBX main page for more details.