---
title: "Freesurfer course for CVL"
---
Freesurfer Course for CVL
===
> “The CVL is a welcoming and user-friendly environment, especially for people who aren’t familiar with shell scripting. It allows you to interact with HPC in a way that looks and feels like using an ordinary desktop. So I’m very grateful that the CVL exists, because it enabled me to start using HPC much more quickly than I otherwise would have.” [name= Dr Clare Harris, Senior Research Assistant at Queensland Brain Institute.]
## Table of Contents
[TOC]
:::info
http://tiny.cc/CVL_Community
:::
## How to Login into the CVL
---
1. https://desktop.cvl.org.au/ (recommended to use Chrome)
1. Select M3 and CVL @MASSIVE
1. Login with your institution credentials
1. Pick Light compute and project **nj86** click **LAUNCH**
1. Then, click **SHOW DESKTOP**
1. On the top menu click on the black button **terminal**
2. You can also access various neuroimaging software packages in the drop-down menu
## Course code
---
:::info
Case sensitive code instructions
:::
> First, let's check our username
```gherkin=
echo ${USER}
```
> Next, let's try some simple commands.
```gherkin=
pwd
ls
cd /home/${USER}/nj86
ls -la
```
> Let's try out some simple Freesurfer commands...
```gherkin=
module load freesurfer/6.0
SUBJECTS_DIR=/scratch/nj86/SUBJECTS_DIR/
vglrun freeview -recon tshaw_3T &
```
> Now, close Freeview and let's explore the module system for loading software...
```gherkin=
module purge
vglrun freeview -recon tshaw_3T &
module avail
module load freesurfer/6.0
SUBJECTS_DIR=/scratch/nj86/SUBJECTS_DIR/
vglrun freeview -recon tshaw_3T &
```
> Now, let's set up for running the analysis... starting by making our own copies of the script we will use.
```gherkin=
cd /projects/nj86/scripts
cp recon-all_example_script_3T.sh recon-all_example_script_3T_${USER}.sh
cp recon-all_example_script_7T.sh recon-all_example_script_7T_${USER}.sh
```
> See all the scripts and names
```gherkin=
ls -lthr
```
> To whom does this script belong?
```gherkin=
ls -la /home/${USER}/nj86/scripts/recon-all_example_script_3T_${USER}.sh
```
> Let's change the permissions...
```gherkin=
chmod 744 /home/${USER}/nj86/scripts/recon-all_example_script_3T_${USER}.sh
ls -la
```
:::info
https://chmod-calculator.com/
:::
> Looks good! Let's see what is inside...
```gherkin=
emacs /home/${USER}/nj86/scripts/recon-all_example_script_3T_${USER}.sh &
```
The "&" at the end tells the shell to run emacs in the background. If you forget to include the & you can hit ctrl + z and then type "bg" to background the program.
> Here is our code:
```gherkin=
#!/bin/bash
#SBATCH --job-name=3T_Freesurfer_test
# To set a project account for credit charging,
#SBATCH --account=nj86
# Request CPU resource for a serial job
#SBATCH --ntasks=1
#SBATCH --ntasks-per-node=1
#SBATCH --cpus-per-task=8
# Memory usage (MB)
#SBATCH --mem-per-cpu=8000
# Set your minimum acceptable walltime, format: day-hours:minutes:seconds
#SBATCH --time=0-48:00:00
# Set the file for output (stdout)
#SBATCH --output=/home/%u/nj86/logs/3T_Freesurfer-test-%u%j.out
# Set the file for error log (stderr)
#SBATCH --error=/home/%u/nj86/logs/3T_Freesurfer-test-%u%j.err
# Command to run a serial job
# you will need to load freesurfer (don't worry too much what this means)
module purge
module load freesurfer/6.0
#change directory so the logs know where to go
PROJECT_FOLDER="nj86"
cd /home/${USER}/${PROJECT_FOLDER}/logs/
# set up some things
#freesurfer set up
source ${FREESURFER_HOME}/SetUpFreeSurfer.sh
#subjects directory set up
SUBJECTS_DIR="/scratch/${PROJECT_FOLDER}/SUBJECTS_DIR"
if [[ ! -e ${SUBJECTS_DIR} ]] ; then
mkdir ${SUBJECTS_DIR} ;
fi
#run freesurfer recon-all
#this is the 3T data
input_file="/home/${USER}/${PROJECT_FOLDER}/rawdata/T1_3T_anon/S01_TS.MR.BRAIN_-_UQ_FMRI.0010.0002.2014.03.12.14.26.21.968750.17558629.IMA.dcm"
echo "recon-all -s ${USER}_3T -i ${input_file} -all -3T -no-isrunning"
recon-all -s ${USER}_3T -i ${input_file} -all -3T -no-isrunning
if grep -q "without error" ${SUBJECTS_DIR}/${USER}_3T/scripts/recon-all-status.log
then echo "Freesurfer ran without any errors!"
else echo "Freesurfer ran into an error, check the output in ${SUBJECTS_DIR}/${USER}_3T/scripts/ "
fi
```
:::info
The script is different to what I have shown you here. We will go through why I changed it.
:::
### Running recon-all in the terminal
```gherkin=
PROJECT_FOLDER="nj86"
SUBJECTS_DIR="/scratch/${PROJECT_FOLDER}/SUBJECTS_DIR"
recon-all
recon-all -help
input_file="/home/${USER}/${PROJECT_FOLDER}/rawdata/T1_3T_anon/S01_TS.MR.BRAIN_-_UQ_FMRI.0010.0002.2014.03.12.14.26.21.968750.17558629.IMA.dcm"
recon-all -s ${USER}_3T -i ${input_file} -all -3T
```
:::info
Once we have run the job from the command line, we can kill it with ctrl+c.
It is then time to submit the job on the cluster (!)
:::
> We need to either delete the whole folder we just created from the $SUBJECTS_DIR
```gherkin=
rm -rf ${SUBJECTS_DIR}/${USER}_3T
```
:::info
***IMPORTANT***: DO NOT USE `rm -rf` unless you know what you are doing. The shell always does EXACTLY what you ask it to do.
:::
> A safer way is to add the flag -no-isrunning to the end of our recon-all command
```gherkin=
recon-all -s ${USER}_3T -all -3T -no-isrunning
```
:::info
**Don't forget to save your file if you've changed it!**
:::
:::info
Make sure you remove -no-isrunning if this is the first time you are running the analysis. You'll also need the input flag (-i) with the path to the nifti or dicom series (as above).
:::
>Time for the big moment!
### Submitting a job on the cluster
We need to tell SLURM to submit our script to the cluster with the sbatch command.
```gherkin=
sbatch /home/${USER}/nj86/scripts/recon-all_example_script_3T_${USER}.sh
```
> and now we wait...
```gherkin=
squeue -u ${USER}
squeue -u ${USER}
squeue -u ${USER}
squeue -u ${USER}
squeue -u ${USER}
squeue -u ${USER}
ad infinitum...
tail -f /home/${USER}/nj86/logs/3T_Freesurfer-test-${USER}.out
```
:::info
*Time to check our output...*
:::
>You will replace tshaw with your username ( or ${USER} ) if you have already run the analysis...
```gherkin=
tree ${SUBJECTS_DIR}/tshaw_3T
cat ${SUBJECTS_DIR}/tshaw_3T/scripts/recon-all-status.log
vglrun freeview -recon tshaw_3T &
```
## Troubleshooting and error fixing.
>If you have issues running recon-all, check your code methodically, ask yourself, is my input correct (does it open in freeview), am i running the correct command? Check the logs in ``${SUBJECTS_DIR}/${subject}/scripts/`` for where things have gone wrong.
Check the Freesurfer mailing list for help.
https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/TroubleshootingData
> Let's fix some common errors...
>Freesurfer tutorials are very useful here.
### Adding control points
https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/ControlPoints_freeview
Load the correct volume
```
cd ${SUBJECTS_DIR}
vglrun freeview -v ${USER}_3T/mri/brainmask.mgz -f ${USER}_3T/surf/lh.white:edgecolor=blue ${USER}_3T/surf/lh.pial:edgecolor=red ${USER}_3T/surf/rh.white:edgecolor=blue ${USER}_3T/surf/rh.pial:edgecolor=red
```
> Find where the white matter is missing because of bias field (low frequency intensity non-uniformity)
> Check Slice 161
> For a 'better' bias correction than Freesurfer see the references for N4.
>Once the control points have been added manually you need to run:
```
recon-all -autorecon2-cp -autorecon3 -subjid ${USER}_3T
```
### Pial surface errors
https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/PialEdits_freeview
```gherkin=
vglrun freeview -v ${USER}_3T/mri/T1.mgz ${USER}_3T/mri/brainmask.mgz -f ${USER}_3T/surf/lh.white:edgecolor=yellow ${USER}_3T/surf/lh.pial:edgecolor=red ${USER}_3T/surf/rh.white:edgecolor=yellow ${USER}_3T/surf/rh.pial:edgecolor=red
```
>Check out slice 122 Coronal
recon-edit, shift+click, delete dura
> once you have edited the pial surface...
```gherkin=
recon-all -autorecon-pial -subjid ${USER}_3T
```
### Skull strip errors
https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/SkullStripFix_freeview
> when too much has been stripped away!
> Alternate between T1 and brainmask
:::info
*Additional script for a good skull strip*
:::
```gherkin=
#!/bin/bash
#quick fix for skull strip errors in mri_watershed
#Tom Shaw 2019
module load robex
module load freesurfer/6.0
INPUT="/path/to/your/dicoms.dcm"
subjName="your_subject_name"
SUBJECTS_DIR="/path/to/subjects_dir"
#run recon-all (first step)
recon-all -autorecon1 -cm -s ${subjName} -i ${INPUT}
#convert the t1 to nifti
mri_convert ${SUBJECTS_DIR}/${subjName}/mri/T1w.mgz ${SUBJECTS_DIR}/${subjName}/mri/T1w_nii.nii.gz
#run a better skull strip
runROBEX.sh ${SUBJECTS_DIR}/${subjName}/mri/T1w_nii.nii.gz ${SUBJECTS_DIR}/${subjName}/mri/T1w_nii_brain.nii.gz ${SUBJECTS_DIR}/${subjName}/mri/T1w_nii_brainmask.nii.gz
#convert the brainmask back to mgz
mri_convert ${SUBJECTS_DIR}/${subjName}/mri/T1w_nii_brain.nii.gz ${SUBJECTS_DIR}/${subjName}/mri/brainmask.mgz
#continue with recon-all
recon-all -autorecon2 -autorecon3 -cm -s ${subjName} -no-isrunning -cm
```
### Talairach errors
:::info
https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/Talairach_freeview
:::
```gherkin=
cd ${SUBJECTS_DIR}
vglrun tkregister2 --mgz --s tshaw_3T --fstal --surf orig
```
When you are satisfied with your registration result, click the SAVE REG button in the tkregister2 toolbar, and you need to re-run everything
```gherkin=
recon-all -all -subjid ${USER}_3T
```
### White Matter Edits
https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/WhiteMatterEdits_freeview
https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/WhiteMatterEditsV6.0
```gherkin=
vglrun freeview -v ${USER}_3T/mri/brainmask.mgz ${USER}_3T/mri/wm.mgz:colormap=heat:opacity=0.4 -f ${USER}_3T/surf/lh.white:edgecolor=blue ${USER}_3T/surf/lh.pial:edgecolor=red ${USER}_3T/surf/rh.white:edgecolor=blue ${USER}_3T/surf/rh.pial:edgecolor=red ${USER}_3T/surf/rh.inflated:visible=0 ${USER}_3T/surf/lh.inflated:visible=0
```
Video of WM edits
hypointense WM labelled as GM usually the culptit.
>when the white matter edits are done:
```gherkin=
recon-all -autorecon2-wm -autorecon3 -subjid ${subjName}
```
### Topological defects
This is essentially the same as WM defects
https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/TopologicalDefect_freeview
See the example here for a 'hole' where the WM has been incorrectly labelled:
>when the topological edits are done:
```gherkin=
recon-all -autorecon2-wm -autorecon3 -subjid ${subjName}
```
## Segmentation and parcellation
https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/AnatomicalROI#IndividualStatsfiles
Let's concatenate our stats
```shell
asegstats2table --subjects tshaw_3T abidesi_3T adsouza_3T samuelk_3T sramanan_3T stu_3T uqpmart6_3T yche9844_3T --meas volume --stats aseg.stats --tablefile aseg.table.txt
```
>Change "volume" as necessary
>If you have more subjects, change as necessary
## ROI editing
> Anatomical ROI analyses...
>
http://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/AnatomicalROIV6.0
> To accurately map a manually drawn or pre-existing label of a region of interest to several subjects in your study, you should first register your label to or draw your label on fsaverage (a template to which all subjects run with FreeSurfer have been registered to) and then use the mri_label2label command to map the label to individual subjects. An example of the command you would use is illustrated below using the FreeSurfer-generated lh.BA45_exvivo.label (Brodmann area 45, part of Broca's area involved in language). Please run:
```gherkin=
cd $SUBJECTS_DIR
mri_label2label --help
mri_label2label --srcsubject fsaverage --srclabel $FREESURFER_HOME/subjects/fsaverage/label/lh.BA45_exvivo.label --trgsubject tshaw_3T --trglabel tshaw_3T/label/lh.BA45_exvivo.label --hemi lh --regmethod surface
```
> View your new ROI...
```gherkin=
vglrun freeview -v tshaw_3T/mri/T1.mgz -l tshaw_3T/label/lh.BA45_exvivo.label
```
## References and useful links
---
:::info
Paula's slides, intro to the CVL:
https://demo.codimd.org/p/SJlh1PQAV#/
Top 10 FAIR things for bioimaging (under review)
https://librarycarpentry.org/Top-10-FAIR/2019/06/27/imaging/
:::
:::info
MASSIVE M3 Documentation: https://docs.massive.org.au/M3/m3users.htmlhttps://demo.codimd.org/p/SJlh1PQAV#/
:::
Some useful websites:
* How to transfer files to MASSIVE:
https://docs.massive.org.au/M3/transferring-files.html
* Freesurfer tutorials:
http://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial
* For recon edits after it has finished recon-all:
https://www.youtube.com/watch?reload=9&v=AR83_Bt04VQ&feature=youtu.be
* For pial edits on brainmask:
https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/PialEdits_freeview
* For white matter edits for removing/adding wm:
https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/WhiteMatterEdits_freeview
* Adding control points for WM:
https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/ControlPoints_freeview
* N4 bias Correction
https://www-ncbi-nlm-nih-gov.ezproxy.library.uq.edu.au/pubmed/20378467
* Morphometry stats details:
https://surfer.nmr.mgh.harvard.edu/fswiki/MorphometryStats
http://surfer.nmr.mgh.harvard.edu/fswiki/eTIV
* Some useful resources for simple bash coding
http://swcarpentry.github.io/shell-novice
https://devhints.io/bash
* The most useful resource for all issues related to Freesurfer:
https://mail.nmr.mgh.harvard.edu/pipermail//freesurfer/
* Collaborative editing!
http://brainbox.pasteur.fr/
* BIDS data structure
https://bids.neuroimaging.io/
* BIDSCoin for easy conversion of your DICOMs into BIDS format!
https://github.com/Donders-Institute/bidscoin
### SLURM references
---
> https://slurm.schedmd.com/pdfs/summary.pdf
> https://slurm.schedmd.com/sbatch.html
>
- Some useful SLURM commands:
```gherkin=
squeue
sbatch <slurm_script_file>
scontrol show job <JOBID>
scancel <JOBID>
sinfo -i 5 -S"-O" -o "%.9n %.6t %.10e/%m %.10O %.15C"
squeue -o"%.7i %9P %.8j %.8u %.2t %.10M %.6D %C"
```
- Massive User Scripts:
```gherkin=
show_job
show_job <JOBID>
show_cluster
user_info
```
- Slurm Sample Scripts are Here:
```
/usr/local/hpcusr/latest/training/samples/slurm/
```
- We recommend using smux to compile and test code on compute nodes.
- How to use smux: https://docs.massive.org.au/M3/slurm/interactive-jobs.html
For more details, please see:
https://docs.massive.org.au/M3/slurm/slurm-overview.html
##Shameless plug for my research
>MND patient hippocampus volume assessment:
> Longitudinal Automatic Segmentation of Hippocampus subfields using multi-contrast MRI
:::info
https://github.com/thomshaw92/LASHiS
:::
## Want to make a 3D brain?
```gherkin=
mris_convert ${SUBJECTS_DIR}/${subjName}/surf/?h.pial \
${SUBJECTS_DIR}/${subjName}/surf/?h.pial.stl
```
This .stl file can be used by 3D printers.
## FAQ and Feedback
:::info
**Need any help with a particular part?** Leave a comment!
:::
:::success
https://tinyurl.com/cvlfeedback
:::
###### tags: `Freesurfer` `CVL`
Sign in with Wallet
Connect another wallet