ROI-AL for the Masses

Want to run ROI-AL and get nice regional alignment but don't have access to something like LDDMM?  We now have a solution (ROI-Demons) that can not only perform extremely well but under the right circumstances can even outperform the ROI-LDDMM method (using our previous default parameters) that we have used successfully to align MTL (and striatal) regions with excellent accuracy even down at the level of hippocampal subfields (see also here). Here, for example are "before" and "after" shots using a combined striatal + MTL regional alignment (average of 31 aligned brains) using the tools described here (a paper comparing many methods including this is currently under review).

The trick is to use MedINRIA and its Diffeomorphic Demons tool written by Vercauteren (which actually implements Thirion's Demons by default) and, optionally, use a command-line version of the tool that I have modified a bit to give us some useful features. With these, you can use a great instantiation of the ROI-AL approach. All you need is the ability to draw (or potentially functionally define) some region and this will do a diffeomorphic alignment of that region across participants. To recap the basic ROI-AL principles:

1. If you are interested in some particular region or set of regions in the brain and if you're brain-alignment techniques are limited in their degrees of freedom, don't waste any alignment power outside of these regions
2. If you as an expert know something about what part of the brain should be called Region X and not called "something else" or Region Y, tell your alignment algorithm this and it will respect this border.

If you segment (manually or automatically) the regions you are interested in and define them in 3D as a label mask (e.g. 1=left hippocampus, 2=right hippocampus, 0=stuff I don't care about) and use these labels as the basis for alignment, you will satisfy both of the above principles. Your alignment will be better as will your localization accuracy and your fMRI power (if you apply the same transformations to your statistical maps prior to group analyses).

Update 7/1/2008: MedINRIA does allow command-line use suitable for most all needs. Details added.
Update 7/11/2008: Documentation of some bugs / limitations added, Thirion vs. Vercauteren clarified, and sample average structural added.

Getting the goods

What you'll need if you want to just get up and going quickly (i.e., you're fine using binary distributions) 
• MedINRIA (http://www-sop.inria.fr/asclepios/software/MedINRIA/)
• Binary (Windows or Intel OS X currently) version of DemonsRegistration for extended command-line use
• The ability to get your files into a format known by ITK (Analyze's .img/.hdr and NiFTI .nii work)

What you'll need to compile it all yourself (i.e., what I needed to do to compile it for each platform):
• CMake (www.cmake.org) - just grab the binaries
• ITK (www.itk.org) - you'll need to compile this yourself. If you want to run the demos and examples, you'll need some more things, but if you just want to compile up things like DemonsRegistration, you're fine with just this.
• MedINRIA (http://www-sop.inria.fr/asclepios/software/MedINRIA/)
• Diffeomorphic Demons command-line tool by Tom Vercauteren (http://insight-journal.org/midas/handle.php?handle=1926/510)
• My modification to the above source code (http://darwin.bio.uci.edu/~cestark/roial/Distribution/source/DemonsRegistration.cxx)
• A supported C/C++ compiler (GCC, Visual C++, etc).

Steps to compile if you're really dead-set on compiling:
1. Download CMake (binary), ITK (source), and MedINRIA (binary)
2. Run CMake on ITK (follow ITK's directions), compile it ("make") and install it after compiling ("sudo make install" or build the "INSTALL" project in Windows). The install will place it somewhere like /usr/local/bin
3. Download the command-line Diffeomorphic Demons, run CMake on it, and compile it as-is ("make"). I'm not sure if there is a "make install" option, but for now you'll not want to do that in any case as you'll want to replace the existing code (DemonsRegistration.cxx) with my version and re-compile to enable some useful options. Then, stick this somewhere in your path.

Preparing Your Data

The first step is to draw the ROIs you wish to align. Each subject must have an ROI mask drawn and the values you paint into each ROI must be the same across subjects. It's these ROIs that will be aligned. You don't need to be obsessive about accuracy here as the alignment approach will have a smoothness constraint that will keep you from over-fitting jagged edges in your drawings. If you wish, you can do something like pass a 3D median filter over your drawings to clean them up. For example, here is a file that will call AFNI's 3dcalc to perform median smoothing of your ROIs. It's a good idea to start things roughly aligned. So, drawing an overlay on a structural that has already been put into Talairach or MNI space is a wise move. At the very least, get them roughly aligned. If you don't do so beforehand, you can do it in MedINRIA using their affine or manual alignment initially to bring things close enough for the Demons algorithm to work well.

Once drawn, get these into NIfTI (.nii) or Analyze (.img/.hdr) format (3D files only - no 4D files yet). You may also want to get your structurals and a statistical map in this format at the same time (with the same image dimensions, locations, etc.)

You're now set to do the alignment. If you've never done it before, you'll need to make a model. This can be a single subject or something else that you come up with (e.g., drawing on an average brain or on an atlas). Later on, you can create a model based on your post-aligned ROIs (e.g., by calculating the modal ROI label across subjects) that represents a central tendency and re-align everyone using this as the model.

Alignment can be done either in MedINRIA's graphical application ImageFusion or on the command line with DemonsRegistration.

Using MedINRIA's ImageFusion GUI

ImageFusion lets you register images, view the overlap, spin brains in 3D, etc. Registration can be done manually with landmarks, via an automated affine procedure, or via the Diffeomorphic Demons algorithm. We'll be using the latter. Fire it up and you'll see the main screen.

The first icon there will let you open up both the fixed (your model) and moving (your subject) ROI files. In addition, on the bottom, you'll see folder icons that let you load each one directly. Note, that currently, the OS X version has a bug in which several of the icons for the buttons disappear each time you click on them. One is already gone (to the left of the color gradient). We're in the "clicking moves the crosshair" mode (there should be a button with a pointer icon). But the buttons still work and you can hover over the areas to get the mouse-over help in case you get lost (hopefully this bug will be fixed soon). Anyway. load up your images. Don't worry if you can't see them all - it's just the brightness / contrast.

If you click on the color gradient button you can use the mouse to change the brightness / contrast. Clicking on the magnifying glass lets you move and zoom the image. You'll also want to know the Perform currently selected registration button (gears, third from left), the Reset all registration steps button (red X, 6th), and possibly the Update the displacement field according to the current state button in the main toolbar (distorted grid with green arrows, 7th). If you like, for visualization, you can colorize the ROIs with the "Color" pull-downs at the bottom of the screen. Colors, contrast, etc. aren't affecting the actual labels and only affect how you see things on the screen.

Now, it's time to align. Under Registration Algorithms, pull down Diffeomorphic Demons and you'll see the following:



By default, Use Histogram Matching is enabled and since we're working on ROI values and not grayscale structurals, we want this disabled. At this point, it's worth seeing what the current overlap looks like. It can be nice to add some color here. I've selected GEColor for both my moving and my fixed images from the pull-downs at the bottom. Above the display of your ROIs, you'll find tabs for Input Images, Image Fusion, and Displacement Field. Click on Image Fusion. On the left, in the Control Panel, click on the Fusion tab (you're currently on the Registration tab). Here, in the Fusion tab, I've selected Use Color Maps. It's not a bad idea to hit the Reset all registration steps (red X) icon here to make sure no transformations are being applied.

Use the Blend Opacity slider to slide back and forth between your two ROI maps. Here, I've got it set at 50% to show you both at the same time.



We can see here the overlap is pretty poor. Now, let's run the Demons algorithm and see how we do. Go back to the Registration tab if you need to change any parameters. Here, we'll just use the defaults (they work very well for us). Click on the Perform currently selected registration button (gears icon). On our Macs here, it takes under 30 seconds to run. Below is the resulting overlap:



A lot better, no?  Think your group fMRI analyses might benefit from this?

Next, let's save the information. Back on the Registration tab, you'll find the Load/Save Transformation section. The right-most button there will save the vector field you just calculated. Click on it and give it a name like "s1_displacement.mha". The ".mha" suffix there is required and that suffix determines the output format. I've found that while the GUI will let you use things like ".nii" files here, the command-line version crashed with ".nii" files but was fine with the ".mha" format (it's default file format).

At this point, you can apply this transformation to whatever files you like. For example, if you go back to Input Images, and use the Open a moving (source) image button (file folder icon) to load your structural, the transformation will be applied to the structural after loading. You can then save the transformed structural by pressing the Save the output image (brain with a floppy disk icon in the main toolbar) button and giving a name like "s1_aligned_struct.nii". Again, the suffix here (".nii") will determine the format (here, NIfTI). If you have a single 3D statistical map (e.g. a map of fit coefficients), you can load them and save the transformed versions the same way.

Once you're done with this subject, press the Reset all registration steps button (red X) to clear out the transformation or the next subject's ROI file will begin using this transformation (and that's probably not what you want).

While here though, one other thing you can do is to look at just what it did to transform this subject onto the model. If you click on the Displacement Field tab and then the Update the displacement field button (grid with green arrows), you'll see what the displacement field looks like. The top one is the easiest to visually parse - it shows an axial slice and how much L-R and A-P distortion was needed in that slice (if your in the cursor mode, things like the mouse scroll wheel will let you change slices). Here's what it did to this subject:

Using DemonsRegistration (command line)

The GUI is nice and will do everything you need it to (or mostly) but it has its limitations. First, if you to process a whole study with a lot of contrasts, you'll be spending a lot of time working with the GUI. Life would be easier if you could write a little script to batch process them all. MedINRIA lets you run this on the command line (see below) that gives you the ability to batch things. Second, you have only some of the options available to you for alignment. There are more tweaks you can do to the algorithm in the command-line version written by Vercauteren. Finally, if you want to look at the overlap of your ROIs across participants, you really would like to have the ROIs resampled using nearest neighbor interpolation so they keep their values.

The command-line tool gives you this control. Just run "DemonsRegistration" without any parameters and you'll get a list of the available parameters. Note that on breeds of Unix, you can use either "short" (e.g., "-e") or "long" (e.g., "--use-histogram-matching") parameter names whereas on Windows you can only use the "short" parameter names.

Example 1:

Let's say you want to run the same thing as the GUI, aligning "s1_ROI.nii" that is located in a directory called "s1" to "model.nii" in the current directory and save the output deformation field. You'd type:

DemonsRegistration -f model.nii -m s1/s1_ROI.nii -O s1/s1_ROI-field.mha -s 1.0 -a 2 -i 15x10x5

Unpacking this a bit we have:

• -f model.nii : Set the fixed image to model.nii in the current directory
• -m s1/s1_ROI.nii : Set the moving (source) image to s1_ROI.nii located in the subdirectory s1
• -O s1_ROI-field.mha : Save the transformation field as s1_ROI-field.mha in the subdirectory s1
• -s 1.0 : Set the deformation field smoothing parameter to 1.0 (the default in the GUI)
• -a 2 : Set the update rule to the Thirion rule (the only one available in the GUI)
• -i 15x10x5 : Set the number of iterations to 15, 10, and 5 for the 3 levels (default) used (the default in the GUI).

Example 2:

Let's say you want to do that same thing but now save the transformed ROI file using nearest neighbor

DemonsRegistration -f model.nii -m s1/s1_ROI.nii -O s1/s1_ROI-field.mha -s 1.0 -a 2 -i 15x10x5 -N -o s1/s1_ROI_aligned.nii

The only differences here are:

• -N : Use nearest neighbor interpolation for making output images
• -o s1/s1_ROI_aligned.nii : Save the transformed ROI map as s1_ROI_aligned.nii in the s1 subdirectory

Example 3:

Now let's say you want to apply that transformation field you made in either of the above examples to a structural dataset called "s1_struct.nii"

DemonsRegistration -f model.nii -m s1/s1_struct.nii -B 1 -b s1/s1_ROI-field.mha -o s1/s1_struct_aligned.nii

Let's unpack this:

• -f model.nii : Why the heck do you need this?  Well, you do. Someday I'll rewrite it so you don't but for now you need to give it a model that it will load and then ignore.
• -m s1/s1_struct.nii : Give it the file you want to transform
• -B 1 : When using the input field, don't just let this be a first guess, but actually use this field to warp the image
• -b s1/s1_ROI-field.mha : Give it the transformation field you created before
• -o s1/s1_struct_aligned.nii : Save the aligned structural

Notes

• Yes, you must give it a model even when you're applying a field and no, giving it won't make it use the model at all. Just do it and wait for me to edit the code more.
• I've only tried things with NIfTI and Analyze datasets.
• The above examples were hand-written and should be checked for typos.
• Known bug: On OS X (and probably Linux) systems, the -O flag will save the field, but not with the name you specify. It will take your output filename and append "-field.mha". I'll fix this soon.
• Known limitation: If using AFNI and bringing things back, AFNI will treat anything as a "+orig" dataset. You'll probably want to run "3drefit -view tlrc"
• The -a 2 parameter above uses Thirion's Demons and not Vercauteren's Diffeomorphic Demons. This is actually what the GUI in MedINRIA does as well. This doesn't mean the fields won't be diffeomorphic. You can run with the -v flag to turn on verbose input and look for a line at the end like "Minimum of the determinant of the Jacobian of the warp: 0.047512". If this is positive or only ever so slightly negative, don't worry. Things would still be invertible or nearly so. If this goes well negative (e.g., -2.84213) you're getting a bit wonky in the fields you're making. Thirion's rule is more prone to wonkiness but also does a better job on the ROIs. It's pretty bad (aka very wonky) on grayscale MRI images with the default settings. You have trade-offs you can make between accuracy of the ROI alignment and smoothness of the transformations. When working on our MTL ROIs, the fields are smooth and diffeomorphic with the default GUI parameters (noted above) and do an excellent job. It's worth examining your fields (or visually examining the deformed structural) to make sure things aren't getting too odd.

Using MedINRIA's ImageFusion via the command line

(Added July 1, 2008)
ImageFusion can be controlled from the command line as well. If you're on a Linux box or a Windows box, just put the executables into your path somewhere. If you're on a Mac, you'll need to start off by grabbing the "MedINRIA" executable itself and putting it somewhere in your path. For example, you might type "sudo cp /Applications/MedINRIA/MedINRIA.app/Contents/MacOS/MedINRIA /usr/local/bin". Once that is done (or just for now get into the directory with MedINRIA), type:

MedINRIA -mod imagefusion -help

This will show a list of available options. So if we want to replicate Example 3 from above we would run:

MedINRIA -mod imagefusion -f model.nii -m s1/s1_struct.nii -d s1/s1_ROI-field.mha -o s1/s1_struct_aligned.nii

Likewise, you can calculate the fields themselves and save them to do your initial alignment as in Example 1:

MedINRIA -mod imagefusion -f model.nii -m s1/s1_ROI.nii -r diffeomorphic -o s1/s1_ROI_aligned.nii -od s1/s1ROI-field.mha

For most purposes (e.g., if you want to simply batch process a series of images using fields you have generated), this tool will work just fine. Note, however, that it does not let you specify details about the algorithm found in the GUI much less those found in the command-line DemonsRegistration tool.


Questions or comments?  E-mail me (%cestark%@%uci%.%edu - without the %'s of course...)

Text and images Copyright Craig Stark, 2008

• About Us > 
• ROI-AL >