# 3RD UOW MRI WORKSHOP ## Hippocampus surface/shape This tutorial will lead you through the basic segmentation and vertex analysis steps adopted by the FMRIB Software Library (FSL, https://fsl.fmrib.ox.ac.uk/fsl/fslwiki), as well as how you can conduct vertex analysis on non-FSL-segmented structures. ### FSL FIRST FIRST is a segmentation/registration tool for subcortical structures. Further details about usage can be found on the FSL wiki page (https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FIRST). > First let’s change your directory to where the T1-weighted image is. Open up a terminal and enter the following command (we are creating a user-specific folder so that we don't annoy each other while working on the same folder :smile: ): ```gherkin= cp -r ~/sk75/hippocampus_vertex ~/sk75/${USER}_hippocampus_vertex cd ~/sk75/${USER}_hippocampus_vertex/fsl_first ``` > Let’s set up fsl. You can view the T1 image in FSLeyes if you’d like to: ```gherkin= module load fsl vglrun fsleyes s001_T1.nii ``` > To perform segmentation on the left and right hippocampi, type in the following command: ```gherkin= run_first_all -i s001_T1 -b -s L_Hipp,R_Hipp -o s001 ``` :::info This script will register and segment the left and right hippocampi for you, as specified in your arguments. If you wish to segment other structures, you can do so as well (e.g. L_amyg). Have a read of the usage below: ```gherkin= run_first_all [options] -i <input_image> -o <output_image_basename> ``` *Optional arguments* ```gherkin= -b : optional, use only if input is already brain extracted -s <name> : run only on one specified structure (e.g. L_Hipp) – if not selected, will run all structures -a <name> : specifies the affine registration matrix to standard space (if present, e.g. if registration has already been done) ::: > Once it has done running, verify that no errors occurred by reading the log files (or you can open up the log files in the *.logs directory – If there are no errors, you will not see any output from this command: ```gherkin= cat *.logs/*.e* ``` > In your folder, you will see the following outputs: > * **<output_basename>_all_fast_firstsegs.nii.gz** = Segmentation masks for the structures (left and right hippocampus) in 3D in native space. The labels used are: > :::info > 17 Left-Hippocampus > 53 Right-Hippocampus > ::: > * **<output_basename>_all_fast_origsegs.nii.gz** = Segmentation masks for the structures in 4D (i.e. one structure per 3D image). These are the initial volumes generated directly from the mesh representation, without boundary correction. > :::info > Notice the difference between the -origsegs.nii.gz and -firstsegs.nii.gz output > ::: > * **<output_basename>_first.vtk** = Mesh representation. Can be viewed in FSLView using 3D mode -> click on ‘**view**’, then ‘**3D view**’ > * **<output_basename>_first.bvars** = Model parameters for shape analysis. **NECESSARY** for running further vertex analysis in fsl. > * **<input_name>_T1w_to_std_sub.nii.gz** = Affine-registered (12 dof) T1 image > Have a look at each individual output with FSLeyes. There is an example output in the folder ‘**first_out**’ that has been generated for all subcortical structures. > :::info > ***Hint**: use the zoom button or toggle the colour map to help you see the structures better* > ::: > Next, try the following command. What do you see? ```gherkin= first_roi_slicesdir *_T1.nii *_firstseg.nii.gz ``` :::info This command should return a summary result of each subject’s registration relative to the MNI standard brain, in multiple views (axial, sagittal, coronal). It is useful for quickly checking segmentaion when running multiple subjects, but I would still encourage you to **ALWAYS VISUALLY INSPECT EVERY SUBJECT INDIVIDUALLY**. ::: ### Vertex-level analysis Now that you have generated your hippocampal structures, it is time to prepare them for further statistical analysis! For each subject, the structure (eg. Left hippocampus)’s vertex location gets projected against the average shape, to calculate the signed, perpendicular distance of each vertex against the average surface (i.e. positive value = larger than average, negative value = smaller than average). It is this signed distance that gets used for further statistical analysis. > Let’s change directory ```gherkin= cd ~/sk75/${USER}_hippocampus_vertex/fsl_vertex/ ``` > Here we have 8 subjects, for which the left and right hippocampi have already been extracted for you. > >We will first need to concatenate the bvars files across all subjects: :::info **Usage:** *concat_bvars output_name.bvars <list of ".bvars" files in the same order as the design matrix>* ::: >e.g. ```gherkin= concat_bvars all-L_Hipp.bvars s001/s001-L_Hipp_first.bvars s002/s002-L_Hipp_first.bvars s003/s003-L_Hipp_first.bvars s004/s004-L_Hipp_first.bvars s005/s005-L_Hipp_first.bvars s006/s006-L_Hipp_first.bvars s007/s007-L_Hipp_first.bvars s008/s008-L_Hipp_first.bvars ``` > Now lets generate the 4D signed distance map (one volume per subject): ```gherkin= first_utils --vertexAnalysis --usebvars -i all-L_Hipp.bvars -d ttest.mat -o ttest_out --useReconMNI ``` :::warning Note that this step can also be done in **native space** ```gherkin= first_utils --vertexAnalysis --usebvars -i <concatenated_bvars> -d <design_matrix.mat> -o <output_basename> --useReconNative --useRigidAlign [--useScale] ``` Here, ‘**useRigidAlign**’ is **NECESSARY** to register mesh of analysis in native space (very important if you are working in native space or you will be comparing structures that are far apart in space – does not make sense!). ‘**useScale**’ is optional for if you wish to remove size effect as well. Note if analysis is done in MNI space, it will be corrected for brain volume. ::: :::info **ttest.mat** is the design matrix created for you. Have a look at it – for this purpose, the design is set up such that we are comparing two groups – s001, s002, s003, s004 vs. s005, s006, s007, s008 ::: > You will see the following outputs. Have a look at them in fsleyes. > - **ttest_out_mask.nii.gz** = boundary mask > - **ttest_out.nii.gz** = 4D volume of signed distance map for each subject > > Scroll through the volumes in the 4D output to see the difference between each subject. > The outputs are now suitable for statistical testing (e.g. permutation test in randomise or PALM, https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/PALM/UserGuide) but we are not going to do this here. ### Alternate shape analysis method This is the shape analysis method I have used (https://onlinelibrary.wiley.com/doi/abs/10.1111/adb.12652) when comparing manually segmented structures (i.e. that do not have the required bvars or was not generated through FSL FIRST). ![](https://i.imgur.com/LXpsdkH.jpg) > First, lets go to the required directory: ```gherkin= cd ~/sk75/${USER}_hippocampus_vertex/manual ``` :::info In most cases, we will first have to ensure that your hippocampi labels are in a consistent space (e.g. standard space). This can be done by applying the transformation matrix obtained from registering each of the original T1-weighted image MNI space, to the hippocampi label: To register T1 image from native space to standard space ```gherkin= first_flirt <invol> <outvol> ``` To apply the transformation matrix to the hippocampi label to bring them to standard space as well: ```gherkin= flirt –in <invol> -ref <refvol> -out <outvol> -init <invol2refvol.mat> -applyxfm ``` However, this has already been done for you in this case. **DO NOT RUN THE ABOVE COMMANDS.** ::: >In the folder you will see 16 hippocampal labels for subjects s001-s008, for the left and right hemisphere each. We would want to get a boundary mask of these hippocampal labels. This is akin to the ‘average shape’ that we will base further statistical analysis on. To do so: ```gherkin= #Average all the transformed manual labels together (use fslmaths to add them up and divide by the number of images) fslmaths s001_LHipp_std.nii -add s002_LHipp_std.nii -add s003_LHipp_std.nii -add s004_LHipp_std.nii -add s005_LHipp_std.nii -add s006_LHipp_std.nii -add s007_LHipp_std.nii -add s008_LHipp_std.nii all_LHipp.nii.gz fslmaths all_LHipp.nii.gz -div 8 avg_LHipp.nii.gz #Threshold the average image to get an average shape (you can choose any threshold that gives a good-looking result, although something between 0.5 and 0.9 is likely to be good, depending on how much variation there is after registration. Have a look at your image). #Try thresholding at 0.5, 0.6, 0.7, and 0.8. Compare you output visually. fslmaths avg_LHipp.nii.gz -thr 0.6 thr6_LHipp.nii.gz #Form a boundary image by taking the thresholded result, eroding by one voxel, fslmaths thr6_LHipp.nii.gz -ero thr6_ero_LHipp.nii.gz #and subtracting the eroded version from the original fslmaths thr6_LHipp.nii.gz -sub thr6_ero_LHipp.nii.gz bound6_LHipp.nii.gz ``` >Next, to get a distance map from EACH hippocampal label: ```gherkin= #Threshold each hippocampal label at 0.5 to form a binary image (called innermask) fslmaths s001_LHipp_std.nii -thr 0.5 -bin s001_LHipp_innermask.nii #You will have to do this for all subjects’ hippocampal label (s001-s008) # you can create a for-loop for running iterative commands, # but lets not worry about this step for now. fslmaths s002_LHipp_std.nii ... fslmaths s003... ... #Run distancemap to calculate the distance of the average boundary points to the inner and outer masks separately: distancemap -i s001_LHipp_innermask.nii -m bound6_LHipp.nii -o s001_LHipp_innerdist.nii #Distance to points smaller than the boundary mask distancemap -i s001_LHipp_innermask.nii -m bound6_LHipp.nii --invert -o s001_LHipp_outerdist.nii #Distance to points larger than boundary mask) #Finally, calculate the signed distance by summing up the inner and outer dist fslmaths s001_LHipp_innerdist.nii -mul -1 -add s001_LHipp_outerdist.nii s001_signdist.nii ``` >The signed distance map should overlap perfectly with the boundary image. Have a look at it. This signed distance map can then be used for further statistical analysis. > :::info *to run permutation testing through FSL (randomse/PALM), you will need to merge the signed distance maps into a single 4D volume* ```gherkin= fslmerge -t <output_name> <input1> <input2> <input3> ... ``` ::: ## Permutation testing - randomise To run the statistical analysis, I have generally favoured FSL's [randomise](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Randomise/UserGuide) or [PALM](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/PALM). More details about the usage can be found on their website, but for now lets give **Randomise** a try. >There will be a folder on your project directory titled 'randomise', ```gherkin= cd ~/sk75/${USER}_hippocampus_vertex/randomise ``` >where you will find: >- **226_RHipp_HCvPT.nii.gz** - a 4D input file of 226 subjects' right hippocampus (an example from my manually-traced dataset) >- **226_RHipp_BOUND.nii** - the boundary mask created from the average of all subjects >- **ttest.mat** and **ttest.con** - design matrix and contrast files for a two-group t-test > >Lets run the following commands ```gherkin= module load fsl randomise -i 226_RHipp_HCvPT.nii.gz -o RHipp_testout -d ttest.mat -t ttest.con -m 226_RHipp_BOUND.nii -n 100 -T ``` > Have a look at the output in fsleyes. Try to work out what the output files reflect. ## Help/feedback? :cat: - <yannying.chye@monash.edu> - [twitter](https://twitter.com/YannChye)