tidied workshops and README

LICENSE

@@ -23,4 +23,4 @@ You do not have to comply with the license for elements of the material in the p
 
 No warranties are given. The license may not give you all of the permissions necessary for your intended use. For example, other rights such as publicity, privacy, or moral rights may limit how you use the material.
 
-© 2024 University of Birmingham
+© 2025 University of Birmingham

README.md

@@ -4,7 +4,7 @@
 
 ![GitHub stars](https://img.shields.io/github/stars/chbh-opensource/mri-on-bear-edu) ![GitHub repo size](https://img.shields.io/github/repo-size/chbh-opensource/mri-on-bear-edu)
 
-> 🎯 **Purpose:** A freely available resource for the 'Magnetic Resonance Imaging in Cognitive Neuroscience' course at the Centre for Human Brain Health
+> **Purpose:** A freely available resource for the 'Magnetic Resonance Imaging in Cognitive Neuroscience' course at the Centre for Human Brain Health
 
 Welcome to the MRI-on-BEAR website, a freely available resource created by researchers at the [Centre for Human Brain Health](https://www.birmingham.ac.uk/research/centre-for-human-brain-health), University of Birmingham. The website is made for students on the 'Magnetic Resonance Imaging in Cognitive Neuroscience' course, but may also be useful to external students and researchers. However, please BEAR in mind that the course materials were designed to run on computing resources at the University of Birmingham!
 
@@ -41,25 +41,23 @@ Whilst not mandatory, additional resources related to the course can also be fou
 
 If you encounter any issues or have questions please contact the following:
 
-### 📚 Course-related Issues
+### Course-related Issues
 - **Dr Magda Chechlacz** (Module Lead)
-  - 📧 [m.chechlacz@bham.ac.uk](mailto:m.chechlacz@bham.ac.uk)
+  - [m.chechlacz@bham.ac.uk](mailto:m.chechlacz@bham.ac.uk)
 
-### 💻 IT/Computing Support
+### IT/Computing Support
 - **Charnjit Sidhu** (Lead Computing Officer, CHBH)
-  - 📧 [c.sidhu@bham.ac.uk](mailto:c.sidhu@bham.ac.uk)
+  - [c.sidhu@bham.ac.uk](mailto:c.sidhu@bham.ac.uk)
 
-### 🌐 Website/GitHub enquiries
+### Website/GitHub enquiries
 - **Aamir Sohail** (Module Teaching Assistant)
-  - 📧 [axs2210@bham.ac.uk](mailto:axs2210@bham.ac.uk)
+  - [axs2210@bham.ac.uk](mailto:axs2210@bham.ac.uk)
 
-> ⏰ Please contact us during working hours (9am-5pm)!
-
-## 🛠️ Contributing (for CHBH staff)
+## Contributing (for CHBH staff)
 
 If you teach on the course, or are a staff member at the CHBH and could like to contribute to the website, please follow the instructions below.
 
-### 🔧 Development Setup
+### Development Setup
 
 You will firstly need to re-create the website locally. The website is built using [MkDocs](https://www.mkdocs.org/), which is nice and easy to work with. After cloning the repository, to install all the required `mkdocs` Python packages, use the provided `requirements.txt` file within the root of this repository. The recommendation for development is to do this inside a dedicated virtual environment. 
 

docs/workshop1/workshop1-intro.md

@@ -8,10 +8,10 @@ Linux OS is similar to other operating systems such as Mac OS and Windows, and c
 !!! success "Overview of Workshop 1"
     Topics for this workshop include:
 
-    - Introduction to the BEAR Portal
+    - An introduction to the BEAR Portal
     - Using the BlueBEAR Graphical User Interface (GUI) environment
     - Navigating files and directories in the BEAR Portal
-    - Introduction to Linux, and using basic Linux commands in the Terminal
+    - An introduction to Linux, and using basic Linux commands in the Terminal
 
 !!! danger "Pre-requisites for the workshop"
     Please ensure that you have completed the '[Setting Up](https://chbh-opensource.github.io/mri-on-bear-edu/setting-up/)' section of this course, as you will require access to the BEAR Portal for this workshop.

docs/workshop2/mri-data-formats.md

@@ -108,9 +108,9 @@ cd 20191008#C4E7_dicom
 ls
 ```
 
-You should see a list of 7 sub-directories. Each top level DICOM directory contains sub-directories with each individual scan sequence. The structure of DICOM directories can vary depending on how it is stored/exported on different systems. <b>The 7 sub-directories here contain data for four localizer scans/planning scans, two fMRI scans and one structural scan.</b> Each sub-directory contains several `.dcm` files.
+You should see a list of 7 sub-directories. Each top level DICOM directory contains sub-directories with each individual scan sequence. The structure of DICOM directories can vary depending on how it is stored/exported on different systems. <b>The 7 sub-directories here contain data for four localizer scans/planning scans, two fMRI scans and one structural scan.</b> Each sub-directory also contains several `.dcm` files.
 
-There are several software packages which can be used to convert DICOM to NIfTI, but `dcm2niix` is the most widely used. It is available as standalone software, or part of [MRIcroGL](https://www.nitrc.org/plugins/mwiki/index.php/mricrogl:MainPage) a popular tool for brain visualization similar to FSLeyes. `dcm2niix` is available on BlueBEAR, but to use it you need to load it first using the terminal.
+There are several software packages which can be used to convert DICOM to NIfTI, but `dcm2niix` is the most widely used. It is available as standalone software, or part of [MRIcroGL](https://www.nitrc.org/plugins/mwiki/index.php/mricrogl:MainPage), a popular tool for brain visualization similar to FSLeyes. `dcm2niix` is available on BlueBEAR, but to use it you need to load it first using the terminal.
 
 To do this, in the terminal type:
 
@@ -129,7 +129,7 @@ If you now check the `T1_vol_v1_5` sub-directory, you should find there a single
 !!! example "Converting more MRI data"
     Now try to convert to NIfTI the `.dcm` files from the scanning session `20221206#C547` with 3 DICOM sub-directories, the two diffusion scans `diff_AP` and `diff_PA` and one structural scan MPRAGE. 
 
-    To do this, you will first need to change current directory, unzip, change directory again and then run the `dcm2niix` command as above.
+    To do this, you will first need to change the current directory, unzip, change the directory again and then run the `dcm2niix` command as above.
 
 If you have done it correctly you will find `.nii` and `.json` files generated in the structural sub-directories, and in the diffusion sub-directories you will also find `.bval` and `.bvec` files.
 

docs/workshop2/visualizing-mri-data.md

@@ -19,7 +19,7 @@ To open FSLeyes, type:
 
 `module load FSL/6.0.5.1-foss-2021a-fslpython`
 
-There are different version of FSL on BlueBEAR, however this is the one which you need to use it together with FSLeyes.
+There are different versions of FSL on BlueBEAR, however this is the one which you need to use it together with FSLeyes.
 
 Wait for FSL to load and then type:
 
@@ -41,7 +41,12 @@ You should then see the setup below, which is the default FSLeyes viewer without
 
 You can now load/open an image to view. Click 'File' → 'Add from file' (and then select the file in your directory e.g., `rds/projects/c/chechlmy-chbh-mricn/xxx/CHBH/visualization/T1.nii`).
 
-You can also type directly in the terminal `fsleyes file.nii.gz` where you replace `file.nii.gz` with the name of the actual file you want to open. 
+You can also type directly in the terminal:
+
+`fsleyes file.nii.gz` 
+
+where you replace `file.nii.gz` with the name of the actual file you want to open. 
+
 However, you will need to include the full path to the file if you are not in the same directory when you open the terminal window e.g. `fsleyes rds/projects/c/chechlmy-chbh-mricn/xxx/CHBH/visualization/T1.nii`
 
 You should now see a T1 scan loaded in ortho view with three canvases corresponding to the sagittal, coronal, and axial planes.
@@ -141,7 +146,7 @@ Now select from the menu 'Settings' → 'Ortho View 1' and tick the box for 'Atl
 You should now see the 'Atlases' panel open as shown below.  
 
 <p align="center">
-  <img src="../../assets/images/workshop2/visualizing-mri-data/fsleyes_atlas_gui.png" alt="FSLeyes atlas GUI" width="900" height="300">
+  <img src="../../assets/images/workshop2/visualizing-mri-data/fsleyes_atlas_gui.png" alt="FSLeyes atlas GUI" width="1000" height="300">
 </p>
 
 The 'Atlases' panel is organized into three sections: 
@@ -231,8 +236,8 @@ Click the (Show/Hide) link after the Left Amygdala; the amygdala overlay will di
 
     If unsure check your results with someone else, or ask for help! 
 
-<b>Make sure all overlays are closed (but keep the `MNI152_T1_2mm.nii.gz` open) before moving to the next section.</b>
-
+!!! warning "Before continuing"
+    Make sure all overlays are closed (but keep the `MNI152_T1_2mm.nii.gz` open) before moving to the next section.
 
 ## Using atlas tools to find a brain structure
 
@@ -251,7 +256,7 @@ Now click on the '+' button next to the tick box. This will centre the viewing c
 </p>
 
 !!! example "Exercise: Atlas visualization"
-    Now try this for yourself: 
+    Now try the following exercises for yourself: 
 
     - <b>Remove the Heschl's Gyrus visualization.</b> You can tick it off in the 'Atlases' window, or select Heschl's Gyrus in the 'Overlay list' window, and then either toggle its visibility off (click the eye icon) or remove it ('Menu' → 'Overlay' → 'Remove').
     - <b>Visualize the Lingual Gyrus and Left Hippocampus.</b> To avoid confusion, change the colour of the Lingual Gyrus visualization from red/yellow to green and Left Hippocampus to blue.
@@ -271,16 +276,12 @@ This time, in the left panel listing different atlases, tick on the option for o
   <img src="../../assets/images/workshop2/visualizing-mri-data/harvard_oxford.png" alt="Harvard Oxford" width="800" height="300">
 </p>
 
-<br>
-
 Now you should see all of the areas covered by the Harvard-Oxford cortical atlas shown on the standard brain. You can click around with the cursor, the labels for the different areas can be seen in the bottom right panel.
 
 <p align="center">
   <img src="../../assets/images/workshop2/visualizing-mri-data/harvard_oxford_atlas.png" alt="Harvard Oxford Atlas" width="900" height="300">
 </p>
 
-<br>
-
 In addition to atlases covering various grey matter structures, <b>there are also two white matter atlases</b>: the JHU ICBM-DTI-81 white-matter labels atlas & JHU white-matter tractography atlas. 
 If you tick (select) these atlases as per previous instructions (hint using the 'Atlas search' tab), you will see a list of all included white matter tracts (pathways) as shown below:
 
@@ -319,7 +320,7 @@ Wait for FSLeyes to load, then:
 You should now see the MFG overlay in the overlay list (as below) and have a `MFG.nii.gz` file in the `ROImasks` directory. You can check this by typing `ls` in the terminal.
 
 <p align="center">
-  <img src="../../assets/images/workshop2/visualizing-mri-data/mfg_roi.png" alt="MFG ROI" width="800" height="300">
+  <img src="../../assets/images/workshop2/visualizing-mri-data/mfg_roi.png" alt="MFG ROI" width="900" height="300">
 </p>
 
 We will now create a white matter mask. Here are the steps:
@@ -331,7 +332,7 @@ We will now create a white matter mask. Here are the steps:
 You should now see the FM overlay in the overlay list (as below) and also have a `FM.nii.gz` file in the `ROImasks` directory. 
 
 <p align="center">
-  <img src="../../assets/images/workshop2/visualizing-mri-data/forceps_roi.png" alt="MFG ROI" width="800" height="300">
+  <img src="../../assets/images/workshop2/visualizing-mri-data/forceps_roi.png" alt="MFG ROI" width="900" height="300">
 </p>
 
 You now have two “probabilistic ROI masks”. To use these masks for various analyses, you need to first binarize these images.

docs/workshop2/workshop2-intro.md

@@ -8,7 +8,7 @@ In this workshop we will explore, MRI image fundamentals, MRI data formats, data
 
     - The fundamentals of MRI data, including file types and formats
     - Converting between different MRI data files (e.g., DICOM to NIFTI)
-    - Introduction to FSLeyes and basic navigation
+    - An introduction to FSLeyes and basic navigation
     - Loading atlases and creating regions-of-interest (ROIs)
     - Binarizing and thresholding ROIs
 

docs/workshop3/diffusion-intro.md

@@ -90,7 +90,7 @@ Let's view the content of the `bvals` and `bvecs` files by using the `cat` comma
 `cat blip_down.bval`
 
 <p align="center">
-  <img src="../../assets/images/workshop3/diffusion-intro/cat_bval.png" alt="Cat bval" width="700" height="300">
+  <img src="../../assets/images/workshop3/diffusion-intro/cat_bval.png" alt="Cat bval" width="900" height="300">
 </p>
 
 The first number is 0. This indicates that indeed the first volume (volume 0) is a non-diffusion weighted image and the third volume (volume 2) is diffusion weighted volume with b=1500. 
@@ -118,7 +118,7 @@ All types of distortions need correction during pre-processing steps in diffusio
 The processing with these two tools is time and computing intensive. <b>Therefore we will not run the distortion correction steps in the workshop but instead explore some principles behind it.</b> 
 
 <p align="center">
-  <img src="../../assets/images/workshop3/diffusion-intro/distortion_types.png" alt="Distortion Types" width="700" height="300">
+  <img src="../../assets/images/workshop3/diffusion-intro/distortion_types.png" alt="Distortion Types" width="800" height="300">
 </p>
 
 For this, you are given distortion corrected data to conduct further analysis, diffusion tensor fitting and probabilistic tractography.  
@@ -203,11 +203,11 @@ and then open the 'BET brain extraction tool' by clicking on it in the GUI.
 In either case, once BET is opened, click on advanced options and make sure the first two outputs are selected ('brain extracted image' and 'binary brain mask') as below. Select as the 'Input' image the previously created `nodif.nii.gz` and change 'Fractional Intensity Threshold' to 0.4. Then click the 'Go' button. 
 
 <p align="center">
-  <img src="../../assets/images/workshop3/diffusion-intro/bet_gui.png" alt="BET GUI" width="600" height="300">
+  <img src="../../assets/images/workshop3/diffusion-intro/bet_gui.png" alt="BET GUI" width="800" height="300">
 </p>
 
 <p align="center">
-  <img src="../../assets/images/workshop3/diffusion-intro/bet_gui_detailed.png" alt="BET GUI Detailed" width="600" height="300">
+  <img src="../../assets/images/workshop3/diffusion-intro/bet_gui_detailed.png" alt="BET GUI Detailed" width="800" height="300">
 </p>
 
 !!! tip "Completing BET in the terminal"

docs/workshop3/diffusion-mri-analysis.md

@@ -27,13 +27,13 @@ To run the diffusion tensor fit, you need 4 files as specified below:
 In the FSL GUI, first click on 'FDT diffusion', and in the FDT window, select 'DTIFIT Reconstruct diffusion tensors'. Now choose as 'Input directory' the `data` subdirectory located inside `p01` and click 'Go'. 
 
 <p align="center">
-  <img src="../../assets/images/workshop3/diffusion-mri-analysis/dtifit_gui.png" alt="DTIfit GUI" width="900" height="300">
+  <img src="../../assets/images/workshop3/diffusion-mri-analysis/dtifit_gui.png" alt="DTIfit GUI" width="1000" height="300">
 </p>
 
 You should see something happening in the terminal and once you see 'Done!' you are ready to view the results.
 
 <p align="center">
-  <img src="../../assets/images/workshop3/diffusion-mri-analysis/dtifit_done.png" alt="DTIfit Done" width="100" height="300">
+  <img src="../../assets/images/workshop3/diffusion-mri-analysis/dtifit_done.png" alt="DTIfit Done" width="150" height="300">
 </p>
 
 Click 'OK' when the message appears.
@@ -72,6 +72,7 @@ This would be useful if you want to write a script; we will look at it in the la
     Again, please do NOT run it now but try it in your own time with data in the `p02` folder.
 
 The results of running DTIfit are several output files as specified below. <b>We will look closer at the highlighted files in bold.</b> 
+
 All of these files should be located in the `data` subdirectory, i.e. within `/rds/projects/c/chechlmy-chbh-mricn/xxx/diffusionMRI/DTIfit/p01/data/`.
 
 | Output File | Description |
@@ -127,7 +128,7 @@ The steps for Tract-Based Spatial Statistics are:
 5. Each participant’s aligned FA map is then projected back onto the skeleton prior to statistical analysis 
 6. Hypothesis testing (voxelwise statistics)
 
-To save time, some of the pre-processing stages including generating FA maps (tensor fitting), preparing data for analysis, registration of FA maps and skeletonization have been run for you and all outputs are included in the `data` folder you have copied at the start of this workshop. 
+To save time, <b>some of the pre-processing stages including generating FA maps (tensor fitting), preparing data for analysis, registration of FA maps and skeletonization have been run for you</b> and all outputs are included in the `data` folder you have copied at the start of this workshop. 
 
 <h2><div align="center"><b>Tract-Based Spatial Statistics analysis pipeline</b></div></h2>
 
@@ -187,7 +188,7 @@ cd FA
 imglob *_FA.*
 ```
 
-You should see data from the 5 older (o1-o5) followed by data fromthe  10 (y1-y10) younger participants.
+You should see data from the 5 older (o1-o5) followed by data from the 10 (y1-y10) younger participants.
 
 Next navigate back to the `stats` folder and open FSL:
 
@@ -200,7 +201,7 @@ fsl &
 Click on 'Miscellaneous tools' and select 'GLM Setup' to open the GLM GUI. 
 
 <p align="center">
-  <img src="../../assets/images/workshop3/diffusion-mri-analysis/tbss_glm.png" alt="TBSS GUI" width="250" height="300">
+  <img src="../../assets/images/workshop3/diffusion-mri-analysis/tbss_glm.png" alt="TBSS GUI" width="350" height="300">
 </p>
 
 <b>In the workshop we will set up a simple group analysis (a two sample unpaired t-test).</b>
@@ -284,7 +285,7 @@ You should see the same results as below:
     Are the results as expected? Why/why not?
 
 !!! example "Reviewing the tstat1 image"
-    Next review the `tbss_tfce_corrp_tstat1.nii.gz` 
+    Next review the image `tbss_tfce_corrp_tstat1.nii.gz`.
 
 !!! info "Further information on TBSS"
     More information on TBSS, can be found on the 'TBSS' section of the FSL Wiki: [https://fsl.fmrib.ox.ac.uk/fsl/docs/#/diffusion/tbss](https://fsl.fmrib.ox.ac.uk/fsl/docs/#/diffusion/tbss)

docs/workshop3/workshop3-intro.md

@@ -11,8 +11,8 @@ By the end of the two workshops, you should be able to understand the principles
 
     - Visualizing diffusion data using FSLeyes (before and after distortion correction)
     - Using FSL's Brain Extraction Tool (BET) to create a brain mask
-    - Understand and perform diffusion tensor fitting (DTIfit) to generate key diffusion metrics like FA (Fractional Anisotropy) and MD (Mean Diffusivity)
-    - Learn to conduct Tract-Based Spatial Statistics (TBSS) for group-level comparisons of diffusion data
+    - Performing diffusion tensor fitting (DTIfit) to generate key diffusion metrics like FA (Fractional Anisotropy) and MD (Mean Diffusivity)
+    - Learning to conduct Tract-Based Spatial Statistics (TBSS) for group-level comparisons of diffusion data
 
 We will be working with various previously acquired datasets (similar to the data acquired during the CHBH MRI Demonstration/Site visit). We will not go into details as to why and how specific sequence parameters and specific values of the default settings have been chosen. Some values should be clear to you from the lectures or assigned on Canvas readings, please check there, or if you are still unclear, feel free to ask.