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.
Here are the major steps:
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:
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
On command line, simply type
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
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.
surf directory in
FS015 and launch Caret, e.g.,
$cd FS015/surf $caret5 &
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
Scene Files section. Scene files are really handy to save visualization settings in Caret. Then click
D/C button on the main window), navigate to
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).
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).
Apply button on the
Draw Border Update box.
Draw Border Update box is active, you cannot rotate the surface in the main window, but you can use the arrow keys to rotate.
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
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).
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:
Run the script simply by typing
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,
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.RIGHT_HEM.73730.topo files for the left and right hemispheres. This will create a caret directory inside the subject directory (e.g.,
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.