ROI Toolbox Docs

Documentation: Display Slices (display_slices.m)
--------------------------------------------
Jeff Cooper
12/13/02

1. Summary

display_slices is a script intended to allow the display of ROI
images or SPM activation results by superimposing those images on 
top of a background image and simultaneously displaying multiple
slices from the combination.  The script is highly flexible, and
also allows many other display options which involve displaying
multiple slices from multiple superimposed images simultaneously.

2. Usage

display_slices
display_slices(imgs)

display_slices can be run either from the command line or from the
Display Slices button in the ROI Toolbox.  If it is run from the
command line, the user may choose to specify which images to display
in a string matrix or cell array, but will still have to specify
the rest of the options in an interactive fashion.  If it is run 
from the Toolbox, or from the command line without arguments, the 
user chooses which images to display with the standard SPM file
selection window.
	Depending on what the user wants to display, exactly, the 
way to operate this script can vary highly.  Well give a quick over-
view of the script as a whole, and then give more detailed step-
by-step instructions for the two most common tasks for this script
below: superimposing an ROI on a background image, and superimposing
SPM activations from a results file (SPM.mat) on a background image.
	In brief, the order of operations for this script is as follows:
the user first chooses all of the image files that they want to display
and/or superimpose, all at once.  The user then tells the script what
type of image each file is  structural, truecolor, blobs, negative blobs,
or contour.  The user is then asked to supply some choices, depending
on what image types are chosen, for the colors and intensities to display
the images at.
	After colors are chosen,  the user then picks the type of slice to
display  axial, coronal, or sagittal  and chooses which slices to
display, in MATLAB expression format, by choosing the first and last
slices (in mm) and the slice increment to display (in mm).  The program
then pops up the SPM Graphics window with the chosen slices displayed, and
the chosen images superimposed with the chosen colors.
	Lets look a little more closely now at the two most common uses
for this scripts.


3. Displaying An ROI Image From A .img File.

The most common use of this script from the ROI toolbox is to display an
ROI image, functional or anatomical, contained in a .img file, on top of 
a structural MRI image, to better visualize the exact location and 
extent of the ROI.  Several ROIs can be chosen at once and superimposed
simultaneously.  Here are the steps to visualize ROIs in this manner.
	The user is first asked for images to display with the standard
SPM file selection window; he or she should select both the background 
anatomical image and all of the ROI files he or she wishes to display in
this file selection.  Once all the files are chosen, the user clicks Done.
	Next, the script asks the user to tell it what type of image
each of the selected image files is.  The user should select structural
for the background anatomical image, and blobs for each of the ROI
images.
	The script will ask for the user to specify a colormap and range
for each ROI.  There are a number of different prespecified colormaps in
MATLAB that can be used, each with a string name like hot or winter (type 
help graph3d at a MATLAB prompt for a complete list of them).  A 
colormap essentially specifies a range of colors mapped to a range of
numbers, which MATLAB and SPM will use to turn a numerical image like 
an .img file into a color image.  The image val range that the user is
asked for next tells the script what range of numbers are to be used in
the map.
	However, since ROI files generally are written as binary masks  
all zeroes outside the ROI, all ones within it  choosing the colormap
is a little tricky.  The user must select a colormap which has black as
its zero value (or else the anatomical image will be washed out in 
a strange color), but if the ROI displays in white, it can be difficult
to make out against the grayscale anatomical image.
	In general, hot and copper are good choices for the colormap.
	The default range value, however, of [0 1] will result in the 
ROI being displayed in white, since both of those maps have white as
their extreme value.  So the user should put a range of 0 2 (note
the space between the numbers) or 0 3; this will put the ROI image
value of 1 squarely in the middle of the map, which is usually a nicely
visible red or orange.
	The most visible choices for these values seem to be hot with
0 3 (which displays in red), and copper with 0 2 (a nice brown-y
orange).  The user is encouraged to play around with these, however.
	The script then asks for an intensity for the structural image;
this should be left at 1.
	After choosing the axis of the slices  axial, coronal, or sagittal 
the user must then choose which slices to display, by editing a string
which looks like -72:2:108.  The number before the first colon is the
location of the first slice to display in mm relative to the zero along
the chosen axis; the number after the last colon is the location of the
last slice to display in mm relative to the zero.  The number between the
colons is the mm increment between displayed slices.  So, in the example
above, the script would display slices every 2 mm from -72 mm to 108 mm
through the brain, with the ROI superimposed on them in the correct place.
	After choosing slice values, the graphics window should display
the chosen slices and superimposed image files; the user can choose to 
print this picture to the spm99.ps file with the Graphics windows
print button.  The scripts windows may then be closed at will. 



4. Displaying A Set Of SPM Activations From A Results File

Displaying SPM activations with display_slices is similar to displaying
an ROI image file, except the displayed file is an SPM.mat rather than
an image.  This results in several differences, but many of the 
instructions from above will be duplicated here.
	In order to display SPM activations, the user must currently be
in SPM and have results currently displayed in the Graphics window 
i.e., there must be a current set of activations showing from a 
particular contrast, threshold, etc.  This ensures that the proper
variables are all in the workspace and accessible to the display_slices
script.  The first step, then, is to go to SPM, select results,
choose the desired SPM.mat file, the desired contrast, threshold, etc.,
and get the results control panel up in the interactive window.
	display_slices can then be run either from the MATLAB command
line with the command, display_slices, or from the ROI Toolbox with
the Display Slices button.  The script will first ask for the user
to choose an image to display, and the user should choose ONLY the
background anatomical image on which they want the results superimposed.
After clicking done, the user will be asked what type of image the 
selected file is.  If the user is currently evaluating results in the
correct way, the first option in the drop-down menu should be Structural
with SPM blobs.  The user should choose this option.
	The script then asks for an intensity for the structural image;
this should be left at 1.
	After choosing the axis of the slices  axial, coronal, or sagittal 
the user must then choose which slices to display, by editing a string
which looks like -72:2:108.  The number before the first colon is the
location of the first slice to display in mm relative to the zero along
the chosen axis; the number after the last colon is the location of the
last slice to display in mm relative to the zero.  The number between the
colons is the mm increment between displayed slices.  So, in the example
above, the script would display slices every 2 mm from -72 mm to 108 mm
through the brain, with the current set of activations superimposed
on the anatomical image.
	The color bar at the lower right will display the scale for the 
activation colors; the hotter the color, the greater the t-value for 
that cluster.
	This image can be printed to the spm99.ps file, as usual, using
the Graphics windows print button.  It may be easier to zoom in on 
the color bar and read it in the spm99.ps file then in the Graphics
window.


5. Output

None, except for graphical output to the screen.


6. Last Bits

display_slices.m was written by Matthew Brett as an adjunct to the 
SPM99 software package.  It requires 
several functions from SPM99 in order to 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...

