Mitchell Horn
Research Computing Service, Boston University
Spring 2024

These are instruction notes for the FreeSurfer Part Deux. This is to be followed in correspondance to the slides also found in this directory. For questions about using FreeSurfer on the SCC please contact us at help@scc.bu.edu. 

====================================================================================
STATS

1. Copy the tutorial data to your local project space. 
  a. To see the SCC projects you're a part of:
  []$ groups

  b. Copy the tutorial .zip file to your project directory:
  []$ cd /projectnb/YOUR_PROJECT/
  []$ cp /project/scv/examples/imaging/tut_fs2_scc/fs2.zip .
  []$ unzip fs2.zip

  c. Set the SUBJECTS_DIR path to our new directory:
  []$ cd fs2
  []$ module load freesurfer/7.4.1
  []$ export SUBJECTS_DIR=$PWD

2. Move into the /stats directory and view some statistical outputs. 
  []$ cd sub-001/stats
  []$ less aseg.stats

  ctrl+z

  []$ less lh.aparc.stats
  
  ctrl+z

3. Create a stats file for an individual Brodmann Area (BA) label:
  []$ mris_anatomical_stats -l lh.BA1_exvivo.label -f lh.BA1_exvivo.stats sub-001 lh
  []$ less lh.BA1_exvivo.stats

  ctrl+z

4. Parse aseg statistics from multiple subjects:
  []$ cd $SUBJECTS_DIR
  []$ asegstats2table --subjects sub-001 sub-002 sub-003 --tablefile aseg.vol.table
  []$ less aseg.vol.table

  ctrl+z

5. Use Linux's version of Excel to view stats:
  []$ libreoffice --calc aseg.vol.table

 exit

6. Parse white matter segmentation statistics (for region 3007 & 3021) from multiple subjects:
 []$ asegstats2table --subjects sub-001 sub-002 sub-003 --segno 3007 3021 --stats wmparc.stats --tablefile wmparc.vol.table
 []$ libreoffice --calc wmparc.vol.table

exit

7. View the FreeSurfer Color Lookup Table:
 []$ libreoffice $FREESURFER_HOME/FreeSurferColorLUT.txt

close

====================================================================================
FREEVIEW

8. Open a volume in Freeview with predefined colormap and opacity:
  []$ cd $SUBJECTS_DIR/sub-001
  []$ freeview mri/aseg.mgz mri/aseg.mgz:colormap=heat mri/aseg.mgz:colormap=jet:opacity=0.2

close

9. Open surfaces for left hemisphere white matter and right hemisphere gray matter:
  []$ freeview -f surf/lh.white surf/rh.pial --viewport 3d

close

10. Open the same surfaces with the aparc.a2009s annotation file:
  []$ freeview -f surf/lh.white:annot=aparc.a2009s.annot surf/rh.pial:annot=aparc.a2009s.annot --viewport 3d

close

11. Open the a surfaces with the overlay of cortical thickness with a defined threshold:
  []$ freeview -f surf/lh.pial:overlay=lh.thickness:overlay_threshold=0,4  --viewport 3d

close

12. Create a gif of the 3D surface. 
  a. Create a directory to save our freeview frames into:
    []$ mkdir gif

  b. Open our freesurfer surface with aparc:
    []$ freeview -f surf/lh.white:annot=aparc.a2009s.annot --viewport 3d

  c. Save movie frames to our directory:
    File > Save Movie Frames...
        Output Location > Select Folder Icon > gif
        Fly through > Angle
        Step size > 10.00 
      Write
  
    close

  d. Use imagemagick package to convert frames to a gif:
    []$ convert -delay 0.05 gif/*.png aparc_lh.gif

  e. View our gif:
    []$ firefox aparc_lh.gif

====================================================================================
REGISTRATION

13. Simple full head registration; same modality (T1w) and across timepoints:
  []$ cd $SUBJECTS_DIR/registration
  []$ mri_robust_register --mov timepoint2.nii.gz --dst timepoint1.nii.gz --lta 2to1.lta --mapmov 2to1.nii.gz --iscale --satit
  []$ freeview timepoint2.nii.gz timepoint1.nii.gz 2to1.nii.gz:colormap=heat:opacity=0.3

# this may take 3-5 minutes

14. (OPTIONAL) Standard cross modality registration (T2w to T1w):
  []$ mri_robust_register --mov T2.nii --dst T1.nii --mapmov T2toT1.nii --lta T2toT1.lta --cost NMI
  []$ freeview T1.nii T2toT1.nii:colormap=heat

# this may take 5-6 minutes

15. Use mri_coreg on 4 cpu's to register our PET average dynamic (template) to T1w:
  []$ mri_coreg --mov sub-dummy_PET.avg.nii.gz --ref sub-dummy_T1w.nii.gz --reg PETtoT1w.lta --threads 4

  # this may take 2-3 minutes

  []$ mri_vol2vol --mov sub-dummy_PET.avg.nii.gz --lta PETtoT1w.lta --targ sub-dummy_T1w.nii.gz --o sub-dummy_PET-T1w.nii.gz
  []$ freeview sub-dummy_T1w.nii.gz sub-dummy_PET.avg.nii.gz:colormap=pet sub-dummy_PET-T1w.nii.gz:colormap=pet:opacity=0.3

16. Use bbregister to register EPI (bold) template to the subject's T1w (using their recon output):
  []$ bbregister --mov sub-004_boldtemp.nii.gz --bold --s sub-004 --lta bold2t1w.lta --o sub-004_bold-t1w.nii.gz

# this may take 2-3 minutes

  []$ freeview sub-004_T1w.nii.gz sub-004_boldtemp.nii.gz:colormap=heat sub-004_bold-t1w.nii.gz:colormap=heat:opacity=0.3:visible=0 -f rh.white:edgecolor=blue lh.white:edgecolor=blue

====================================================================================
fMRI

17. Apply bbregister transform to our fMRI correlation score (significance) map to move to subject's T1w space:
  []$ cd $SUBJECTS_DIR/fmri
  []$ mri_vol2vol --mov sub-005_sig.nii.gz --lta sub-005_bold2t1.lta --targ sub-005_t1w.nii.gz --o sub-005_sig-t1w.nii.gz

# this may take 1-2 minutes

  []$ freeview sub-005_t1w.nii.gz sub-005_sig-t1w.nii.gz:colormap=heat:heatscale=0,10,20

18. Apply mri_vol2surf to move our fMRI significance map to move to subject's surface:
  []$ mri_vol2surf --mov sub-005_sig.nii.gz --reg sub-005_bold2t1.lta --projfrac 0.5 --interp nearest --hemi lh --o sub-005.lh.sig.nii
  []$ freeview -f $SUBJECTS_DIR/sub-005/surf/lh.inflated:overlay=sub-005.lh.sig.nii:overlay_threshold=10,20 -viewport 3d