-
Notifications
You must be signed in to change notification settings - Fork 0
Module 4 MRI QA and 3D Print Prep
If you do not know how to view the FreeSurfer output on HiPerGator, watch this video for an extended walk-through (I recommend watching at 1.5 speed). This was recorded in a previous semester so update paths accordingly! Also, logging in to HiPerGator and interacting with files and applications has changed somewhat, but this should be close enough to figure out.
There are many ways to assess the quality of FreeSurfer outputs. These would only be a small part of that assessment. We will not cover editing and reprocessing files, although that might need to be done in some instances. There are fairly standardized methods for doing that but we won't cover them.
What we will do for quality assessment is use two semi-automated tools to provide a way to view the images and outputs. These will also provide some metrics of quality that can be considered in analyses.
Doing the first tutorial requires you to have completed the two recon-all commands. Some students had issues with running out of memory. Rather than keeping trying over and over, I've made the two processed brains available to students who need these. Copy (don't move) the two sub- directories into your directory (probably best in your ADNI_bids [or whatever you called it]/derivatives/freesurfer directory).
The processed brains are in /blue/psy4930/share/data/Module4
Again, only copy those if your processing for Module 3 failed and I already gave you credit for it.
- Watch this tutorial and follow along: https://youtu.be/5svhiqgO6g0
Key commands are as follows (this assumes you are in your freesurfer output directory where the recon-all command saved the processed images). This will need to be changed to match what you called your subjects (some of you have done 011_S_6303 or sub-6303 or something like that -- pay attention to names and paths). Again, remember that where files are in the video might not match where they are this year! Update paths to match where your data are.
Important: If you receive an error like this when trying to run the fsqc.sif container, you either have an incomplete FreeSurfer processing or your lh.pial and rh.pial files are named something different.
[WARNING: warnings.py: 109]: /app/fsqc/fsqc/fsqcMain.py:1203: UserWarning: Could not find /in/sub-6303/surf/lh.pial for subject sub-6303
warnings.warn(
In that case, rename the 4 files. In my case (update paths as needed), it was like this:
cd /blue/psy4930/share/students/jjtanner/Module3/ADNI_bids/derivatives/freesurfer/sub-6303/surf/
mv lh.pial.T1 lh.pial
mv rh.pial.T1 rh.pial
cd /blue/psy4930/share/students/jjtanner/Module3/ADNI_bids/derivatives/freesurfer/sub-6367/surf/
mv lh.pial.T1 lh.pial
mv rh.pial.T1 rh.pial
Then you are ready to run these in an interactive session or in HiPerGator Desktop. Do not run this on the login terminal.
#This mkdir command assumes you are where you want to make this directory. I was in my freesurfer output directory so you'll want to run something like this first (update as appropriate to match where you saved the ):
cd /blue/psy4930/share/students/jjtanner/Module3/ADNI_bids/derivatives/freesurfer
mkdir fsqc_out
apptainer run -B $PWD:/in -B $PWD/fsqc_out:/out /blue/psy4930/share/data/neurotools/fsqc.sif --subjects_dir /in --subjects sub-6303 sub-6367 --output_dir /out --skullstrip-html --surfaces-html --screenshots-html --fornix-html
#In the previous command $PWD is a variable that prints (calls) your current directory. Only use this if you are where the data are. Otherwise put in the full path (usually safer). Something like: apptainer run -B /blue/psy4930/share/students/jjtanner/Module3/ADNI_bids/derivatives/freesurfer:/in
#Pay attention to spaces in the apptainer command. There are places where there are no spaces. Also, pay attention to the dashes. Some of them are single and some are double.
- Then watch this video and follow along: https://youtu.be/c2z2FwUEWp0
IMPORTANT UPDATE
To have this run properly, run these commands in a Terminal on HiPerGator:
mkdir -p /blue/psy4930/$USER/neurotools
cd /blue/psy4930/$USER/neurotools
cp /blue/psy4930/share/data/neurotools/conn22a.zip .
cp /blue/psy4930/share/data/neurotools/spm12.zip .
unzip -q conn22a.zip -d conn
unzip -q spm12.zip -d spm12
Then in Matlab, add those paths, rather than the ones mentioned in the video. You can do that similarly to how shown in the video or by running these commands in the main Matlab window. Make sure you replace <gatorlinkid> with your Gatorlink ID!
addpath('/blue/psy4930/<gatorlinkid>/neurotools/spm12');
addpath('/blue/psy4930/<gatorlinkid>/neurotools/conn');
As you follow along with the video, you will have the files needed to submit for the homework when you are done.
This is more for fun, but will give you additional experience with containers and scripting (if you choose to script).
Watch this video and follow along. I show both running the processing "live" and in a script (script is the last part of the video). You can do either method or both, for the experience.
If you use the script, it's in /blue/psy4930/share/data/Module4
Please copy (not move) it from there into somewhere in your own directory. Then edit it to match your paths and files. Make sure to change the email address in it too!
At the end of this you will have 1 or 2 .stl files that are 3D models of human brains. These could be imported into 3D modeling software, or, with some additional minor preparation, are ready for 3D printing.
Here is the script's contents with commands used in the video. If you put these into terminal to run this live (only do that in an interactive session or in the Terminal in a HiPerGator Desktop), it's best to have each command as one line (example after this next section). Remember that paths listed here will need to be updated to match where your data are.
#!/bin/bash
#SBATCH --job-name=3dprintprep # Job name
#SBATCH --mail-type=END,FAIL # Mail events (NONE, BEGIN, END, FAIL, ALL)
#SBATCH --mail-user=putyyourgatorlinkidhere@ufl.edu # Where to send mail EDIT THIS
#SBATCH --ntasks=1 # Run on a single CPU
#SBATCH --mem=4gb # Job memory request
#SBATCH --time=00:40:00 # Time limit hrs:min:sec
#SBATCH --account=psy4930
#SBATCH --qos=psy4930
#SBATCH --output=3dprintprep_%j.log # Standard output and error log
pwd; hostname; date
cd /blue/psy4930/share/students/jjtanner/Module3/ADNI_bids/derivatives/freesurfer
module load freesurfer/7.1.1
apptainer run \
--env FREESURFER_HOME=/opt/freesurfer \
--env PATH=/opt/freesurfer/bin:$PATH \
-B $PWD:/in \
-B $PWD/3dprint/:/out \
-B $FREESURFER_HOME:/opt/freesurfer \
/blue/psy4930/share/data/neurotools/fsqc.sif \
--subjects_dir /in \
--subjects sub-6367 sub-6303 \
--output_dir /out \
--shape
cd /blue/psy4930/share/students/jjtanner/Module3/ADNI_bids/derivatives/freesurfer/3dprint
apptainer run \
-B /blue/psy4930/share/students/jjtanner/Module3/ADNI_bids/derivatives/freesurfer/brainprint/sub-6367/surfaces/:/in \
-B /blue/psy4930/share/students/jjtanner/Module3/ADNI_bids/derivatives/freesurfer/3dprint:/out \
/blue/psy4930/share/data/neurotools/3dprintprep.sif \
/in \
/out/sub-6367.stl
apptainer run \
-B /blue/psy4930/share/students/jjtanner/Module3/ADNI_bids/derivatives/freesurfer/brainprint/sub-6303/surfaces/:/in \
-B /blue/psy4930/share/students/jjtanner/Module3/ADNI_bids/derivatives/freesurfer/3dprint:/out \
/blue/psy4930/share/data/neurotools/3dprintprep.sif \
/in \
/out/sub-6303.stl
date
Here is an example of the apptainer run commands as a single line. It looks like it's multiple lines but that's just because of text wrapping with the constraints of the text box here
#Run fsqc to create the brain "shape" files
apptainer run --env FREESURFER_HOME=/opt/freesurfer --env PATH=/opt/freesurfer/bin:$PATH -B $PWD:/in -B $PWD/3dprint/:/out -B $FREESURFER_HOME:/opt/freesurfer /blue/psy4930/share/data/neurotools/fsqc.sif --subjects_dir /in --subjects sub-6367 sub-6303 --output_dir /out --shape
#Convert those "shape" files to stl, combine them, and perform smoothing of the surface.
apptainer run -B /blue/psy4930/share/students/jjtanner/Module3/ADNI_bids/derivatives/freesurfer/brainprint/sub-6367/surfaces/:/in -B /blue/psy4930/share/students/jjtanner/Module3/ADNI_bids/derivatives/freesurfer/3dprint:/out /blue/psy4930/share/data/neurotools/3dprintprep.sif /in /out/sub-6367.stl
apptainer run -B /blue/psy4930/share/students/jjtanner/Module3/ADNI_bids/derivatives/freesurfer/brainprint/sub-6303/surfaces/:/in -B /blue/psy4930/share/students/jjtanner/Module3/ADNI_bids/derivatives/freesurfer/3dprint:/out /blue/psy4930/share/data/neurotools/3dprintprep.sif /in /out/sub-6303.stl
The goal will be to use two semi-automated software packages to run quality assessment on T1 NIfTI files and on FreeSurfer processed images.
What you submit
- The fsqc-results.html and fsqc-results.csv files in the fsqc output directory you created.
- The two .jpg or .pdf reports from the CAT12 processing (this processing is run on the original T1 NIfTI images and not any FreeSurfer-processed ones). These should be in your CAT12 output directory you created within the report subdirectory.
- You only need to do the 3D printing preparation on one brain. If you ran a script, submit the .log file and/or a screenshot of the open .stl file (in Paraview on HiPerGator or, you can download the file and open in Preview on a Mac or 3D Viewer or similar on Windows).