Functional MRI Analysis with xds

Timothy L. Davis <> 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 expects 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).