Table of contents: <<TableOfContents()>>

= Converting CBU MRI DICOM data to BIDS format =
To start working with your MRI data, you need to convert the raw `DICOM` format data to `NIfTI` format and organise them according to the [[https://bids-specification.readthedocs.io/en/stable/|BIDS standard]]. This tutorial outlines how to do that. If you have any questions, please email [[https://www.mrc-cbu.cam.ac.uk/people/dace.apsvalka/|Dace]].
The example scripts described in this tutorial are available on our [[https://github.com/MRC-CBU/BIDS_conversion/tree/main/MRI|GitHub repository]].

To perform the conversion on your CBU MRI data, you need to be logged into [[http://intranet.mrc-cbu.cam.ac.uk/home/accessing-the-cbu-cluster-2019/|CBU Compute Cluster]].

== Where is your raw data ==

The raw data that come from the MRI scanner are stored at `/mridata/cbu/[your project code]`. 
You can see all your participant scan directories with a command like this (replace 'MR09029' with your project code):

{{{
ls -d /mridata/cbu/*_MR09029/*

/mridata/cbu/CBU210700_MR21002/20211208_143530/
/mridata/cbu/CBU210711_MR21002/20211213_103712/
/mridata/cbu/CBU220006_MR21002/20220106_115411/
/mridata/cbu/CBU220011_MR21002/20220107_125238/
...
}}}

The first part of the folder name which follows the project code, is the acquisition date. E.g., the data of the first subject in the example above was acquired on 08/12/2021 ('20211208').
Each subject's folder contains data like this: 

{{{
ls /mridata/cbu/CBU210700_MR21002/20211208_143530

Series001_64_Channel_Localizer/
Series002_CBU_MPRAGE_64chn/
Series003_bold_mbep2d_3mm_MB2_AP_2_SBRef/
Series004_bold_mbep2d_3mm_MB2_AP_2/
Series005_bold_mbep2d_3mm_MB2_AP_2_SBRef/
Series006_bold_mbep2d_3mm_MB2_AP_2/
Series007_bold_mbep2d_3mm_MB2_AP_2_SBRef/
Series008_bold_mbep2d_3mm_MB2_AP_2/
Series009_bold_mbep2d_3mm_MB2_AP_2_SBRef/
Series010_bold_mbep2d_3mm_MB2_AP_2/
Series011_bold_mbep2d_3mm_MB2_PA_2_SBRef/
Series012_bold_mbep2d_3mm_MB2_PA_2/
Series013_fieldmap_gre_3mm_mb/
Series014_fieldmap_gre_3mm_mb/
}}}

Each `Series###` folder contains DICOM files of the particular scan. The name of the folder is the same as what a radiographer named the scan in the MRI console. Usually, the name is very indicative of what type of scan it is. Ideally, you'd also know yourself what type of scans were acquired for your project. In the example above, we acquired a T1w anatomical/structural scan (MPRAGE), five multi-band functional scans with single-band reference scans for each of them, and two field maps. 


.. need to convert ..
Several conversion tools exist (see a full list [[https://bids.neuroimaging.io/benefits#converters|here]]). We recommend using [[https://heudiconv.readthedocs.io/en/latest/index.html|HeuDiConv]].

== DICOM to BIDS using HeuDiConv ==

`HeuDiConv` is available on our computing system as an Apptainer image 

`/imaging/local/software/singularity_images/heudiconv/heudiconv_latest.sif`

Converting DICOM data to BIDS using `HeuDiConv` involves 3 main steps:
 1. Discovering what type of scans there are in your data
 2. Creating a heuristics file specifying how to translate the scans into BIDS format
 3. Converting the data 

=== Step 1: Discovering your scans ===
...
{{{
#!/bin/bash

# ============================================================
# Discovering DICOM files using HeuDiConv
# ============================================================

# Your project's root directory
PROJECT_PATH='/imaging/correia/da05/wiki/BIDS_conversion/MRI'

# Location of the raw data
RAW_PATH='/mridata/cbu/CBU090942_MR09029'

# Location of the output data (it will be created if it doesn't exist)
OUTPUT_PATH=$PROJECT_PATH/data/work/dicom_discovery/

# Subject ID
subject="01"

# Load the apptainer module
module load apptainer

# Run the container
apptainer run --cleanenv \
    --bind "${PROJECT_PATH},${RAW_PATH}" \
    /imaging/local/software/singularity_images/heudiconv/heudiconv_latest.sif \
    --files "${RAW_PATH}"/*/*/*.dcm \
    --outdir "$OUTPUT_PATH" \
    --heuristic convertall \
    --subjects "${subject}" \
    --converter none \
    --bids \
    --overwrite

# Unload the apptainer module
module unload apptainer
}}}
=== Step 2: Creating heuristics file ===
...

=== Step 3: Converting the data ===

...

{{{
[da05@login-j05 MRI]$ squeue -u da05
             JOBID PARTITION     NAME     USER ST       TIME  NODES NODELIST(REASON)
         3246338_0      Main heudicon     da05  R       0:06      1 node-k08
         3246338_1      Main heudicon     da05  R       0:06      1 node-k08
         3246338_2      Main heudicon     da05  R       0:06      1 node-k08
         3246338_3      Main heudicon     da05  R       0:06      1 node-k08
}}}

== More examples ==
...
=== Functional scans with `sbref` ===
...

{{{
ls /mridata/cbu/CBU210700_MR21002/20211208_143530

Series001_64_Channel_Localizer/
Series002_CBU_MPRAGE_64chn/
Series003_bold_mbep2d_3mm_MB2_AP_2_SBRef/
Series004_bold_mbep2d_3mm_MB2_AP_2/
Series005_bold_mbep2d_3mm_MB2_AP_2_SBRef/
Series006_bold_mbep2d_3mm_MB2_AP_2/
Series007_bold_mbep2d_3mm_MB2_AP_2_SBRef/
Series008_bold_mbep2d_3mm_MB2_AP_2/
Series009_bold_mbep2d_3mm_MB2_AP_2_SBRef/
Series010_bold_mbep2d_3mm_MB2_AP_2/
Series011_bold_mbep2d_3mm_MB2_PA_2_SBRef/
Series012_bold_mbep2d_3mm_MB2_PA_2/
Series013_fieldmap_gre_3mm_mb/
Series014_fieldmap_gre_3mm_mb/
}}}

In this example, researchers acquired a T1w anatomical/structural scan (MPRAGE), five multi-band functional scans with single-band reference scans for each of them, two field maps, and ... 

=== Multiple sessions per subject ===
...
== Code examples ==

[[https://github.com/MRC-CBU/|code_examples on GitHub]]