Autorecon1

From CCN Wiki
Jump to navigation Jump to search

The first step in Freesurfer data processing is brain segmentation and skull-stripping.

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 &

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 mMPRAGE 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 binary mask that identifies which voxels correspond to the brain and which do not. By binary, I mean to say that it is a 3D block of 1's and 0's: Every location in this block that the previous step has determined contains brain matter gets a 1, and everywhere else gets a 0.

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.

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.