Freesurfer Recon_all Quality Assurance and Resubmission

This script needs to be run for all participants once the dicoms have been successfully converted. It will submit recon-all jobs that will begin the Freesurfer cortical surface reconstruction process. We use these outputs later in the preprocessing scripts and it takes a long time so it is important to start this step as soon as we can.

First you'll need to navigate to the following directory: /home/data/madlab/scripts/freesurfer_scripts

In this directory you'll find three files that are essential for the dicom conversion process:

    1) run_recon.py
    2) run_recon_afterEdits.sh

1. In the run_recon.py file you need to use the vi editor to change the value of the 'sids' list variable to correspond to the subject ids for the specific experimental paradigm that is being worked on (e.g., WMAZE_001 or 783126). You'll also need to change the 'base_directory' of the datasource node in the nipype script to reference where the specific study related data are located following the dicom conversion (Make sure you are in the correct environment)

Once these two things are changed you can submit the jobs to the queue via the LSF scheduler with the following command from the /home/data/madlab/scripts/freesurfer_scripts directory:

bsub -q PQ_madlab -e /scratch/madlab/crash/reconall_err -o /scratch/madlab/crash/reconall_out < run_recon.py

This command is typed on the command line of the terminal window. It sends the job to the PQ_madlab queue (-q), it outputs an error text file called reconall_err to the /scratch/madlab/crash directory, it outputs an output text file called reconall_out to the same directory and you are specifically submitting ('<') the run_recon.py script.

TAKES ~7-8 HOURS PER PARTICIPANT TO RUN...SOMETIMES LONGER!!!

Once the recon-all job has finished (without any errors) navigate to the appropriate directory to make sure all of the directories and files are there. Type on the command line (make sure you have the correct project environment loaded):

        `cd /home/data/madlab/surfaces/{PROJECT NAME}
        ls`

You should see a bunch of directories that are named the subject ids. If you 'cd' into a single participant's directory you should see the following directories: bem label mri scripts src stats surf tmp touch trash

If you 'cd' into the scripts directory you'll see a bunch of files...you are looking for the recon-all.log. if you use the cat (or less) command to look into that file: (eg., cat recon-all.log) you want to see the following text at the very end:

      `Started at Mon Jul 27 13:12:12 EDT 2015 

       Ended   at Mon Jul 27 19:23:55 EDT 2015

       #@#%# recon-all-run-time-hours 6.195

       recon-all -s IRC04H_18F004 finished without error at Mon Jul 27 19:23:55 EDT 2015`

If you find that message at the end of the log file, with the text "finished without error" then you can take a look at how well Freesurfer did in constructing the surfaces. To do this you need to use the following Freesurfer command line argument tkmedit. To use this type on the command line the following (!!careful you need to have the appropriate project specific environment loaded!!).

tkmedit {SUBJECT ID} brainmask.mgz -aux T1.mgz -surfs -aparc+aseg

replace {SUBJECT ID} with the relevant subject ID (e.g., IRC04H_18F004)

It is best to do this on a terminal opened on a visualization node(https://hpcportal.fiu.edu/enginframe/vdi/vdi.xml?_uri=//vdi/login). To see how to start a visualization node and/or get the related software onto your computer see: http://ircc.fiu.edu/visualization/

Once you have typed the above command this will launch two GUIs that looks like:

IMPORTANT IF EDITS ARE DEEMED NECESSARY AFTER LOOKING AT THE FILES. COPY THE ORIGINAL DIRECTORY AND FILES IN CASE IN THE EDITING PROCESS THINGS GET CORRUPTED. TO DO THIS TYPE:

cp -r {ORIGINAL DIRECTORY NAME} {ORIGINAL DIRECTORY NAME UNDERSCORE ORIG} FOR EXAMPLE: cp -r IRC04H_15F001/ IRC04H_15F001_ORIG/

---

The red line in the picture corresponds to the pial boundary and should be on the boundary of grey matter and CSF. If it goes beyond the grey matter and includes what is clearly non-brain (i.e., SKULL or MENINGES) you'll need to use the delete voxel tool to remove problematic non-brain from your brainmask.mgz file.

The yellow line in the picture corresponds to the white matter boundary and should be on the boundary of the white and grey matter. If the yellow line does not make it up to the white matter boundary you'll need to add control points and re-run the analysis.

REVIEW THE FREESURFER BIBLE TO BETTER UNDERSTAND HOW TO MAKE EDITS AND NAVIGATE THESE TOOLS.

2. If edits (e.g., brainmask.mgz voxel deletions or control points were added) then the run_recon_afterEdits.sh file will need to be edited with the vi editor. This script is a bash script that iterates via a for loop over the subjects sending things to the queue. You will need to uncomment (aka REMOVE THE # from in front of the cmd line) for the command that corresponds to the types of edits that were made (e.g., pial edits, WM edits, or both pial and WM edits). Once you've done this and changed the subject id to the correct subject id that is being resubmitted exit the script and submit it to the queue using the following command.

bsub -q PQ_madlab < run_recon_afterEdits.sh

This will take a while to run too. Once it has finished re-check the parcellation and cortical surface reconstruction via the tkmedit tool described above. Continue to do this until the boundaries and labels are correct. Once the QA process is complete and everything looks good with the surfaces and labels note this in the project spreadsheet and delete the copied (_orig) directory.