Analisis de datos con freesurfer
================================

.. code:: Bash

   ls sub-112/ses-BL/anat

FreeSurfer Tutorial #3: Recon-all
---------------------------------

Using the Recon-all command
---------------------------

.. code:: Bash

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

.. code:: Bash
   
   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:

.. code:: Bash

   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:

.. code:: Bash

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

Analyzing the Cannabis Dataset
------------------------------
 
.. code:: Bash

   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:

.. code:: Bash

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

.. code:: Bash

   sudo mv fsurf /bin

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

.. code:: Bash

   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:

.. code:: Bash

   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:

.. code:: Bash

   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
----------------------------

.. code:: Bash

   fsurf output --id <subjID>

.. code:: Bash

   fsurf remove --id <subjID>

FreeSurfer Tutorial #6: Freeview

Freeview Options from the Command Line

.. code:: Bash

   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:


.. code:: Bash

   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:

.. code:: Bash

   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:

.. code:: Bash

   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:

.. code:: Bash

   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:

.. code:: Bash

   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:

.. code:: Bash

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


Creating the Contrast file
--------------------------


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

.. code:: Bash

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

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

.. code:: Bash

   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:

1. An FSGD file (indicated by the --fsgd option);

2. A template to resample to (--target);

3. An indication of which hemisphere to resample (--hemi);

4. 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:

.. code:: Bash

   #!/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.,

.. code:: Bash

   recon-all -s <subjName> -qcache

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

.. code:: Bash

   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:

1. The concatenated dataset containing all of the subjects’ structural maps (--y);

2. The FSGD file (--fsgd);

3. A list of contrasts (each contrast specified by a different line containing --C);

4. The hemisphere of the template to analyze (--surf);

5. A mask to restrict our analysis only to the cortex (--cortex);

6. An output label for the directory containing the results (--glmdir).

.. code:: Bash

   #!/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:

.. code:: Bash

   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:

.. code::

   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
--------------------------------------

.. code:: Bash

   #!/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:

1. The directory that is being corrected for multiple comparisons (--glmdir);

2. The vertex-wise cluster threshold (--cache);

3. The cluster-wise p-threshold (--cwp, always set to 0.05 unless you have reasons for doing otherwise);

4. 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:

.. code::

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

FreeSurfer Tutorial #10: Correlation Analysis
---------------------------------------------