Autorecon1

From CCN Wiki
Jump to navigation Jump to search

The first step in Freesurfer data processing is brain segmentation and skull-stripping. Remember, if you already know that this will complete without errors for your dataset, you can use the -all flag, instead of the -autorecon1 flag, to complete all the autorecon steps without pausing in-between.

Stage 1a: Skull Stripping

Calling recon-all with the -autorecon1 flag performs a number of steps related to segmenting the anatomical MRI image into brain/non-brain voxels. A shell script called autorecon1.sh can be found on the ubfs Scripts/Shell folder. This script simply acts as a wrapper (i.e., a convenient shortcut for executing computer code that might have a bunch of parameters that are error-prone or annoying to have to specify). You can copy this script to your ~/bin directory to be able to run it yourself: 

cp ~/ubfs/cpmcnorg/Scripts/Shell/autorecon1.sh ~/bin/

Before you run the script, be sure to first open it up in a text editor so that you can: 1) see what it's actually doing, and 2) modify it so that it matches your particular requirements: 

nano ~/bin/autorecon1.sh

If you do so, you will find that it sets some environment variables that you will want to change, such as your $PROJECTROOT The autorecon1.sh script I most recently used contains the following: 

#!/bin/bash
# Usage: autorecon1.sh <subjectid> <timepoint>
# e.g., autorecon1.sh 501 T1_

PROJECTROOT=~/ubfs/cpmcnorg/openfmri/booth/ #Change this: where are your data located?
OLD_SUBJECTS_DIR=${SUBJECTS_DIR} #Your subjects directory might be initially set to something else
SUBJECTS_DIR=${PROJECTROOT} #now tell freesurfer where the subject in question resides
export SUBJECTS_DIR
echo SUBJECTS_DIR: ${SUBJECTS_DIR}

subjectID=$1
timepoint=$2
recon-all -autorecon1 \
  -i ${SUBJECTS_DIR}/${subjectID}/mri/${timepoint}MPRAGE.mgz \
  -subjid FS_${timepoint}${subjectID}

SUBJECTS_DIR=${OLD_SUBJECTS_DIR} #reset subjects_dir to whatever it was before
export SUBJECTS_DIR

As the comments indicate, this script would be run as follows: 

autorecon1.sh 501 T1_

It takes 2 parameters, a subjectid (e.g., 501) and a timepoint (e.g., T1_), which is intended for use with the longitudinal booth lab reading data. Naturally, you should modify your copy of the script to suit the data you will be working on; for example by changing the PROJECTROOT variable.

When operating on data stored locally on either wernickesarea or brocasarea, this step takes between 20 and 30 minutes to complete. At the other extreme, operating on data stored on the ubfs network drive using the accumbens micro-computer took 2:18 hours to complete. However, note that this step can be run remotely via ssh, even from the comfort of your own home. If you are not physically seated at either of the main workstations, it is recommended that you use an ssh terminal connection into one of those two computers and run this step that way: 

nohup autorecon1.sh 501 T1_ &

The nohup directive tells linux to keep the program going, even if you log off. That way your computer isn't held hostage over the internet while you wait for the skull stripping step to finish. Be sure to add the ampersand character to the end of your command.

If you're running multiple subjects, you may want to send your output text to separate logs, e.g.: 

nohup autorecon1.sh 501 T1_ > 501_T1.out &

Batch Processing batchrecon.sh

The following script will automate autorecon1/autorecon2 across a directory containing many subject files. 

PROJECTROOT=/home/.../.../ #Change this: where are your data located?
SUBJECTS_DIR=${PROJECTROOT} #now tell freesurfer where the subject in question resides
ls -1 -d */ | sed "s,/$,," >  subjects
for SubjectName in `cat *subjects*`; do 
 	recon-all -autorecon1 -autorecon2 \ #replace autorecon1/autorecon2/autorecon3 with desired recons
	   -i ${SUBJECTS_DIR}/$SubjectName/mri/MPRAGE.nii.gz  \ #use .mgz where applicable
	   -subjid FS_$SubjectName
done

Running multiple MPRAGE files

Running autorecon1 with multiple MPRAGE files is one way to help the program separate out important matter. There are a few ways to do this, each with increasing confidence. The first way is to run two MPRAGE files or MPRAGE and a T2 file. The second is to run two MPRAGE files and a T2 file. Finally, you can repeat the last step but use the modified MPRAGE file discussed ##LINK here.

  1. Running with two MPRAGE files
    • First, put the two MPRAGE files (one from SESS 1 and 2) in the mri folder. Name the one from session one MPRAGE_SESS_1 and the other MPRAGE_SESS_2.
    • Make sure these are *.mgz files (see Slicer).-
    • In a terminal, run recon-all -autorecon1 -subjid FS_<subjectID> -i <path to MPRAGE_SESS_1> -i <path to MPRAGE_SESS_2>.
  2. Running with an MPRAGE file and a T2 file
    • First, put the MPRAGE file and T2_3D in the mri folder.
    • Make sure these are *.mgz files (see Slicer).-
    • In a terminal, run recon-all -autorecon1 -subjid FS_<subjectID> -i <path to MPRAGE_SESS_1> -T2 <path to T2_3D file>.
  3. Running with two MPRAGE files and a T2 file
    • Combine steps 1 and 2.
    • In the terminal, run recon-all -autorecon1 -subjid FS_<subjectID> -i <path to MPRAGE_SESS_1> -i <path to MPRAGE_SESS_2> -T2 <path to T2_3d file>
  4. Running with all four modifications
    • If this doesn't work, control points are basically the only option.
    • Create the sliced.nii for MPRAGE_SESS_1 file using the steps outlined #LINK here.
    • In a terminal, run recon-all -autorecon1 -subjid FS_<subjectID> -i <path to sliced.nii> -i <path to MPRAGE_SESS_1> -T2 <path to T2_3d file>.
    • You could also probably run the code with 2 modified MPRAGE files for extra assurance.
    • As stated above, if this doesn't work, you'll have to resort to control points (or, worst case scenario, throwing the brain out!).

Stage 1b. Brain Mask Editing

The skull stripping stage creates a mask that identifies which voxels correspond to the brain and which do not. In this mask, all voxels that are not part of the brain are set to 0, and those zero-values can be used by later steps to select the voxels to map into surface space.

Unfortunately, because voxel identity is determined algorithmically, sometimes the process breaks down. For example, there is generally a gap surrounding the brain (the cerebrospinal fluid in which the brain floats) which can be used to help identify where to make the partition. However in some regions, this gap may be smaller than the width of a single voxel, and in these cases the gap might not be detectable, and the algorithm might decide that a brain region continues into voxels that are actually part of the skull. For this reason we manually inspect the anatomical image with the brain mask overlaid. We can use Freesurfer tools to tweak the mask to exclude these errors.

You would check the success of this step by overlaying the brainmask on the T1 (anatomical) image in a program called tkmedit. The masked-out voxels (i.e., the ones you want to exclude) appear as black in the mask, and the background T1 voxels remain visible. If the skull-stripping is successful, you should not see any of the background skull in the overlay because these voxels will be covered-over with black. In the (likely) event that some non-brain voxels made it through, you will use tkmedit to modify the brainmask image so that these stray non-brain voxels are excluded. Unfortunately, you have to first complete the autorecon2 step to generate the surfaces in order to overlay them. Thus, this step might properly be labeled step 2b.

If you have only completed autorecon1:

tkmedit FS_T1_501 brainmask.mgz -aux T1.mgz


If you have already completed autorecon2:

tkmedit FS_T1_501 brainmask.mgz -aux T1.mgz -surfs

A description/tutorial on brain mask editing in tkmedit can be found here.

If there's a bit of dura left in the image, you might run the gcuts step 

recon-all -skullstrip -clean-bm -gcut -subjid <subjid>

and then inspect 

tkmedit FS_T1_501 -segmentation brainmask.gcuts.mgz -aux T1.mgz -surfs

I tried this on one participant, and found the gcuts were too aggressive. Unfortunately it's an all-or-nothing option.

Quick Brain Mask Editing Using SPM and MRICron

If there are just a few slices where the brain mask includes skull or dura, then we would probably edit the brainmask.mgz file using tkmedit. Sometimes, however, even the above steps using more aggressive watershed parameters or using the -gcut switch fails to get the job done, leaving large chunks of non-brain voxels. The following approach takes advantage of SPM's segmentation tools, which generate separate volumes for WM, GM, and other tissue. This procedure entails 3 general steps: Segmentation of the MPRAGE in SPM12, generating a mask out of the segmented files, and applying the mask to the brainmask.mgz file in MRICron.

SPM Segmentation

The first step requires you to copy the MPRAGE that FreeSurfer was operating on into a new working directory. In my home directory I have created a new subdirectory called ~/fix for this procedure: 

SUBJID=FS_0238
mkdir ~/fix
cd ~/fix
mkdir $SUBJID #subject gets own subdirectory under 'fix'
cd $SUBJID 
mkdir orig #for the sake of ease, the MPRAGE will go into an 'orig' subdirectory
cp $SUBJECTS_DIR/$SUBJID/mri/orig/001.mgz ./ #copy the target MPRAGE file to the working directory
mri_convert 001.mgz 001.nii #Convert .mgz file to .nii so SPM can read it

Next, if you don't already, you will need a copy of the mri_fix_script.m script in your fix directory. You can find this file ubfs/Scripts/Matlab.

Edit: LIES! Script is not there. Also the one I am using here has a bug. There must be multiple versions.

Once you have a copy of it, open it up in MATLAB to modify it to match your particular files: First, modify line 161 to match the location of your fix directory: 

CCN.root_dir = '/home/chris/fix';

Change the directory to match your own directory location. Likewise, the working directory will need to be changed (line 168) to the same location: 

CCN.work_dir = '/home/chris/fix';

A couple lines down (line 171) is the list of subject IDs. Change this to match your subject folder names: 

CCN.all_subjects = {'FS_0238'};

That should be all the changes required. This script will work on wernickesarea, brocasarea and accumbens. It is run in MATLAB, and requires everything under /opt/spm12 and /opt/northwestern to be in your path (see Chris for his copy of startup_spm12.m). If these conditions are met, you should be able to run it from your ~/fix directory: 

mri_fix_script

The script should run for about 15 minutes, and you'll know almost right away if it's working if you start seeing MATLAB plots of error values. If it crashes before you see any such plots, ask for help. Otherwise, you can expect the script to crash right about at the time it attempts to realign functional runs (which are missing from the directory), but by that point, the script has done everything we need. If it worked, you should have the following files:

  • fix
    • SUBJID
      • orig
        • 001.mgz
        • 001.nii
        • 001_seg8.mat
        • c1001.nii
        • c2001.nii
        • c3001.nii
        • c4001.nii
        • c5001.nii
        • m001.nii
        • y_001.nii

c1001.nii is the gray matter segmentation, and c2001.nii is the white matter segmentation.

Mask Manipulation

The next step is to slightly dilate the WM definition, by smoothing (I tried in the i axis below, seemed to work) 

3dcalc -a c2001.nii -b a+i -c a-i -expr 'step(median(a+b+c))' -prefix smWM.nii

Then we can merge the dilated WM and the GM images into a binary mask: 

3dcalc -a c1001.nii -b smWM.nii -expr 'notzero(a+b)' -prefix GMWM.nii

Mask Application in MRICron

We will now apply our mask to the brainmask.mgz file generated by recon-all. Copy brainmask.mgz from the FreeSurfer $SUBJID/mri/brainmask.mgz to your fix/$SUBJID/orig directory. 

cp $SUBJECTS_DIR/$SUBJID/mri/brainmask.mgz ~/fix/$SUBJID/orig

Launch MRICron. From the File menu, load the brainmask.mgz file. Next, from the Draw menu, select Open VOI..., and find the GMWM.nii mask file (the file won't be visible in the window until you change the file format filter from Volume of interest (*.voi) to Neuroimaging. You should now see the voxels included in your mask with a red overlay. Finally, we can delete the nonsense voxels by selecting Draw>Mask image with VOI > Preserve regions within VOI. Save your modified brainmask (File>Save as NIfTI...).

Mask Conversion and Copying

We need to convert our modified brainmask.nii file back to .mgz format, once again using mri_convert 

rm brainmask.mgz #delete the unmodified .mgz file
mri_convert brainmask.nii brainmask.mgz #convert the modified .nii file to .mgz format

Finally, copy the modified brainmask.mgz file to the FreeSurfer subject directory, overwriting the original (you might first make a backup copy of the original brainmask.mgz if you want to play it safe).

Retrieved from "https://ccn-wiki.caset.buffalo.edu/index.php?title=Autorecon1&oldid=2095"