Montréal Paris Neurobanque (MPN) 7T MRI Data Processing Pipeline

Overview

This repository hosts scripts and tools for processing and managing high-resolution 7T MRI data as part of the MPN initiative. The aim is to facilitate open data sharing and streamline quality control (QC) and preprocessing using an integrated pipeline that connects LORIS, CBRAIN, and micapipe, following BIDS standards.

| | | | |:---:|:---:|:---:| | Seamlessly manages raw and BIDS-formatted data, facilitating initial QC annotation. | Connects to LORIS to run QC and preprocessing tools, extracting and feeding back QC metrics and initial derivatives. | Performs standardized preprocessing of MRI data and generates derivatives. |

Repository Contents

| File | Description | |:--------------:|:--------------------------------------------------------------------------------| | README | Detailed documentation on the project's goals, setup instructions, and usage guidelines. | | LICENSE | Information on the repository's licensing terms for open-source distribution. | | Dockerfile | Configuration to containerize the pipeline for reproducibility and easy deployment. | | Functions | Directory with the functions. |

Workflow

The data processing workflow begins by transferring raw MRI data, in both BIDS and MINC format, to the LORIS platform. Once uploaded, initial quality control (QC) annotations are performed on LORIS using both automated tools and human evaluations. The data is then linked to CBRAIN, where automated QC metrics are extracted for further analysis. Following this, the QC reports on LORIS are reviewed and classified as either "pass" or "fail." Once the data is approved, it is transferred back to LORIS for preprocessing with micapipe. micapipe then generates initial derivatives while applying additional QC measures to ensure the integrity of the data throughout the entire pipeline.

MRI transfering steps

Option 1. Raw DICOM to to NIfTI BIDS

1. Organizes raw DICOM into a temporary structurated directories
2. Transforms the sorted dicoms into BIDS
3. Run BIDS validator through deno

bash dcm2bids.py --dicoms_dir MPN00001_sorted/ --bids_dir /BIDS_MPN/rawdata --sub MPN00001 --ses v1

Option 2. Sorted DICOM to NIfTI BIDS

bash dcm2bids.py --dicoms_dir MPN00001_sorted/ --sorted_dir MPN00001_sorted/ --bids_dir /BIDS_MPN/rawdata --sub MPN00001 --ses v1

3. Integrated BIDS validation

bash deno run --allow-write -ERN jsr:@bids/validator {bids_dir} --ignoreWarnings --outfile {bids_dir}/bids_validator_output.txt

Running micapipe v0.2.3 with container

bash mpn_micapipe.sh <subject> <session> <path to singularity image>

Naming dictionary

Anatomical

| N | 7T Terra Siemens acquisition | BIDS | Directory | |:-----:|:--------------------------------------------------:|:-----------------------------------:|:-------------:| | 1 | anat-T1wacqmprage0.8mmCSptx | T1w | anat | | 2 | anat-T1wacq-mp2rage0.7mmCSptxINV1 | inv-1MP2RAGE | anat | | 3 | anat-T1wacq-mp2rage0.7mmCSptxINV2 | inv-2MP2RAGE | anat | | 4 | anat-T1wacq-mp2rage0.7mmCSptxT1Images | T1map | anat | | 5 | anat-T1wacq-mp2rage0.7mmCSptxUNIImages | UNIT1 | anat | | 6 | anat-T1wacq-mp2rage0.7mmCSptxUNI-DEN | desc-denoisedUNIT1 | anat | | 7 | anat-flairacq-0p7isoUPAdia | FLAIR | anat | | 8 | CLEAR-SWIanat-T2staracq-megre0*7isoASPIRE | acq-SWIT2starw | anat | | 9 | RomeoPanat-T2staracq-megre0*7isoASPIRE | acq-romeoT2starw | anat | | 10 | RomeoMaskanat-T2staracq-megre0*7isoASPIRE | acq-romeodesc-maskT2starw | anat | | 11 | RomeoB0anat-T2staracq-megre0*7isoASPIRE | acq-romeodesc-unwrappedT2starw | anat | | 12 | AspireManat-T2staracq-megre0*7isoASPIRE | acq-aspirepart-magT2starw | anat | | 13 | AspirePanat-T2staracq-megre0*7isoASPIRE | acq-aspirepart-phaseT2starw | anat | | 14 | EchoCombinedanat-T2staracq-megre0*7isoASPIRE | acq-aspiredesc-echoCombinedT2starw | anat | | 15 | sensitivitycorrectedmaganat-T2staracq-megre0*7isoASPIRE | acq-aspiredesc-echoCombinedSensitivityCorrectedT2starw | anat | | 16 | T2staranat-T2staracq-megre0*7isoASPIRE | acq-aspire[T2starw,T2starmap] | anat | | 17 | anat-mtwacq-MTON07mm | acq-mtwmt-onMTR | anat | | 18 | anat-mtwacq-MTOFF07mm | acq-mtwmt-offMTR | anat | | 19 | anat-mtwacq-T1w07mm | acq-mtwT1w | anat | | 20 | anat-nmacq-MTboostsag0.55mm | acq-neuromelaninMTwT1w | anat | | 21 | anat-angioacq-tof03mminplane | angio | anat | | 22 | anat-angioacq-tof03mminplaneMIPSAG | acq-sagangio | anat | | 23 | anat-angioacq-tof03mminplaneMIPCOR | acq-corangio | anat | | 24 | anat-angioacq-tof03mminplaneMIPTRA | acq-traangio | anat |

The acquisitions acq-romeo_part-phase_T2starw, acq-aspire_part-mag_T2starw, and acq-aspire_part-phase_T2starw each have five echoes. The final string will include the identifier echo- followed by the echo number. For example: acq-aspire_echo-1_part-mag_T2starw.

Field maps

| N | 7T Terra Siemens acquisition | BIDS | Directory | |:-----:|:--------------------------------------------:|:-------------------------------------:|:-------------:| | 1 | fmap-b1trap2 | acq-[anat,sfam]TB1TFL | fmap | | 2 | fmap-b1acq-sagp2 | acq-[anat,sfam]TB1TFL | fmap | | 3 | fmap-fmriacq-mbep2dSE19mmdir-AP | acq-fmridir-APepi | fmap | | 4 | fmap-fmriacq-mbep2dSE19mmdir-PA | acq-fmridir-PAepi | fmap |

Functional

| N | 7T Terra Siemens acquisition | BIDS | Directory | |:-----:|:--------------------------------------------:|:-------------------------------------:|:-------------:| | 1 | func-crossacq-ep2dMJC19mm | task-restbold | func | | 2 | func-cloudyacq-ep2dMJC19mm | task-cloudybold | func | | 3 | func-presentacq-mbep2dME19mm | task-presentbold | func |

Each functional MRI acquisition includes three echoes and a phase. The final string will contain the identifier echo- followed by the echo number (e.g., task-rest_echo-1_bold). Additionally, the string part-phase will be included to identify the phase (e.g., task-rest_echo-1_part-phase_bold).

Naming convention | Diffusion weighted Images

| N | 7T Terra Siemens acquisition | BIDS | Directory | |:-----:|:--------------------------------------------:|:-------------------------------------:|:-------------:| | 1 | *dwiacqb0PA | acq-b0dir-PAdwi | dwi | | 2 | *dwiacqb0PASBRef | acq-b0dir-PAsbref | dwi | | 3 | *dwiacqmultib38dirAPacc9 | acq-multib38dir-APdwi | dwi | | 4 | *dwiacqmultib38dirAPacc9SBRef | acq-multib38dir-APsbref | dwi | | 5 | *dwiacqmultib70dirAPacc9 | acq-multib70dir-APdwi | dwi | | 6 | *dwiacqmultib70dirAPacc9SBRef | acq-multib70dir-AP_sbref | dwi |

The string part-phase will be included to identify the phase acquisitions (e.g., acq-multib38_dir-AP_part-phase_dwi).

Abbreviation Glossary

| Abbreviation | Description | |-------------------|---------------------------------------------------------------| | AP | Anterio-Posterior | | PA | Postero-anterior | | mtw | Magnetic transfer weighted | | sfmap | Scaled flip angle map | | tof | Time of flight | | multib | Multi shell N directions | | semphon | Semantic-phonetic | | romeo | Rapid opensource minimum spanning tree algorithm | | aspire | Combination of multi-channel phase data from multi-echo acquisitions |

References

1. Eckstein K, Dymerska B, Bachrata B, Bogner W, Poljanc K, Trattnig S, Robinson SD. Computationally efficient combination of multi‐channel phase data from multi‐echo acquisitions (ASPIRE). Magnetic resonance in medicine. 2018 Jun;79(6):2996-3006. https://doi.org/10.1002/mrm.26963

2. Dymerska B, Eckstein K, Bachrata B, Siow B, Trattnig S, Shmueli K, Robinson SD. Phase unwrapping with a rapid opensource minimum spanning tree algorithm (ROMEO). Magnetic resonance in medicine. 2021 Apr;85(4):2294-308. https://doi.org/10.1002/mrm.28563

3. Sasaki M, Shibata E, Tohyama K, Takahashi J, Otsuka K, Tsuchiya K, Takahashi S, Ehara S, Terayama Y, Sakai A. Neuromelanin magnetic resonance imaging of locus ceruleus and substantia nigra in Parkinson's disease. Neuroreport. 2006 Jul 31;17(11):1215-8. https://doi.org/10.1097/01.wnr.0000227984.84927.a7

Requirements

| Package | Version | |:-----------------:|:-------------:| | python | 3.8 | | dcm2niix | 1.0.20240202 | | jq | 1.6 | | bids_validator | 2.0.0 | | deno | 2.0.6 |

Runing singularity

```bash

Define directories

bids=/BIDSMPN/rawdata/ dicoms=/BIDSMPN/dicoms

Path to singularity image

img=/dcm2bids_v0.1.2.sif

Define subject and session

sub=MPNphantom ses=v1

Call singularity

singularity run --writable-tmpfs --containall \ -B ${bids}:/bids -B ${dicoms}:/dicoms \ ${img} --sub $sub --ses $ses --dicomsdir /dicoms --sorteddir /dicoms --bids_dir /bids ```