caret: plot a NIfTI image

Ah, Caret. Such beautiful images, such a learning curve. In the hopes of saving others some frustration, this tutorial shows how to use caret to make a nice image out of a nifti file - the nifti made in the previous post and available for download here. I'm using caret version 5.65, Jan 27, 2012.

downloading

The first step is to get caret and an anatomic template. I had no difficulty registering then downloading the files from the download page; my only confusion was that you do not (at least on Windows) need to install the program: you simply unzip it to wherever you want it to sit on your hard drive, then double-click the exe to start the program. Specifically, I unzipped the caret download to d:/caret/, so start it by double-clicking d:/caret/caret/bin_windows64/caret5.exe in the file explorer.

But, to do anything useful we need to download an atlas, not just the program. A caret-saavy coworker suggested that the atlas_Conte69_74k_pals is appropriate for displaying my SPM8-then-R-manipulated MNI-normalized files. The interface is rather unusual, but you should be able to download that atlas on this SumsDB page. Make sure you get the set that is made for caret 5, not the Workbench. The download is a zip archive containing a bunch of files. I expanded the zip into d:/caret/atlas_Conte69_74k_pals/; make note of where the files are unzipped.

getting a blank brain

Start up caret (double-click or whatever, as explained above). On my windows box it first opens a little dos window, then a GUI with a picture of caret's friendly carrot. Now we need a blank brain to put the nifti image's clusters onto. The example nifti is aligned to the MNI template, SPM8-style, so we can tell caret that when we're loading in the blank brain.

In caret, select File, then Open Spec File ... Navigate to the place where you put the atlas_Conte69_74k_pals files, and select pals.L.atlas.74k_pals.spec. Note the .L. in the middle of the filename: we're loading the left hemisphere blank brain only. To get the right, do the same steps, but pick the .R. file. It's ok that the nifti has both hemispheres, if all goes well, caret will put the correct clusters onto the correct hemispheres.

Now another window pops up. This lists some of the things that are linked (or whatever) to the .spec file we just opened. There are a few things that need to be set in this big window: which blank brains to load (flat, inflated, fiducial) and the atlas space we want to use.

In this case, the nifti image is MNI, so I set the Space box to SPM5 (it doesn't have an SPM8 option but SPM5 is compatible). Then, check the boxes in the Coordinate Files spot for the blank brains you want to have available. In the example here, I picked all of the Conte69 ones except FLAT, because I don't want to see a flat map. Now click Load.

With luck, the option screen will disappear and you will see a blank brain in the main caret window, as below.

changing the main viewing window

The main viewing window has buttons to rotate the brain, whether it is blank or has blobs mapped on.

The basic ones are circled at left. Clicking the little M L A P etc. buttons causes the brain to rotate to particular views - I clicked the L ("lateral") button to have the side view shown here.

The "Model" dropbox lets you pick which blank brain you want to see - how inflated. In this screenshot we are looking at the FIDUCIAL model - the most "bumpy" one in this set of blank brains. Change the model to INFLATED or VERY INFLATED to see inflated models. Note that these are the maps we picked by selecting the check-boxes on the previous screen (above picture - the screen that appears when you load a .spec file).

overlaying a NIfTI image

Now that we have the blank brain we can put our clusters on it. I'm assuming here that we have the clusters in a properly-formatted image file - that the header information with the orientation information has been set correctly. I'm also assuming that we indicated the space matching our nifti when we loaded the blank brain.

1. In the caret window, click Attributes, then Map Volume(s) to Surface(s).
2. Leave "Data Mapping Type" as "Metric (Functional) or Surface Shape Data" and click Next.
3. Click the "Add Volumes From Disk ..." button and navigate to the image you want to overlay, such as fakeBrain.nii.gz. After you select it, its name will appear in the big white box with the word FILE. Click the Next button.
4. In the next window ("Spec File and Surface Selection") click the "Map to Caret ..." button, then OK in the little window that pops up. Now the big white box should say "Caret (1 surfaces)". Click the Next button.
5. Click the Next button on the "Data File Naming" screen without changing anything.
6. Select "METRIC_INTERPOLATED_VOXEL" on the "Mapping Algorithm" screen, then click the Next button.
7. Click Finish then Close.

The big window will disappear, showing the blank brain in the caret window again ... and it's still blank. Don't panic: caret doesn't show the blobs until you tell it to.

Click the little D/C button in the main caret window (to the right of the buttons that rotate the image). This brings up a big "Display Control" window.

Select the "Overlay/Underlay - Surface" page (like in this screenshot) if it didn't open to that page.

Set the "Primary Overlay" "Data Type" to "Metric" (as highlighted in green). This should cause the "Display Column" and "Threshold Column" boxes to automatically have the name of the image we loaded - fakeBrain.nii.gz. Click the "Close" button to close the window.

If following these steps, you should now see a colorful group of voxels on the medial wall of the template (click the "M" button in the viewing window to rotate). The "Metric Settings" page of the "Display Control" window lets you adjust the scale, set a different palette, and show a color key.

comments

If you select an image as the Primary Overlay in the Display Control but no blobs appear, check that the orientation information is set properly in overlay image, such as by opening up the image in another program and checking if it is orientated as expected. Caret won't necessarily make error messages when it can't determine where to put an overlay.

Caret has many, many more features than those used in this tutorial. Some of the options chosen here may not be suitable for your data; be sure you check the images to confirm the clusters appear in the expected locations.

UPDATE (20 September 2013): directions for creating this overlay in the Connectome Workbench (successor to caret) are posted here.