Human Brain Atlas Processing Tutorial [input template]

# Human Brain Atlas Processing Tutorial [input template] ## Table of Contents [TOC] ## 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](https://) | | MATLAB |[https://au.mathworks.com/products/matlab.html](https://) | | Python |[https://www.python.org/](https://) | | HDBET |[https://github.com/MIC-DKFZ/HD-BET](https://) | | FSL |[https://fsl.fmrib.ox.ac.uk/fsl/fslwiki](https://) | | Freesurfer |[https://surfer.nmr.mgh.harvard.edu/](https://) | | MRTrix3 |[https://www.mrtrix.org/](https://) | | ANTS |[http://stnava.github.io/ANTs/](https://) | | pydeface |[https://github.com/poldracklab/pydeface](https://) | ## 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](https://) | | `make-masks-hba-project.sh` |[https://osf.io/j8nhz/?view_only=2d48452b19cf4fb68d892072be41e575](https://) | | `n4bias-corr-hba-project.sh` | [https://osf.io/ycz8p/?view_only=2d48452b19cf4fb68d892072be41e575](https://) | | `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](https://) | ## Data summary >:memo: 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](https://)| >:memo: 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 ```matlab=1 cd [insert data path here] %e.g. cd ~/Desktop/hba-sample-dataset-template-input ``` 2. Make a directory called ```raw``` ```matlab=1 mkdir raw ``` 3. 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: ![](https://i.imgur.com/gbvVry0.png) 4. 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... 5. 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](https://) | 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. ```bash=1 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: ```bash=1 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 ``` 2. 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 ```bash=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 ```bash=1 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 ```bash=1 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 ```bash=1 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... ![](https://i.imgur.com/SBQCAMH.png) Then change the filename such that `INV2` changes to `UNI_DEN` ![](https://i.imgur.com/3rUCtcu.png) -> ![](https://i.imgur.com/OrUmdsK.png) ... 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 ```bash=1 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: ```bash=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_UNI_DEN_defaced.nii.gz TEMPLATE=${DATA_PATH}/template/0p40-sub-01_t1_ACPC.nii.gz itksnap -g $DEFACED_SCAN -s $BRAINMASK -o $TEMPLATE ``` ```bash=1 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 ``` ```bash=1 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 ``` ```bash=1 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 ``` 2. 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. ![](https://i.imgur.com/XgLraPD.png) 3. Now click the `Tools` menu option, then `Registration` ![](https://i.imgur.com/JIOGAjS.png) 4. 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. ![](https://i.imgur.com/8w2hAIu.png) 5. 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" >:memo: 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 | ![](https://i.imgur.com/aq2tvbL.png) 6. 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` ![](https://i.imgur.com/zWsdIFK.png) 7. 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`. ![](https://i.imgur.com/zvUlAl1.png) 8. 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. ![](https://i.imgur.com/VFM7x8n.png) 9. Now we have to reslice the brainmask image. For this, click the tile icon in the Registration panel. ![](https://i.imgur.com/3JxfoxX.png) Make sure the Interpolation option is set to `Nearest Neighbor`, then click okay. ![](https://i.imgur.com/BqqhQO9.png) 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` ![](https://i.imgur.com/bRqFwFm.png) 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: ```bash=1 # 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. ```bash=1 # 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. ```bash=1 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[@]}} ``` ![](https://i.imgur.com/TBWBiyO.png) 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: ```bash=1 ## 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) ```bash=1 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. ```bash=1 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. ```bash=1 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: ![](https://i.imgur.com/c0JaxFz.png)

Syntax	Example	Reference
# Header	Header	基本排版
- Unordered List	Unordered List
1. Ordered List	Ordered List
- [ ] Todo List	Todo List
> Blockquote	Blockquote
Bold font	Bold font
Italics font	Italics font
~~Strikethrough~~	~~Strikethrough~~
19^th^	19^th
H~2~O	H₂O
++Inserted text++	Inserted text
==Marked text==	Marked text
[link text](https:// "title")	Link
![image alt](https:// "title")	Image
`Code`	`Code`	在筆記中貼入程式碼
```javascript var i = 0; ```	`var i = 0;`
:smile:		Emoji list
{%youtube youtube_id %}	Externals
$L^aT_eX$	L^aT_eX
:::info This is a alert area. :::	This is a alert area.