Analisis de datos con freesurfer

ls sub-112/ses-BL/anat

FreeSurfer Tutorial #3: Recon-all

Using the Recon-all command

recon-all -s sub-101 -i sub-101_ses-BL_T1w.nii.gz -all

recon-all -s <subjectName> -qcache

FreeSurfer Tutorial #4: Running recon-all in Parallel

Downloading the Parallel Command

Volviendo a FreeSurfer, normalmente solo se usa un núcleo cada vez que se ejecuta recon-all. Con un comando llamado parallel , cada instancia de recon-all se puede asignar a un núcleo diferente. Si usa una computadora Macintosh, puede ver el número de núcleos escribiendo lo siguiente:

sysctl hw.physicalcpu hw.logicalcpu

Using the Parallel Command

If you want to store the results of recon-all in the directory from which you run parallel, type export SUBJECTS_DIR=`pwd`.

Parallel is run by piping the output of the ls command into the parallel command. For example, if you have six anatomical images labeled sub1.nii, sub2.nii … sub6.nii, you can analyze them in parallel by typing the following:

ls *.nii | parallel --jobs 8 recon-all -s {.} -i {} -all -qcache

Analyzing the Cannabis Dataset

ls .. | grep ^sub- > subjList.txt

for sub in `cat subjList.txt`; do
  cp ../${sub}/ses-BL/anat/*.gz .
done

gunzip *.gz

SUBJECTS_DIR=`pwd`

ls *.nii | parallel --jobs 8 recon-all -s {.} -i {} -all -qcache

rm *.nii

for sub in `cat subjList.txt`; do
  mv ${sub}_ses-BL_T1w.nii ${sub}
done

The next tutorial will show you another way to batching your recon-all processes by using a supercomputer: The Open Science Grid.

FreeSurfer Tutorial #5: Using the Open Science Grid

Preparing Your Data for the Open Science Grid

You will also need a command called fsurf to submit recon-all jobs to the Open Science Grid supercomputer. To download this command, type:

curl -L -o fsurf 'http://stash.osgconnect.net/+fsurf/fsurf'
chmod +x fsurf

sudo mv fsurf /bin

Next, create a list of all of the subjects by typing the following code:

ls | grep sub- > subjList.txt

Submitting Recon-All Jobs

First you will need to run recon-all on your anatomical images, omitting the -all option. This will create a series of directories, and then convert the anatomical image to .mgz format and place it in the mri/orig directory. The following code can be either copied and pasted into the Terminal, or you can copy it into a shell script and run it with tcsh:

 foreach subj (`cat subjList.txt`)
    cd $subj/ses-BL/anat
    if (! -d $subj ) then #If the FS directory doesn't exist, then run recon-all
            recon-all -s $subj -i *.nii.gz -sd .
            #zip the FreeSurfer directories, so they can be submitted to fsurf
            zip -r $subj.zip $subj
            cd ../../..
    else
            echo "FreeSurfer folder for $subj already exists; if you want to rerun recon-all for this subject, delete the folder and rerun this script."
            cd ../../..
    endif
end

Once that has finished, you can submit the jobs using fsurf. In this example, I’ve placed fsurf in a for-loop:

foreach subj (`cat subjList.txt`)
   cd $subj/ses-BL/anat
   fsurf submit --subject=$subj --input=$subj.zip --defaced --deidentified --version 6.0.0 --freesurfer-options='-all -qcache -3T'
   cd ../../..
end

The status of the jobs can then be checked by typing fsurf list, which will print several columns to the screen. The first column is the subject name, the second column is the subject ID assigned by the Open Science Grid supercomputer, and the second-to-last column specifies whether the job is running, completed, or has failed. Periodically check the status of these jobs to see which ones can be downloaded.

Downloading or Removing Jobs

fsurf output --id <subjID>

fsurf remove --id <subjID>

FreeSurfer Tutorial #6: Freeview

Freeview Options from the Command Line

freeview -v mri/orig.mgz mri/aseg.mgz:colormap=LUT -f surf/lh.pial:edgecolor=yellow

FreeSurfer Tutorial #7: The FSGD File

Before starting this tutorial, create a directory called FS within the Cannabis directory. The FS directory should contain all of the directories that have been generated by recon-all. Either run the recon-all commands from that directory, or move them into the FS directory with the mv command.

Comparing Groups

Organizing the Directories

First, we will copy the fsaverage template into our current directory. Navigate to the Cannabis directory which contains all of the subjects (i.e., Cannabis/FS), and then type:

cp -R $FREESURFER_HOME/subjects/fsaverage .

to copy the fsaverage template. When that is done, set the SUBJECTS_DIR variable to the current directory by typing export SUBJECTS_DIR=`pwd`. This will place the output of any recon-all or group analysis commands into the current directory:

setenv SUBJECTS_DIR `pwd`

We will also create two directories called FSGD and Contrasts, which will contain the text files needed to run our analysis:

mkdir FSGD Contrasts

Creating the FSGD File

To keep our files organized, copy the participants.tsv file into the FSGD directory, and rename it CannabisStudy.tsv:

cp ../participants.tsv FSGD/CannabisStudy.tsv.

Now, open the file CannabisStudy.tsv in Excel. We will reformat it into an FSGD file, which is organized in such a way that can be understood by the group analysis commands we will run later. In the first column, type the following four lines:

GroupDescriptorFile 1
Title CannabisStudy
Class HC
Class CB

For now, save the spreadsheet as a Tab Delimited Text file by clicking on File -> Save As, and selecting “Tab Delimited Text” from the File Format field. This will create a file called CannabisStudy.txt. Make sure this is saved into the FSGD directory. Then open a Terminal, navigate to the FSGD directory, and type the following:

tr '\r' '\n' < CannabisStudy.txt > CannabisStudy.fsgd

Creating the Contrast file

To specify these weights, navigate to the Contrasts directory and then type:

echo "1 -1" > HC-CB.mtx

Now create another contrast file for the opposite contrast, namely:

echo "-1 1" > CB-HC.mtx

Exercises

Now that we have created the files necessary for a group analysis, the next step is to run the group analysis itself. Before you proceed, try the following exercises to test your understanding of what you just read.

FreeSurfer Tutorial #8: Group Analysis

Creating a group file with mris_preproc

We will perform all of these steps with a single command: mris_preproc. The command requires the following arguments:

An FSGD file (indicated by the –fsgd option);
A template to resample to (–target);
An indication of which hemisphere to resample (–hemi);
A label for the output file (–out).

To make the command more compact and to make it adaptable to any study you wish to analyze, we will use nested for-loops:

#!/bin/tcsh

setenv study $argv[1]

foreach hemi (lh rh)
  foreach smoothing (10)
    foreach meas (volume thickness)
      mris_preproc --fsgd FSGD/{$study}.fsgd \
        --cache-in {$meas}.fwhm{$smoothing}.fsaverage \
        --target fsaverage \
        --hemi {$hemi} \
        --out {$hemi}.{$meas}.{$study}.{$smoothing}.mgh
    end
  end
end

Copy this code into a shell script and save it as runMrisPreproc.sh. This code is also available for download here. Make sure the script is in the directory containing all of the subject directories (in this case, Cannabis/FS), and then run it by typing tcsh runMrisPreproc.sh.

If you haven’t used the -qcache option during recon-all, you can still smooth the data without having to rerun all of the preprocessing steps; e.g.,

recon-all -s <subjName> -qcache

To smooth at a specific level, you can add it after the -fwhm option, e.g.:

recon-all -s <subjName> -qcache -fwhm 10

Fitting the general linear model with mri_glmfit

Now that all of the subjects are concatenated into a single dataset, we can fit a general linear model with FreeSurfer’s mri_glmfit command. In this example we will use the following inputs:

The concatenated dataset containing all of the subjects’ structural maps (–y);
The FSGD file (–fsgd);
A list of contrasts (each contrast specified by a different line containing –C);
The hemisphere of the template to analyze (–surf);
A mask to restrict our analysis only to the cortex (–cortex);
An output label for the directory containing the results (–glmdir).

#!/bin/tcsh

set study = $argv[1]

foreach hemi (lh rh)
  foreach smoothness (10)
    foreach meas (volume thickness)
        mri_glmfit \
        --y {$hemi}.{$meas}.{$study}.{$smoothness}.mgh \
        --fsgd FSGD/{$study}.fsgd \
        --C Contrasts/CB-HC.mtx \
        --C Contrasts/HC-CB.mtx \
        --surf fsaverage {$hemi}  \
        --cortex  \
        --glmdir {$hemi}.{$meas}.{$study}.{$smoothness}.glmdir
    end
  end
end

Copy this code into a shell script and save it as runGLMs.sh. This code is also available for download here. Run the script from the subject directory by typing tcsh runGLMs.sh.

Reviewing the Output

If the scripts run without any errors, you should see the following directories in your current directory:

lh.thickness.CannabisStudy.10.glmdir
lh.volume.CannabisStudy.10.glmdir
rh.thickness.CannabisStudy.10.glmdir
rh.volume.CannabisStudy.10.glmdir

To render the statistical maps on the fsaverage template, navigate to any of the contrast directories (e.g., HC-CB) and type:

freeview -f $SUBJECTS_DIR/fsaverage/surf/lh.inflated:overlay=sig.mgh

FreeSurfer Tutorial #9: Cluster Correction

Overview

After you have run your general linear model and created group-level contrast maps, you will need to correct for the amount of tests that you have run. For a more detailed overview of how cluster-correction works, see this page. Although it uses fMRI data to illustrate the concept, the same idea applies to the vertices that we analyze in structural data.

Cluster Correction with mri_glmfit-sim

 #!/bin/tcsh

 setenv study $argv[1]

 foreach meas (thickness volume)
   foreach hemi (lh rh)
     foreach smoothness (10)
       foreach dir ({$hemi}.{$meas}.{$study}.{$smoothness}.glmdir)
         mri_glmfit-sim \
           --glmdir {$dir} \
           --cache 1.3 pos \
           --cwp 0.05  \
           --2spaces
       end
     end
   end
end

The options for mri_glmfit_sim specify the following:

The directory that is being corrected for multiple comparisons (–glmdir);
The vertex-wise cluster threshold (–cache);
The cluster-wise p-threshold (–cwp, always set to 0.05 unless you have reasons for doing otherwise);
Correction for analyzing both hemispheres (–2spaces)

These clusters can then be rendered on the fsaverage template by typing the following from the cluster-corrected directory:

freeview -f $SUBJECTS_DIR/fsaverage/surf/lh.inflated:overlay=cache.th13.pos.sig.cluster.mgh