Caret

The most common way to average data across subjects would be to transform all subject's functional data to a standard space (e.g., Talairach space). An alternative (and better) way to average would be to use surface-based registration, which aligns different subject's anatomy according to major landmarks of the cerebral cortex. There is a way to do this in MLR using Caret that allows users to average certain type of data (overlays, ROIs) across subjects after spherical registration. This page documents the procedures of this process.

• FreeSurfer software link
• Caret software link
• Download Caret's Freesurfer_to_PALS-B12 Pipeline Distribution here (scroll down to the bottom of page)
• Basic familiarity with the Caret GUI interface and file types (go through some tutorials).

Here are the major steps:

1. Use FreeSurfer to do segmentation and surface reconstruction
2. Run the preborder script to import FreeSurfer surface to Caret and auto-landmark
3. Manually fix the auto-landmarks to conform to guidelines
4. Run the postborder script to do spherical registration
5. Import the aligned surface to MLR

NB: The pipeline scripts were developed by Donna Dierker, Caret's main program analyst, in late 2009. The one tested at MSU (Taosheng Liu's lab) are beta versions of these scripts. This document was written based on these beta scripts but they final version should work too (and possibly better). If not feel free to email me (Taosheng Liu) or the Caret email list (Donna is terrific in helping others).

We use FreeSurfer for segmentation/surface reconstruction from volume anatomy (MP-RAGE) data. One can also use Caret to do this. However, Caret requires more manual intervention (e.g., manual fixing of topological errors during surface optimization), while FreeSurfer can do everything pretty much automatically. This particular way to do things are endorsed by the Caret team, because of the convenience of FreeSurfer surface engine. It is entirely possible to do everything in Caret. Consult the Caret tutorials on how to segment/surface recon in Caret. To generate surface from volume data using FreeSurfer, run the recon-all command:

$recon-all -subject FS015 -i S01520091009+13-mprage_1mm_iso_20.83_bw.hdr -all

Come back in ~24 hrs, you will find a directory named FS015 that contains all FreeSurfer files. This directory will reside in fmri/anat/ (the environmental variable specified by SUBJECTS_DIR, which is set up by FreeSurfer).

The preborder script does the following things:

1. Import FreeSurfer surface to Caret. The FreeSurfer surface in the native space is transformed first to the MNI space (kind of Talairach transform, although in this case auto-Talairch, i.e., no need to define AP,PC, … points), then from MNI to 711-2B, which is Caret's atlas space. Quite cumbersome, I know, but there're just too many standards in this field .
2. Resample the surface to the 73730 nodes. Turns out FreeSurfer generates surfaces with many more nodes than Caret. All Caret surfaces have 73730 nodes per hemisphere and all spherical registration parameters are optimized for this node density, so it is necessary to downsample.
3. Automatically draw landmarks for spherical registration. This is really cool, Caret can guess (largely correct) the location of the six landmarks. So all you need to do is to tweak them later, instead of drawing from scratch.
4. Generate a html report so you can easily inspect the result.

Tip: It is hard to debug shell scripts. Two things to know: there's a debug flag at the beginning of the script set -x. It prints out the actual command being, useful to know where you are in the script. Once the script runs smoothly, you can turn it off (by adding # in front). Also, watch out for error messages when running, and stop the script (ctrl-c) as soon as you spot one (otherwise it keeps running and prints out many error messages). You need to take care the first error message, then repeat, etc.

Use a text editor to edit the script to customize to your particular setup/needs. All site specific information is at the top of the file.

Near the top of the file:

DIRLIST=/tmp/dirlist.$$.txt
cat > $DIRLIST <<EOF
FS015
EOF

FS015 is the FreeSurfer directory in this example. You can also process more than one subject's data at once, by adding the names of additional directories (each on a new line before the ending EOF).

• FREESURFER_DIR: where FreeSurfer is installed
• CARET_DIR: where Caret is installed
• ATLAS_DIR: where the Caret atlas directory is located
• HTMLDIR: where the output for checking results will be saved

On command line, simply type

$./preborder.sh

This script should be at the same directory level with the input directory (FS015). After a few minutes (and many screen ouput), it's done. If you see any error message you should just stop the program (Ctrl-C) and try to debug (hopefully this doesn't happen). You will likely see some warning messages, which are Ok. This script generates many Caret files in the FS015/surf/ directory.

If the script finished without error, you should be able to see the result by opening the views.html file in HTMLDIR. It has many useful views of the output (haven't figured out how to post this html yet).

Although the auto-landmark does a (very) decent job, the borders are (far) from perfect and still need to be cleaned up. The standard reference for drawing the landmarks is the Core 6 Landmark Set. Definitely study this page; this is the one and only guide to do this critical step.

Now you actually have to use Caret so it is necessary to know some basics. It is highly recommended to go through one or two Caret's introductory tutorial first if you haven't used it before.

Here are the steps to fix the autolandmarsk.

• Change to the surf directory in FS015 and launch Caret, e.g.,

  $cd FS015/surf
  $caret5 & 

• Open the spec file. After launching Caret, a Choose Spec File dialog pops up asking you which spec file to open. Choose something named like Human.FS015.R.73730.spec. A second dialog pops up asking you which files to open (the spec file is simply a file containing names of many other related files). Take the default but also select Human.FS015.R.LandmarkCheck.scene under Scene Files section. Scene files are really handy to save visualization settings in Caret. Then click Load.
• Open the Display Control setting (click D/C button on the main window), navigate to Scene, select Medial View of Landmarks, and click Show Selected Scenes… button. An error message might pop up, ignore and close the Display Control window. Now you should see something like this (Caret running on Ubuntu Linux).

• The first (primary) window shows a “very inflated surface”, this is a nice surface to draw borders on. You should see some borders already drawn–this is the result of auto-landmark. Viewing Window 2 contains a folded surface, which is useful for checking the location of borders with respect to sulci/gyri. Viewing Window 3 shows surface and volume together, can be used to check segmentation quality (although you should probably checked it already in FreeSurfer).
• Now touch up the auto-drawn landmarks. Go to “Layers:Borders:Draw Border Update” from the menu and a dialog box pops up. Here you can either erase, extend or replace segments of a border. Use the Core 6 landmark set as the guideline of how to modify the borders. Some tips I found in using this:
  • When you first start modifying the borders, you need to click Apply button.
  • Select Mode and start drawing by moving the mouse while holding down the left button. Finish drawing by releasing the button, and then Shift-click again. Caret is smart enough to figure out which borders you are fixing based on where you clicked (really neat feature).
  • To cancel a particular segment you just drew, instead of Shift-click, click the Apply button on the Draw Border Update box.
  • Draw on the very inflated surface but also view the folded surface (all the windows are synced) to get an idea of where you are drawing.
  • When the Draw Border Update box is active, you cannot rotate the surface in the main window, but you can use the arrow keys to rotate.
  • Many of the guidelines from the Core 6 landmark set refer to distance measures. To measure distance, close the Draw Border Update box, click on a point on the surface. This brings up a Identify Window with information about the node where you just clicked, then click another point. Now it shows the information of the new node, along with a distance (in mm) from the last clicked node. You can erase the green points by clicking CID button.
  • If you need to modify the aSTG landmark (the pink one), it might be easier to draw on the spherical/ellipsoidal surface, since it sits on the ridge and small deviation from the ridge might lead to a large deviation in 3D.

• Save border files. After you're happy with the result, go to File:Save Data File (or Ctrl-S), and select “File Type” to be “Border Projection Files (*.borderproj)”. Change the name to something like Human.FS015.R.LANDMARKS.borderproj (do not save it as *bvo*; those are something else, I think). Agree to overwrite the old file with the same name.

For full description always consult the official Caret guideline. Here's just a “cheat sheet” for distance measures and polarity (A: anterior, P: posterior, I: inferior, S: superior).

• Medial wall dorsal: A→P
• Medial wall ventral: P→A, gap between two medial walls: ~19 mm frontal junction, ~16 mm calcarine junction
• Calcarine: P→A, ~24 mm to occipital pole
• Central sulcus: I→S, ~19 mm above sylvian fissure margin, ~18mm to medial wall
• Sylvian fissure: P→A
• Superior temporal sulcus: P→A

NB: polarity is not an issue if you modify auto-landmarks as described above. But if you draw by hand (sometimes the auto-landmark fails so drawing by hand would be necessary), pay attention of where you start.

After saving the fixed border, you are ready to run spherical registration. This is done by the postborder.sh script. You need to edit the following:

• Subject directory (e.g., FS015), same as in preborder.sh
• ATLAS_DIR: Caret's atlas directory, same as in preborder.sh

Run the script simply by typing

$./postborder.sh

This script generates files in the subject's surf directory (e.g., FS015/surf), as well as the ATLAS_DIR.

Put the script check_reg.sh in ATLAS_DIR. The only thing you need to customize is to make sure the HTMLDIR exists on your system. Then run it,

$./check_reg.sh

You might also need following files: “sanity.scene” “Human.colin.RIGHT.RegToPALS_B12.FLAT.CartSTD.clean.73730.coord” (These files have been included in the PALS_B12.LR directory).

This script will generate a html file in HTMLDIR that shows all subjects in ATLAS_DIR. It should show something like this (I'm forgetting what it shows exactly).

A bad one may look like this: (due to polarity reversal of the SF landmark)

Now we can load a Caret atlas surface and view maps in the atlas.

This step import the Caret atlas surfaces into the OFF format, so MLR can use them. Start Matlab and run mlrImportCaret without any arguments from inside the subject directory (FS015). Make sure you have run mlrImportFreeSurfer so that there is a SurfRelax directory in FS015. It will ask you at some point to choose the topo files for the atlas brain. Choose the Human.sphere_6.LEFT_HEM.73730.topo and Human.sphere_6.RIGHT_HEM.73730.topo files for the left and right hemispheres. This will create a caret directory inside the subject directory (e.g., FS015/caret).

You may also need Human.PALS_B12.LEFT(RIGHT)_AVG_B1-12.FIDUCIAL_FLIRT.clean.73730 Human.PALS_B12.LEFT(RIGHT)_AVG_B1-12.INFLATED.clean.73730 Human.PALS_B12.LEFT(RIGHT)_AVG_B1-12.VERY_INFLATED.clean.73730

Now go to a MLR session and launch mrLoadRet. From the GUI, go to File/Base Anatomy/Import surfaces. You should go look for the caret directory that was generated (e.g., FS015/caret) and click on leftAtlasVeryInflated.off. Then set up the dialog to look like this:

Make sure the coords look like they are in the right place (click the 'anatomy' button in the above dialog box). It should be a midcortical surface, like this:

After importing, you can see the very inflated Caret atlas surface. Here's a screen shot of retinotopically defined V1 on the native inflated surface (left) and on the atlas surface (right). Looks pretty nice, doesn't it?

After importing, you need to save the veryInflated atlas surface to the Anatomy directory in each session. In the GUI, while viewing this surface (separately for left and right hemispheres), go File/Base anatomy/Save. Now you can combine overlays and ROIs across subjects based on the spherical registration.

The main function for combination of overlays is mlrComputeAtlasMean, it gets run in the experiment directory. For more on it's options, take a look at the help for that function. This function can average both overlays and ROIs (useful for looking at ROI consistency across subjects) in the atlas space.