Functional MRI Analysis with xds
Timothy L. Davis <tldavis@nmr.mgh.harvard.edu>
October, 1998
This Guide is intended to introduce the user to a set of visualization
and analysis tools which were designed specifically for the analysis of
MRI data. Most of these tools have been utilized extensively for functional
mapping of brain cortex by echo-planar MRI. However, they are flexible
and should prove useful to anyone who collects data which is presented
as an image in two (e.g. spatial) dimensions and varies in a third (e.g.
temporal) dimension. The primary interactive tool is xds, a data
visualization program based on the X Window System. Image data is manipulated
using repack, which allows conversion between file formats and data
modification in spatial and temporal dimensions, magnitude constraints,
and scaling. Finally, an extensible series of special-purpose statistical
mapping engines with source code allows a wide range of analyses to be
performed in a straightforward manner.
Interactive Visualization with xds
The xds program was designed for efficient visualization of stacks
of image data (X utility to Display Stacks). It allows quick perusal
of data sets in space and time. Design goals were responsiveness, execution
speed, and sensible responses to user input. It reads multiple files
and loads, scales, and processes data in the background to allow the currently-requested
image to show up as quickly as possible, and to allow quick interaction
with the user while simultaneously managing memory allocation and image
formatting tasks. Color overlays describing summative statistics
can be dynamically thresheld, and need not be the same dimensions as the
underlying anatomical grayscale images. As many images and/or
overlays as desired can be loaded at once. There is wide flexibility
in image viewing for a wide range of image and time-course interpretation
possibilities.
Visualizing anatomical data
There are two windows for interaction with xds: the anatomical image display
window and the time-course graph window. The user types single-letter commands
at the keyboard while input focus is in the window. Input focus
refers to the X Window System's management of client programs; typically,
one either moves the mouse pointer into the window or clicks in the window
to place the focus there.
Starting the program
xds is started by specifying the program name and a list of image files
on the command line, along with any desired command line options. The command
xds -h
provides a summary of all command-line options, as well as a summary
of interactive commands. This help output can be easily sent to the printer.
During startup, xds opens a connection to the X DISPLAY server (see
the manual page for X for more information); then, it opens an image display
window and begins to copy image data to the X server. During these operations,
an indicator is placed in the lower right portion of the image display
window: `F' for file access, `S' for server access, and `*' for pending
access during interactive tasks. One can begin immediately to interact
with the image data; however, some operations (such as animation) may be
delayed if the data is not yet available at the server.
Zooming and interpolation
xds -z 4 -b image.bshort
starts xds with images located in file image.bshort increased
in size by 4x4 (-z 4), using bilinear interpolation (-b) for smoothing.
The zoom factor can be changed while the program is running by simply dragging
the window to a new size. Typing b interactively toggles between
pixel replication and bilinear interpolation. Pixel replication produces
the fastest result, bilinear zoom by a power of 2 is moderately fast, and
bilinear zoom by an arbitrary integral scale is slowest.
Image contrast: window and level
While there are command-line options to start with given data values to
ramp between black and white (see xds -h for details on -L and -H options),
it is most common to select the contrast and brightness using the mouse.
While holding down the middle button, dragging vertically changes brightness
(level), and horizontally changes contrast (window size). Because 8-bit
colormaps of typical X Window System servers limit the number of defined
gray values, it is sometimes helpful to re-assign colors in the colormap
to remove false contours in the display of data with high internal bit-depth.
Typing r interactively re-loads the images from the raw data based
on the currently displayed contrast, evenly spreading the gray values between
the currently-displayed maximum (white) and minimum (black) data
values.
In the latest version of xds (available from Ona Wu),
typing a number followed by Control-W will set the minimum value
displayed (all numbers below will be set to black). To set the maximum
value displayed, type the value followed by Control-E.
Auto window and level
By default, xds selects image brightness and contrast to display the entire
range of loaded data. This method can be easily applied to a single image
using the w interactive command, which uses the current image
(or current image region of interest, if defined) to set the maximum black
and minimum white data value. The data is then re-loaded as with the r
command, described in the preceding paragraph. Interactive region-of-interest
choice is describedbelow.
Choosing a region of interest (ROI) overlay
Image contrast and statistics can be obtained for a specified set of pixels.
This is commonly referred to as a region of interest (ROI). xds manipulates
ROI data as a simple overlay. Dragging the pointer while holding down the
left mouse button draws rectangles on this overlay. The interactive commands
x,
X, c, and C respectively set individual pixels,
toggle individual pixels, clear individual pixels, or clear the entire
overlay.
There are four overlays available. At any one time, the currently visible
overlays are the ones used for analysis or saving as an overlay file. xds
-h lists the interactive commands for switching the currently active overlay.
Saving and retrieving overlays
The O command writes over the file named default.ovl
with the current overlay definition. The overlay file is simply a list
of pixel locations in ASCII. the o command adds the contents of
default.ovl to the currently active overlay. The overlay file
name may be changed on the command line with, e.g., xds -v myoverlay.ovl.
Cycling through several images
When more than one image has been loaded into xds, either by listing more
than one image file or by loading image files containing multiple images,
the entire stack of images is available for display, one image at a time.
The + and - interactive commands step through the stack,
starting over after going through all of the images. In addition, an animation
function is available. When holding down the right mouse button, the images
are displayed in forward sequence. Horizontal motion of the mouse controls
presentation rate. During the initial period of image loading (while the
indicators `F', `S', or `*' are seen at the lower right of the image),
the xds client has not finished copying image data to the X Window System
server. Until this is complete, the animation may be slow.
Visualizing temporal sequences
The Plot window
The first use of the g interactive command causes a new X window
to be opened for display of time-course data. It may be positioned anywhere
on the screen. When the mouse pointer is placed in the image window, the
plot window is updated to show the intensity for the given pixel through
each image. This fast interaction between image coordinates and pixel time-course
is extremely useful to obtain an intuitive understanding of the behavior
of a given data set. The N interactive command switches to local
mode, for which the time course plot is re-scaled locally for each pixel.
Summary statistics
After defining a region of interest (see above) the s interactive
command generates summary statistics for that ROI. Unless the Q
interactive command is switched to Quiet mode, the s command prints
to standard output (stdout) a list consisting of
image_number pixel_count average standard_deviation Inf_count NaN_count
for each image in the stack. In addition, these averages are plotted
in the plot window. If the N command has not placed the plot window
in local mode, the standard deviation of the ROI for each image
is also displayed. NOTE that the standard deviation should not generally
be used as an error estimate for the time course; it is simply a measure
of homogeneity for the ROI.
Log files
When starting the program, a log file may be specified as, for instance,
xds -l logname.log imagefile.bshort
This log file will hold the summary statistics generated with the `s
command. The file may be renamed (Unix mv) between executions of the s
command in order to save multiple files of time-course statistics. A useful
paradigm is to define an ROI, save it with the O interactive command,
rename it from its default name default.ovl to something related
to the anatomical structure, then type s to save the time-course,
and rename that file to something similar but with a different extension.
Significance Map Overlays
Several of the separate statistical mapping tools produce a significance
map, or p-value map; in addition, they provide a map which may at first
seem strange: Ðlog(p-value). This Ðlog(p) map is provided for the
purpose of showing significance in color over an anatomical image. xds
has several features to allow this: The command-line option xds -A logp.bfloat
is first used to load the significance map. This may be a single image
to overlay the anatomical time course (so that active pixels may be identified
and their time courses examined directly), or it may be a time-course of
activation significance to show over a single high-resolution anatomical
scan. If the scans are of different resolution, the smaller will be bilinearly
interpolated before they are superimposed.
The current method for modifying the activation map is somewhat complicated.
To change the limits of significance for the overlay, one types the -log(p)
desired and either control-L for the lower limit, or control-H for the
higher limit. To change the lower limit transparency cutoff without altering
colors, one can specify a lower limit and control-A rather than control-L.
The Ðlog(p) map can be constructed specially for two-tailed tests.
By default, only positive map values are shown. Control-T cycles through
the tails displayed: typing once gives the negative tail only, again gives
both tails, and Control-T a third time shows the original image of positive-only
tails again.
The entire activation map can be hidden or redisplayed using the A
interactive command.
Special Display Options
Complex data
There are several manipulations which may be made on data before it is
displayed; the possible options are related to several common MRI techniques.
The simplest is complex data. If one produces data which is interleaved
pairs of real and imaginary components of a complex image, the current
method is to treat the data as a standard image, with twice the number
of columns as actual columnar data. Then, the -M (magnitude), -P (phase),
-R (real part), or -I (imaginary part) may be requested as command-line
options or interactively. The interactive commands for this are 1 D
(magnitude), 2 D (phase), 3 D (real), 4 D (imaginary),
and 0 D for standard (real-only) data. Displaying in a complex
mode reduces the number of displayed columns by half, and interprets the
data as complex pairs, displaying the requested portion.
Alternate color maps
Occasionally, one has constructed an 8-bit image and desires to display
it with a custom 8-bit (256 color) colormap. The command line option -m
colormap.map expects colormap.map to be an ASCII list of (red, green, blue)
color intensity triples (max intensity 65535). The requested colormap will
be installed and the data files treated as 8-bit color images indexing
this given color map. Contrast/brightness cannot be changed in this mode.
Sometimes, however, the user simply wants to colorize a one-parameter
image (e.g. as PET images are often presented). An alternate colormap is
available as the m interactive command. Unlike the user-specified
colormap, this colorized map can be modified in its window size and color
temperature using the window/level feature with the middle mouse button.
Referenced Images (subtraction, ratio, log ratio)
Often it is desirable to compare changes in a time-course data set visually.
The simplest such comparison is to choose a reference image and then to
subtract the reference from the entire stack of images. The result can
then be animated, and individual examples written out as separate files.
The 1 R interactive command chooses the currently-viewed image
as reference, and subtracts it from the remaining images. Afterwards it
may be necessary to re-set the image contrast to enhance differences. Similarly,
2 R divides all images by the current image, forming ratio images,
and 3 R produces images which are -log(image/reference), which
for T2 contrast bolus passage experiments corresponds to mapping changes
in 1/T2, or delta R2. 0 R returns to the un-referenced state.
Example usage
xds -b -z 4 baseline1.bshort expt.bshort does bilinear interpolation to
4x4 original image size, loading all images in the two listed files. I
then use the left mouse button to choose an ROI in the center of the tissue
and type w then C, which sets the window/level (brightness
and contrast) to a linear scale from black to white for the region of interest,
and then clears the ROI so that I can see the whole image. This process
also starts a re-loading of the entire dataset to that the 256 colors on
the screen maps are assigned reasonably. I sometimes then do the same thing
manually by changing brightness/contrast with the middle mouse button and
then typing r. I then type g to bring up the time-series
graph and scan around with the mouse.
To learn more about the command-line and interactive options for xds,
and to get the most up-to-date information, type xds -h.
For the curious: xds is a relative memory hog, taking more than twice
the space that it might really need, in order to be quick about its activities.
If you have trouble with crashes on sets of, for instance, 1000 images,
try limiting your input set size, preferably by cropping away the usual
70% of the image outside the sample using repack. It may also help to avoid
zooming images too large. One other trick is to run xds remotely on another
machine, so you get the memory on the remote machine for the base floating-point
representation and save your local memory for the screen pixmaps.
Currently Supported File Formats
While we commonly convert native-format image files containing a single
image each into multi-image short integer files for each experimental time-course
(filename ending in .bushort), the tools are capable of reading
files from any of a range of native imager and simple file formats. The
following formats are recognized according to a name suffix convention.
Any of the formats may be used as input to xds and repack;
however, output of programs is restricted to the simple binary types, and
in some cases (e.g. parameter mapping), the only output type permitted
is the .bfloat simple floating data type.
Simple binary data types with header file
All of the programs, including the statistical mapping routines, will accept
any of the simple data-stack types. Filenames ending in .b<type>
and .bu<type>, where <type> is a C data type from the following table,
are expected to contain unadorned image data. Minimal image header information
is contained in a separate file with the same base filename but ending
with extension .hdr. NOTE: multiple files with the same base filename but
different extensions will conflict in the name of the header file; therefore,
the user should be careful to use different base file names for each data
file within a directory. When it is not automatically generated,
the header file may be constructed easily: it contains (in standard ASCII
text) the number of rows, number of columns, number of images, and 0 if
Big-endian (created on Sun-style machine), or 1 if little-endian (created
on Intel-style machine). For example, a header file consisting of
a single line of text below
64 128 16 0
corresponds to a data file containing 16 images, each 128 pixels wide
by 64 high. The last zero indicates the byte-order of data words as described
above, and is usually 0 in our environment. The storage order for the data
is left-to-right, top-to-bottom, first image to last. There is currently
no method for specifying the number of slices per volume. Typically, each
slice is processed separately. However, if slices are stored in slice order
before temporal sequence, the processing can be done on volumes by manually
changing the header file. This trick is accomplished by multiplying the
number of rows in the image (64 in the above example) by the number of
slices, and dividing the number of images by the number of slices. Then,
several brain slices will appear vertically connected in a single image
and will be processed together for each time point. Another option
is to keep the data in large volume-images from the scanner or to use the
mosaic program supplied to make NxM image mosaics for each time-resolved
volume before temporal processing.
| Filename Extension. |
C data type |
bits/pel |
format |
range |
| .bfloat with .hdr |
float |
32 |
IEEE floating point |
[-1E38, 1E38] |
| .bchar with .hdr |
char |
8 |
integer raw data |
[-128, 127] |
| .buchar with .hdr |
unsigned char |
8 |
integer raw data |
[0, 255] |
| .bshort with .hdr |
short |
16 |
integer raw data |
[-32768, 32767] |
| .bushort with .hdr |
unsigned short |
16 |
integer raw data |
[0, 65535] |
| .blong with .hdr |
long |
32 |
integer raw data |
[-2E9, 2E9] |
| .bulong with .hdr |
unsigned long |
32 |
integer raw data |
[0, 4E9] |
|
|
|
|
|
| .dicom .nema .acr or .ani |
|
16 |
DICOM, ACR/NEMA or Siemens Numaris 2 |
|
| .ima or .num3 |
|
16 |
Siemens Numaris 3 |
|
| .ged |
|
12 |
GE Signa 3.x |
|
| .gedno |
|
12 |
GE Signa 4.x |
|
| .MR |
|
16 |
GE Signa 5.x |
|
| .gen |
|
16 |
GE Genesis |
|
| .ome with .hdr |
|
32 |
GE/Bruker Omega floating point |
|
| .im |
|
16 |
Advanced NMR APD-1 |
|
| .img with .irp |
|
16 |
Advanced NMR APD-2 |
|
| .anmr with .hdr |
|
16 |
Advanced NMR beta machine |
|
| .flt |
|
32 |
MGH seg-compatible floating point |
|
| .sis |
|
161 |
Sisco |
|
| .idf |
|
16 |
Technicare |
|
File formats supported by xds and repack.
General Electric Signa 4.x and Omega
Native General Electric 3.x, 4.x (.ged and .gedno), Genesis (.gen) and
Omega CSI (.ome) file types, each containing one image, can be read directly.
Advanced NMR
Files with the ANMR extension (.im), can be read directly. In addition,
the file number is read from the internal header and used for reordering
by default in the repack program.
ACR/NEMA and Siemens Numaris 2
Siemens Numaris 2 and NEMA images are recognized when given the .ima extension.
Numaris 3 images currently require conversion to ACR/NEMA format before
they are readable, as ACR header type 0x0028 is required.
Bruker, Sisco
The old Bruker format is supported (extension .imag) as is Sisco file format
(extension .sis).