changed 3 years ago
Linked with GitHub

Human Brain Atlas Processing Tutorial [input template]

Table of Contents

About

This guide will go through the steps used to generate the templates from the Human Brain Atlas project. This guide assumes :

-you have an input template that you want to align everything to. See [this] (link coming soon) guide if you want to preprocess data without an input template.
-you have installed all the necessary software/programs
-that you're using linux or OSX as your operating system. most of the software packages used here are not compatible with Windows.

The data from the original project is huge, so here we will use sample data and a 0.4mm template instead of 0.25mm. You can can download this dataset here (download the demo-input-template folder as a zip file):

Link to sample dataset used in this guide https://osf.io/zfupt/files/?view_only=2d48452b19cf4fb68d892072be41e575

Any queries can be sent to Zoey Isherwood (zoey.isherwood@gmail.com) or Mark Schira (mark.schira@gmail.com)

List of software packages needed

Software/Programs Website
ITKSNAP http://www.itksnap.org/pmwiki/pmwiki.php?n=Downloads.SNAP3
MATLAB https://au.mathworks.com/products/matlab.html
Python https://www.python.org/
HDBET https://github.com/MIC-DKFZ/HD-BET
FSL https://fsl.fmrib.ox.ac.uk/fsl/fslwiki
Freesurfer https://surfer.nmr.mgh.harvard.edu/
MRTrix3 https://www.mrtrix.org/
ANTS http://stnava.github.io/ANTs/
pydeface https://github.com/poldracklab/pydeface

List of scripts used to process data

NOTE: if you download the dataset, all the necessary code is included in the zip folder.

Scripts Website
dicm2nii.m https://au.mathworks.com/matlabcentral/fileexchange/42997-xiangruili-dicm2nii
make-masks-hba-project.sh https://osf.io/j8nhz/?view_only=2d48452b19cf4fb68d892072be41e575
n4bias-corr-hba-project.sh https://osf.io/ycz8p/?view_only=2d48452b19cf4fb68d892072be41e575
hba-sample-data-set-preproc-input-template.sh (Note: this code contains all the code blocks contained in this guide) https://osf.io/rdxta/?view_only=2d48452b19cf4fb68d892072be41e575

Data summary

Image Not Showing Possible Reasons
  • The image file may be corrupted
  • The server hosting the image is unavailable
  • The image path is incorrect
  • The image format is not supported
Learn More →
Internal data summary:

Sequence Name File used for template File used for brainmask
MP2RAGE UNI_DEN INV2
DUTCH INV1_ND INV1_ND
FLAWS INV2_ND INV2_ND
T2 T2 T2
DTI mean for alignment. Apply non-linear & linear transform to other files (FAC) mean

Converting RAW files to NIFTI

Step 1: DICOM -> NIFTI

MATALB script used to convert data:

Original Name Website
dicm2nii.m https://au.mathworks.com/matlabcentral/fileexchange/42997-xiangruili-dicm2nii

Image Not Showing Possible Reasons
  • The image file may be corrupted
  • The server hosting the image is unavailable
  • The image path is incorrect
  • The image format is not supported
Learn More →
Internal lab info: dicoms are located here:

/mnt/lab-nas/raw/raw2018/human-brain-atlas-may-2018/source
  1. Open MATLAB and go to the directory where the unzipped data is located
cd [insert data path here] %e.g. cd ~/Desktop/hba-sample-dataset-template-input
  1. Make a directory called raw
mkdir raw
  1. Now run the dicm2nii.m script. For it to run it has to be added to the filepath. When you run it a GUI like this should open:

  2. Click on DICOM folder/files and select the source folder in the current directory. Next, click the Result folder button and select the raw folder in the current directory.

    Now ensure all the correct options are selected (see image above; click to select Output format .nii ,Compress,Left-hand storage, Use parfor if needed, Save json file, and Use SeriesInstanceUID if it exists)

    Once all the correct options are selected, click Start conversion.

    Note: this step can take a while

  3. If the processing has finished, you've successfully converted the files from DICOM to NIFTI.

Step 2: Rename files according to BIDS formatting

Rename the files output in raw with BIDS formatting. For this, use sub-01 as the subject name, and ses-01 as the session number. In the sample dataset, the run numbers should be runs: run-01, run-02,run-03, and run-04. The acquisition name should be: acq-mp2rage-wip944.

There will be multiple files associated with each run. These files include: INV1, T1_Images, UNI_DEN, UNI_Images, and INV2.

See below for some examples of how to rename each file:

Original Name BIDS Name
mp2rage_wip944_0_4iso_INV1_s012.nii.gz sub-01_ses-01_run-01_acq-mp2rage-wip944_INV1.nii.gz
mp2rage_wip944_0_4iso_T1_Images_s013.nii.gz sub-01_ses-01_run-01_acq-mp2rage-wip944_INV2.nii.gz
mp2rage_wip944_0_4iso_UNI_DEN_s014.nii.gz sub-01_ses-01_run-01_acq-mp2rage-wip944_T1_Images.nii.gz
mp2rage_wip944_0_4iso_UNI_Images_s015.nii.gz sub-01_ses-01_run-01_acq-mp2rage-wip944_UNI_DEN.nii.gz
mp2rage_wip944_0_4iso_INV2_s016.nii.gz sub-01_ses-01_run-01_acq-mp2rage-wip944_UNI_Images.nii.gz

We were a bit old school in our approach and manually renamed each file to follow BIDS formatting. There are many more intuitive ways of doing this (e.g. using the BIDS feature in dicm2nii, naming files automatically using a script etc), but we ended up naming them manually.

Step 3: Anonymise the data by defacing each scan.

Python script used to convert data:

script name Website
pydeface https://github.com/poldracklab/pydeface

Run the section of code below to anonymize the data by removing the subject's face. It's a little redundant in the case of our data since 1) the identities of both subjects are not anonymised in the upcoming publication and 2) we end up skull stripping later on. So you can skip this step if you like, but it's just best practice to do this just in case you have to share anonymous data with the skull intact.

DATA_PATH=[base input path to the unzipped downloaded dataset] INPUT_PATH=${DATA_PATH}/raw OUTPUT_PATH=${DATA_PATH}/defaced # make OUTPUT_PATH if it doesn't already exist if [ ! -d ${OUTPUT_PATH} ]; then mkdir -p ${OUTPUT_PATH}; fi SCANS=(sub-01_ses-01_run-01_acq-mp2rage-wip944_ sub-01_ses-01_run-02_acq-mp2rage-wip944_ sub-01_ses-01_run-03_acq-mp2rage-wip944_) TYPES=(INV1.nii.gz INV2.nii.gz T1_Images.nii.gz UNI_DEN.nii.gz UNI_Images.nii.gz) cd $INPUT_PATH for f in ${SCANS[@]}; do echo "Processing scan: $f..." #deface INV2 image then apply to everything else... pydeface ${INPUT_PATH}/${f}${TYPES[1]} \ --applyto \ ${INPUT_PATH}/${f}${TYPES[0]} \ ${INPUT_PATH}/${f}${TYPES[2]} \ ${INPUT_PATH}/${f}${TYPES[3]} \ ${INPUT_PATH}/${f}${TYPES[4]} \ done # now move all the defaced files to ${OUTPUT_PATH} mv ${INPUT_PATH}/*_defaced.nii.gz ${OUTPUT_PATH}/

Preprocessing the data

Step 1: Generate automated masks for each raw file

In order to skull strip each file, we have to first generate a brainmask. To do this we use the make-masks-hba-project.sh script, which utilises HD-BET and ANTs' N4 bias correction. The script is pretty automated, requiring only a few input parameters, so I won't delve into exactly what it's doing here.

  1. To generate brainmasks of the files generated in the last few steps, run the following section of code:
DATA_PATH=[base input path to the unzipped downloaded dataset] CODE_DIR=${DATA_PATH}/code # for make-masks-hba-project.sh OUTPUT_PATH=${DATA_PATH}/brainmasks INFLATE_MM=0 # make OUTPUT_PATH if it doesn't already exist if [ ! -d ${OUTPUT_PATH} ]; then mkdir -p ${OUTPUT_PATH}; fi # list all the scans you want to process in the IMAGES variable below. #find "$(pwd)" makes it easier... # have to use the INV2 images for the MP2RAGE images since the T1 weighted image is too noisy.... IMAGES=(${DATA_PATH}/defaced/sub-01_ses-01_run-01_acq-mp2rage-wip944_INV2_defaced.nii.gz ${DATA_PATH}/defaced/sub-01_ses-01_run-02_acq-mp2rage-wip944_INV2_defaced.nii.gz ${DATA_PATH}/defaced/sub-01_ses-01_run-03_acq-mp2rage-wip944_INV2_defaced.nii.gz ${DATA_PATH}/defaced/sub-01_ses-01_run-04_acq-mp2rage-wip944_INV2_defaced.nii.gz) for image in "${IMAGES[@]}"; do bash ${CODE_DIR}/make-masks-hba-project.sh \ -i $image \ -o $OUTPUT_PATH done #clean up rm $OUTPUT_PATH/ss-*.nii.gz rm $OUTPUT_PATH/hd-bet-*.nii.gz
  1. When the mask is generated for the INV2 image, you have to open the corresponding UNI_DEN MP2RAGE image in ITK SNAP along with the corresponding INV2 generated mask. You then have to save the mask with the phrase "UNI_DEN" in the filename instead of INV2.

    • You have to do this because for some reason the transformation matrix occasionally differs between the UNI_DEN and INV2 image So this way you save the mask in the same space was the UNI_DEN image.

You can manually open each file and the corresponding brainmask using ITKSNAP's GUI. Alternatively, you can open ITKSNAP from the command line. Examples of this are listed below for each of the 4 images

SCAN 1

DATA_PATH=[base input path to the unzipped downloaded dataset] CODE_DIR=${DATA_PATH}/code #SCAN 1 DEFACED_SCAN=${DATA_PATH}/defaced/sub-01_ses-01_run-01_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz BRAINMASK=${DATA_PATH}/brainmasks/brainmask-sub-01_ses-01_run-01_acq-mp2rage-wip944_INV2_defaced.nii.gz itksnap -g $DEFACED_SCAN -s $BRAINMASK

SCAN 2

DATA_PATH=[base input path to the unzipped downloaded dataset] CODE_DIR=${DATA_PATH}/code #SCAN 2 DEFACED_SCAN=${DATA_PATH}/defaced/sub-01_ses-01_run-02_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz BRAINMASK=${DATA_PATH}/brainmasks/brainmask-sub-01_ses-01_run-02_acq-mp2rage-wip944_INV2_defaced.nii.gz itksnap -g $DEFACED_SCAN -s $BRAINMASK

SCAN 3

DATA_PATH=[base input path to the unzipped downloaded dataset] CODE_DIR=${DATA_PATH}/code #SCAN 3 DEFACED_SCAN=${DATA_PATH}/defaced/sub-01_ses-01_run-03_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz BRAINMASK=${DATA_PATH}/brainmasks/brainmask-sub-01_ses-01_run-03_acq-mp2rage-wip944_INV2_defaced.nii.gz itksnap -g $DEFACED_SCAN -s $BRAINMASK

SCAN 4

DATA_PATH=[base input path to the unzipped downloaded dataset] CODE_DIR=${DATA_PATH}/code #SCAN 4 DEFACED_SCAN=${DATA_PATH}/defaced/sub-01_ses-01_run-04_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz BRAINMASK=${DATA_PATH}/brainmasks/brainmask-sub-01_ses-01_run-04_acq-mp2rage-wip944_INV2_defaced.nii.gz itksnap -g $DEFACED_SCAN -s $BRAINMASK

After opening the scan and its corresponding brainmask, click Segmentation -> Save [brainmask] as

Then change the filename such that INV2 changes to UNI_DEN

​​​​->

Then click finish. Now the brainmask is in the same space as the UNI_DEN images.

Step 2: Skull strip raw files with masks generated in the last step

DATA_PATH=[base input path to the unzipped downloaded dataset] CODE_DIR=${DATA_PATH}/code # get scans and masks and put into the following variables... need fullpath for code to work. use line below... # find $(pwd)/*.nii.gz -maxdepth 1 -type f -not -path '*/\.*' | sort # find $(pwd)/brain*.nii.gz -maxdepth 1 -type f -not -path '*/\.*' | sort OUTPUT_PATH=${DATA_PATH}/brainmasks # make OUTPUT_PATH if it doesn't already exist if [ ! -d ${OUTPUT_PATH} ]; then mkdir -p ${OUTPUT_PATH}; fi IMAGES=(${DATA_PATH}/defaced/sub-01_ses-01_run-01_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz ${DATA_PATH}/defaced/sub-01_ses-01_run-02_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz ${DATA_PATH}/defaced/sub-01_ses-01_run-03_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz ${DATA_PATH}/defaced/sub-01_ses-01_run-04_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz) MASKS=(${DATA_PATH}/brainmasks/brainmask-sub-01_ses-01_run-01_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz ${DATA_PATH}/brainmasks/brainmask-sub-01_ses-01_run-02_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz ${DATA_PATH}/brainmasks/brainmask-sub-01_ses-01_run-03_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz ${DATA_PATH}/brainmasks/brainmask-sub-01_ses-01_run-04_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz) echo "skull stripping with indicated masks..." counter=0 for image in "${IMAGES[@]}"; do FILEPATH=$(dirname $image) FILENAME=$(basename $image) FILENAMENOEXT=${FILENAME%%.*} echo "ss'ing: ${image}" echo "brainmask: ${MASKS[$counter]}" ImageMath 3 ${OUTPUT_PATH}/ss-${FILENAMENOEXT}.nii.gz m $image ${MASKS[$counter]} # copy mask used here to final directory... # cp ${MASKS[$counter]} ${OUTPUT_PATH}/brainmask-${FILENAMENOEXT}.nii.gz ((counter=counter+1)) done

Step 3: Align the 0.4m template to each raw file and save the corresponding manual brainmask

Summary:

We've already manually created a brainmask of a template file. So rather than relying on the automated brainmask, we'd like to align the manual one to each raw file.

This step has to be done manually using ITK SNAP use the masks generated in Step 1 as an ROI to help guide the linear alignment only use RIGID alignment in ITKSNAP. It is important to use nearest neighbour interpolation when reslicing the brainmasks.

Save each brainmask file in ${DATA_PATH}/sub-01/0p20/brainmasks with the prefix template-brainmask- and the name of the corresponding raw file, e.g. template-brainmask-sub-01_ses-01_run-01_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz

More detailed instructions are below:

  1. Open each file with its corresponding brainmask, as well as the template. See the code blocks below if you want to open each file using the command line:
DATA_PATH=[base input path to the unzipped downloaded dataset] CODE_DIR=${DATA_PATH}/code #SCAN 1 DEFACED_SCAN=${DATA_PATH}/defaced/sub-01_ses-01_run-01_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz BRAINMASK=${DATA_PATH}/brainmasks/brainmask-sub-01_ses-01_run-01_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz TEMPLATE=${DATA_PATH}/template/0p40-sub-01_t1_ACPC.nii.gz itksnap -g $DEFACED_SCAN -s $BRAINMASK -o $TEMPLATE
DATA_PATH=[base input path to the unzipped downloaded dataset] CODE_DIR=${DATA_PATH}/code #SCAN 2 DEFACED_SCAN=${DATA_PATH}/defaced/sub-01_ses-01_run-02_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz BRAINMASK=${DATA_PATH}/brainmasks/brainmask-sub-01_ses-01_run-02_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz TEMPLATE=${DATA_PATH}/template/0p40-sub-01_t1_ACPC.nii.gz itksnap -g $DEFACED_SCAN -s $BRAINMASK -o $TEMPLATE
DATA_PATH=[base input path to the unzipped downloaded dataset] CODE_DIR=${DATA_PATH}/code #SCAN 3 DEFACED_SCAN=${DATA_PATH}/defaced/sub-01_ses-01_run-03_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz BRAINMASK=${DATA_PATH}/brainmasks/brainmask-sub-01_ses-01_run-03_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz TEMPLATE=${DATA_PATH}/template/0p40-sub-01_t1_ACPC.nii.gz itksnap -g $DEFACED_SCAN -s $BRAINMASK -o $TEMPLATE
DATA_PATH=[base input path to the unzipped downloaded dataset] CODE_DIR=${DATA_PATH}/code #SCAN 4 DEFACED_SCAN=${DATA_PATH}/defaced/sub-01_ses-01_run-04_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz BRAINMASK=${DATA_PATH}/brainmasks/brainmask-sub-01_ses-01_run-04_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz TEMPLATE=${DATA_PATH}/template/0p40-sub-01_t1_ACPC.nii.gz itksnap -g $DEFACED_SCAN -s $BRAINMASK -o $TEMPLATE
  1. Once you've opened the necessary files, change the opacity of the brainmask to 0 using the 'Segmentation Labels'. We turn this off because it's distracting when trying to manually align the template to the raw scan.

  1. Now click the Tools menu option, then Registration

  1. First get a good manual alignment of the template scan to the raw scan using the Manual registration tab.

    Use your mouse to rotate and move the brain in either of the 3 viewing windows. The main thing is to align the ACPC line and ensure roughly the same positioning.

  1. Now run automatic registration using the following parameters: Transformation Model Rigid, Image similarity matrix Mutual Information, Coarse Level 8x, Finest Level 1x. Also make sure Use segmentation as a mask is selected. Once all the parameters are set, hit "Run Registration"

Image Not Showing Possible Reasons
  • The image file may be corrupted
  • The server hosting the image is unavailable
  • The image path is incorrect
  • The image format is not supported
Learn More →
Internal lab registration parameters:

Sequence Name Transformation Model, Image similarity matrix Use brainmask?
MP2RAGE Rigid, Mutual Information Yes
DUTCH Rigid, Cross Correlation Yes
FLAWS Rigid, Cross Correlation No

  1. When the Automatic registration is complete, visually inspect it to make sure it did a good job. If it's all good, save the transformation matrix. To do this, click the floppy disk icon in the Registration panel. Name the file the following depending on the run number template-to-sub-01_ses-01_run-0X_acq-mp2rage-wip944_UNI_DEN_defaced.txt and save it in ${DATA_PATH}/template

  1. Now open the template brainmask. We will no resclice it in the space of the raw scan using the transformation matrix generated in the previous step. Open ${DATA_DIR}/template/brainmask-0p40-sub-01_t1_ACPC.nii.gz in ITKSNAP by either using the File -> Open option in the toolbar, or by dragging and dropping the file from a fileviewer. When opening the file, be sure to select Load as Additional Image.

  1. Now click on the folder icon in the Registration panel to open the transformation matrix you made in Step 6. Make sure the Moving image layer selected is the brainmask file. Click okay, and now the brainmask should be in the same space as the raw scan.

  1. Now we have to reslice the brainmask image. For this, click the tile icon in the Registration panel.

Make sure the Interpolation option is set to Nearest Neighbor, then click okay.

A 4th scan should now appear in the ITKSNAP window - this is the resliced brainmask. Click on the dropdown button (circled below) and click Save image. Save the file in the ${DATA_PATH}/brainmasks folder named as the following depending on the run number template-brainmask-sub-01_ses-01_run-0X_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz

Repeat this process for the remaining scans before you move onto Step 4.

Step 4: Expand the brainmasks generated in the previous step using FSL

Since the manual brainmask is a bit tight, we're going to inflate it slightly before skull stripping the original files. Run the section of code below to do this:

# get scans and masks and put into the following variables... need fullpath for code to work. use line below... # find $(pwd)/*.nii.gz -maxdepth 1 -type f -not -path '*/\.*' | sort # find $(pwd)/brain*.nii.gz -maxdepth 1 -type f -not -path '*/\.*' | sort DATA_PATH=[base input path to the unzipped downloaded dataset] CODE_DIR=${DATA_PATH}/code OUTPUT_PATH=${DATA_PATH}/brainmasks if [ ! -d ${OUTPUT_PATH} ]; then mkdir -p ${OUTPUT_PATH}; fi MASKS=(${DATA_PATH}/brainmasks/template-brainmask-sub-01_ses-01_run-01_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz ${DATA_PATH}/brainmasks/template-brainmask-sub-01_ses-01_run-02_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz ${DATA_PATH}/brainmasks/template-brainmask-sub-01_ses-01_run-03_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz ${DATA_PATH}/brainmasks/template-brainmask-sub-01_ses-01_run-04_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz) echo "expanding masks" for image in "${MASKS[@]}"; do echo "expanding ${image}" FILEPATH=$(dirname $image) FILENAME=$(basename $image) FILENAMENOEXT=${FILENAME%%.*} echo "expanded name: e_${FILENAMENOEXT}.nii.gz" fslmaths ${image} -dilM ${OUTPUT_PATH}/e_${FILENAMENOEXT}.nii.gz done

Step 5. Skull strip raw files using the expanded template masks that have been aligned to each raw file

Now that we've inflated the brainmasks slightly, we're ready to skull strip the original files. Run the section of code below to do this.

# get scans and masks and put into the following variables... need fullpath for code to work. use line below... # find $(pwd)/*.nii.gz -maxdepth 1 -type f -not -path '*/\.*' | sort # find $(pwd)/template*.nii.gz -maxdepth 1 -type f -not -path '*/\.*' | sort DATA_PATH=[base input path to the unzipped downloaded dataset] CODE_DIR=${DATA_PATH}/code OUTPUT_PATH=${DATA_PATH}/brainmasks if [ ! -d ${OUTPUT_PATH} ]; then mkdir -p ${OUTPUT_PATH}; fi IMAGES=(${DATA_PATH}/defaced/sub-01_ses-01_run-01_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz ${DATA_PATH}/defaced/sub-01_ses-01_run-02_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz ${DATA_PATH}/defaced/sub-01_ses-01_run-03_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz ${DATA_PATH}/defaced/sub-01_ses-01_run-04_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz) MASKS=(${DATA_PATH}/brainmasks/e_template-brainmask-sub-01_ses-01_run-01_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz ${DATA_PATH}/brainmasks/e_template-brainmask-sub-01_ses-01_run-02_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz ${DATA_PATH}/brainmasks/e_template-brainmask-sub-01_ses-01_run-03_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz ${DATA_PATH}/brainmasks/e_template-brainmask-sub-01_ses-01_run-04_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz) echo "Skull stripping with indicated masks..." counter=0 for image in "${IMAGES[@]}"; do FILEPATH=$(dirname $image) FILENAME=$(basename $image) FILENAMENOEXT=${FILENAME%%.*} echo "ss'ing: ${image}" echo "brainmask: ${MASKS[$counter]}" ImageMath 3 ${OUTPUT_PATH}/e-ss-${FILENAMENOEXT}.nii.gz m $image ${MASKS[$counter]} ((counter=counter+1)) done

NOTE If you're running into any errors in this step or the last, it is possible that you didn't save the resliced template brainmask properly for one of your raw scans. Check the errors being spit out by the last two steps, and if there is a Segmentation fault for one of the files, double check that file, and reslice the template brainmask again and save it just in case it wasn't done correctly/a step was missed..

It's also important throughout the process, particularly at this stage, to quality check (QC) the output. Open ITKSNAP and check the e-ss*.nii.gz files to make sure they were skull stripped correctly. You can also run the section of code below to automatically open up these files in ITKSNAP.

DATA_PATH=[base input path to the unzipped downloaded dataset] IMAGES=(${DATA_PATH}/brainmasks/e-ss-sub-01_ses-01_run-01_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz ${DATA_PATH}/brainmasks/e-ss-sub-01_ses-01_run-02_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz ${DATA_PATH}/brainmasks/e-ss-sub-01_ses-01_run-03_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz ${DATA_PATH}/brainmasks/e-ss-sub-01_ses-01_run-04_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz) itksnap -g ${IMAGES[0]} -o ${IMAGES[@]:1:${#IMAGES[@]}}

In the figure above, it looks like the skull stripping has been done correctly.

Step 6. N4 bias correct files

In order to correct for inhomogeneities in our images (e.g. the occipital pole being brighter than the rest of the brain), here we run N4 bias correction. Use the block of code below to do this:

## now n4 bias correct the new skull stripped files... # get scans and masks and put into the following variables... need fullpath for code to work. use line below... # find $(pwd)/e-ss*.nii.gz -maxdepth 1 -type f -not -path '*/\.*' | sort # find $(pwd)/template-brain*.nii.gz -maxdepth 1 -type f -not -path '*/\.*' | sort DATA_PATH=[base input path to the unzipped downloaded dataset] CODE_DIR=${DATA_PATH}/code OUTPUT_PATH=${DATA_PATH}/n4bias-corr if [ ! -d ${OUTPUT_PATH} ]; then mkdir -p ${OUTPUT_PATH}; fi IMAGES=(${DATA_PATH}/brainmasks/e-ss-sub-01_ses-01_run-01_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz ${DATA_PATH}/brainmasks/e-ss-sub-01_ses-01_run-02_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz ${DATA_PATH}/brainmasks/e-ss-sub-01_ses-01_run-03_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz ${DATA_PATH}/brainmasks/e-ss-sub-01_ses-01_run-04_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz) MASKS=(${DATA_PATH}/brainmasks/template-brainmask-sub-01_ses-01_run-01_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz ${DATA_PATH}/brainmasks/template-brainmask-sub-01_ses-01_run-02_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz ${DATA_PATH}/brainmasks/template-brainmask-sub-01_ses-01_run-03_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz ${DATA_PATH}/brainmasks/template-brainmask-sub-01_ses-01_run-04_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz) echo "N4Bias correction..." counter=0 for image in "${IMAGES[@]}"; do bash ${CODE_DIR}/n4bias-corr-hba-project.sh \ -i $image \ -x ${MASKS[$counter]} \ -o $OUTPUT_PATH \ ((counter=counter+1)) done

Step 7. Upsample first input file

Before putting all our files into the ANTs multivariate template code, we have to upsample the first input image to the desired voxel resolution of our template. We have to do this because the ANTs script doesn't upsample everything based on the input template - it does so based on the first input image. So here we'll upsample the first scan to the desired voxel resolution (for this demo, it's 0.4mm isotropic)

OUTPUT_PATH=${DATA_PATH}/ants-mvt if [ ! -d ${OUTPUT_PATH} ]; then mkdir -p ${OUTPUT_PATH}; fi OUTPUT_PREFIX=upsample-040- INPUT_RES=0.40 #in mm input_images=(${DATA_PATH}/n4bias-corr/n4corr-e-ss-sub-01_ses-01_run-01_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz) for image in "${input_images[@]}"; do FILEPATH=$(dirname $image) FILENAME=$(basename $image) FILENAMENOEXT=${FILENAME%%.*} mri_convert -nc -cs $INPUT_RES $image ${OUTPUT_PATH}/${OUTPUT_PREFIX}${FILENAMENOEXT}.nii.gz done

Step 8. Copy files needed for the ANTs Multivariate Template Code

ANTs requires all the files used for the template to be in the same directory. It's not the most practical thing to do space-wise, but I like to copy all the files we'll be using into a new directory just for ANTs. We've already saved the upsampled version of the first scan to ${DATA_PATH}/ants-mvt so now we'll transfer over the remaining files As well as the input template.

DATA_PATH=[base input path to the unzipped downloaded dataset] cp ${DATA_PATH}/n4bias-corr/n4corr*.nii.gz ${DATA_PATH}/ants-mvt rm ${DATA_PATH}/ants-mvt/n4corr-e-ss-sub-01_ses-01_run-01_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz #we don't need the low res first run... cp ${DATA_PATH}/template/0p40-sub-01_t1_ACPC.nii.gz ${DATA_PATH}/ants-mvt

Step 9. Run the ANTs Multivariate Template Code

Now we're finally ready to run the ANTs Multivariate Template Code!

Run the block of code below to run ANTs. Be sure to change the variable NUM_CORES based on your computer specs.

Depending on your computer specs this can take a few days to run. To run 3 iterations on a 24 core computer (ramonx, UOW) it'll take ~3 days.

DATA_PATH=[base input path to the unzipped downloaded dataset] CODE_DIR=${DATA_PATH}/code FILEDIR=${DATA_PATH}/ants-mvt if [ ! -d ${FILEDIR} ]; then mkdir -p ${FILEDIR}; fi # copy relevant files over to FILEDIR. ANTS only works when everything is in the same folder. TEMPLATE=${FILEDIR}/0p40-sub-01_t1_ACPC.nii.gz IMAGES=(${DATA_DIR}/ants-mvt-0p4/n4corr-e-ss-raw-sub-01_ses-01_run-01_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz ${DATA_DIR}/ants-mvt-0p4/n4corr-e-ss-raw-sub-01_ses-01_run-02_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz ${DATA_DIR}/ants-mvt-0p4/n4corr-e-ss-raw-sub-01_ses-01_run-03_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz ${DATA_DIR}/ants-mvt-0p4/n4corr-e-ss-raw-sub-01_ses-01_run-04_acq-mp2rage-wip944_UNI_DEN_defaced.nii.gz) DIMS=3 GRADIENT=0.1 NUM_CORES=12 #change the number of cores based on your computer's specs NUM_MODS=1 N4BIASCORRECT=0 # we've already done this step. STEPSIZES=20x15x5 #from Lüsebrink, F., Sciarra, A., Mattern, H., Yakupov, R. & Speck, O. T1-weighted in vivo human whole brain MRI dataset with an ultrahigh isotropic resolution of 250 μm. Scientifc data 4, 170032, https://doi.org/10.1038/sdata.2017.32 (2017). ITERATIONS=2 #4 from ants paper, 2 for hba project (prev 0.25 template). may change to 3 iterations later down the track... 2022/02/14. zji. ############################### # # Set number of threads # ############################### ORIGINALNUMBEROFTHREADS=${ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS} ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS=$NUM_CORES export ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS ########### ants cd $FILEDIR outputPath=${FILEDIR}/TemplateMultivariateBSplineSyN_${STEPSIZES} mkdir $outputPath antsMultivariateTemplateConstruction.sh \ -d $DIMS \ -r 0 \ -c 0 \ -m $STEPSIZES \ -n $N4BIASCORRECT \ -s CC \ -t GR \ -i $ITERATIONS \ -g $GRADIENT \ -b 1 \ -o ${outputPath}/T_ \ -y 1 \ #left to default setting. -z $TEMPLATE \ ${IMAGES[@]} ############################### # # Restore original number of threads # ############################### ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS=$ORIGINALNUMBEROFTHREADS export ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS

Step 10. Looking at/navigating the data from ANTs.

Once the script has completed, you can inspect your data using ITKSNAP. You'll notice in the ${DATA_PATH}/ants-mvt folder a new folder called ${DATA_PATH}/ants-mvt/TemplateMultivariateBSplineSyN_${STEPSIZES} depending on the step sizes you used. Within this folder, you'll see some other folders with GR_ as the prefix. These folders are output after each iteration. If you want to compare the output template after each iteration you can open the T_template0.nii.gz file within each GR_ folder and compare it to the final template ${DATA_PATH}/ants-mvt/TemplateMultivariateBSplineSyN_${STEPSIZES}/T_template0.nii.gz.

The other files you may see have the suffixes _Warp.nii.gz, InverseWarp.nii.gz, and Warp.nii.gz. These are the non-linear alignment files output from ANTs which were used to warp the files to the input template. The number preceding each suffix indicates the file number it corresponds to (e.g. scans 1 to 4 will correspond to 0 to 3).

Files with the suffix _WarpedToTemplate.nii.gz are the output of each scan being warped to the template. Again the number preceding the suffix indicates the file number, so if you open each one they should all be aligned.

As noted above, the output template we're most interested in has the file name T_template0.nii.gz. See below for an example screenshot of this file:

Select a repo