2 Getting started

Authors

Affiliations

Christina Rubino

source("glossary_setup.R")

You need to have the following programs installed:

fsl as well as
R and RStudio (or similar) installed.
I also highly recommend the package ITK-SNAP, which can be used for some (semi-)manual mask modifications.
You may want to use the powerful ANTs package (or the underlying ANTsR package) for registration. The included script, to is provided by Dr. Dianne Patterson, PhD.

2.1 Let’s get to it

Keep a backup

Before starting, be warned. The script might override original data with modified data without warning. Please keep a backup of original files. Now you have been warned.

Script files are located in the codes folder like below.

${normalisation-pipeline}
├── ...
├── codes
   ├── 00norm_prep_pipeline.sh
   ├── T1_2_MNI152_1mm.cnf
   ├── ant_reg3_bbl.sh
   ├── file-structure.R
   ├── fsl_anat_alt_bbl.sh
   ├── fsl_norm_bbl.sh
   ├── modified_brain_mask_bbl.sh
   ├── multi_punch.sh
   ├── nemo-packing.R
   ├── optiBET.sh
   └── prep_T1w_bbl.sh
├── ...

Download or clone the repository to your computer and extract the folder if necessary. Move the contents of the codes folder to whereever you find appropriate (or just leave them for now). This is now the “codes folder” and will be referenced as /codes/folder/ in the script examples. Edit this to run on your computer.

Now, open a terminal window and navigate to in the parent directory of your data folder, which we will now refer to as the “root directory”.

This pipeline assumes, that your files are organised in the following way. This is not completely according to the BIDS-format, but that might be coming in the future. For now, this is the way:
```
${ROOT}
├── sub01
    ├── sub01_T1w.nii.gz (T1 weighted base image)
    ├── sub01_lesion.nii.gz (lesion mask, optional)
├── subNN
    ├── subNN_T1w.nii.gz
    ├── subNN_lesion.nii.gz
```
If, your files are like this, just jump ahead. If your files are all on one folder, but named as above, you can use the file-prep.R script to organise subject files into subfolders. Open the script and edit the first three variables. Save it and then, run the following in the terminal window:
```
Rscript file-prep.R
```
Now the files and folders should be structured as expected.
Optional: If you want to do registration to 1mm MNI space, you need to add a new config file to fsl. If not, skip ahead. The config file is the .cnf file in your codes folder, and it can be copied to the correct location using the following command:
```
imcp /codes/folder/T1_2_MNI152_1mm.cnf $FSLDIR/etc/flirtsch/T1_2_MNI152_1mm.cnf
```
Depending on what you are doing, you’ll probably be fine doing 2mm registration, but for some use cases, the 1mm registration is necessary. Here is a discussion, I found useful on doing 1 or 2 mm.
Now you are ready for start data processing. The script has a few assumptions. It will look for a file with the file name pattern ‘[Ll]esion.nii.gz’, and assume this is a lesion mask for the T1 weighted image (which should be named ‘*T1w.nii.gz’). You may optionally specify the lesion mask file name pattern used, eg: sh 00norm_prep_pipeline.sh 1mm 'lesion.nii.gz'. If no lesion mask is in the folder, the script will just perform skull stripping and registration of the head/brain. The script will also assume you want 2mm registration and do so with fsl. To view the documentation and see a few examples run this:
```
sh /codes/folder/00norm_prep_pipeline.sh -h
```
Then, when ready run the main script with your desired settings. Now processing starts, and it will take some time. Sit back and relax while your computer hums away. Or do something else in the meantime. You’ll get time stamps along the way to have an idea of the progress and the time needed. The output files are written along the way, so you can manually check the output while the script works. Note that your original T1 and lesion mask will have “_orig” appended as suffix and be substituted with corrected files. If the script gets interrupted, you can just restart it, and it will skip subjects already processed. Make sure you delete the output files, if you want the script to rerun on a specific subject.
Now it is time for quality control. Please refer to the separate Chapter 3 on this. Then, you are done and can use these normalised files however you like.

2.2 Glossary

term	definition
ANTs	Advanced Normalization Tools. https://github.com/ANTsX/ANTs
BIDS	Brain Imaging Data Structure. https://bids-standard.github.io/bids-starter-kit/index.html
fsleyes	Thes picture viewing tool from the fsl-package. https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FSLeyes
registration	I this context, registration denotes to art of registrering to normal space. In this case to the MNI space. Think of it as normalising data.