Coffee Chat Brewing AI Knowledge

eng kor

[MRIQC 3] Running MRIQC: A Step-by-Step Guide using nii2dcm, Heudiconv, and MRIQC

20 May 2024     #bio #brainImaging

MRIQC analyzes and evaluates the quality of the input MRI images and compiles the relevant information into a report. To use MRIQC, you need MRI images stored in the BIDS format. In this post, I will detail the process of running MRIQC and obtaining analysis results using DICOM files.


nii2dcm

While I used DICOM files here, NIfTI is also a common MRI file format. If you are using NIfTI files, you can use a BIDS converter that supports NIfTI or convert the NIfTI files to DICOM and then use a DICOM-supported BIDS converter. Based on my personal experience, BIDS converters that support NIfTI did not work reliably (though this might have been due to my own mistakes). You can use the nii2dcm library to convert NIfTI files to DICOM. Refer to the code below:

nii2dcm NIFTI_FILE_DIR OUTPUT_DIR -d MR
  • NIFTI_FILE_DIR: Path to the NIfTI file you want to convert
  • OUTPUT_DIR: Path where the converted DICOM files will be saved


Heudiconv

I used Heudiconv as the BIDS converter. I summarized the instructions by referring to the tutorial provided on the official page. Here’s how to use it:

Installing Heudiconv

Install via PyPI:

pip install heudiconv

Adjusting heuristic.py

Write a code to define the rules for saving each image in the BIDS format. You can refer to or modify the heuristic.py file from the data repository provided in the tutorial. This file determines the modality of the input image files and creates file paths that conform to the BIDS format for each modality, saving the images accordingly. Modify the judgment criteria and save paths as necessary.

The function to refer to and modify is infotodict() in heuristic.py.

  • Identify the modality of the images to be used: T1WI, T2WI, DWI, etc.
  • Delete or comment out the code related to unused modalities.
  • Check the path format where the modality images will be saved and modify it if needed.
  • Specify and modify the criteria (dimensions, current filename characteristics, etc.) in the conditional statements to distinguish each modality.

The modified example code is as follows. For T1WI and DWI, the path where the images will be saved and the conditions to determine the image modality have been set.

Running Heudiconv

After installation, set the parameters and run it as follows. Heudiconv can process multiple sets of subject data, i.e., multiple bundles of DICOM files, at once.

heudiconv --files DICOM_FILE_DIRS -o OUTPUT_DIR -f HEURISTIC.PY -s SUB_ID -ss SES_ID -c dcm2niix -b minmeta --overwrite
  • DICOM_FILE_DIRS: Input the DICOM files for multiple subjects in a globbing format (e.g., dataset/sub-001/ses-001//.dcm)
  • OUTPUT_DIR: Path where the converted BIDS format folder will be saved
  • HEURISTIC.PY: Path to the heuristic.py file created above
  • SUB_ID: Subject id (e.g. 001)
  • SES_ID: Session id (e.g. 001)

Here is an example of how to run it. Enter the following code:

heudiconv --files data/*/*.dcm -o bids/data/ -f heuristic.py -s 0 -ss 0 -c dcm2niix -b minmeta --overwrite

BIDS format folders will be created under bids/data/ as follows:


MRIQC

Once the MRI images are stored in the BIDS format, they can be input into MRIQC. MRIQC can be used by downloading the package via PyPI or through a Docker container.

With PyPI

First, install it using the following code:

python -m pip install -U mriqc

After installation, run the following code:

mriqc BIDS_ROOT_DIR OUTPUT_DIR participant --participant-label SUB_ID
  • BIDS_ROOT_DIR: Root path of the BIDS format folder
  • OUTPUT_DIR: Path where the MRIQC results will be saved
  • participant OR group: If set to participant, MRIQC analysis results will be obtained per subject; if set to group, MRIQC will analyze all images under the root path.
  • SUB_ID: In participant mode, specify the subject ID for analysis by entering it in --participant-label. Multiple IDs can be entered at once (e.g., --participant-label 001 002 003).

With Docker

I used MRIQC through Docker. The advantage of Docker containers is that they include all dependencies needed to run the program, ensuring a consistent environment. Enter the following code to run MRIQC at the participant level:

docker run -it --rm -v BIDS_ROOT_DIR:/data:ro -v OUTPUT_DIR:/out nipreps/mriqc:latest /data /out participant --participant_label SUB_ID [--verbose-reports]

Even if the nipreps/mriqc image is not downloaded, it will automatically download when you run the code.

  • BIDS_ROOT_DIR: Root path of the BIDS format folder. This is connected to the /data folder inside the container using the -v flag. The ro option stands for ‘read only’, meaning the path can only be read from the local path to the container path.
  • OUTPUT_DIR: Path where the MRIQC results will be saved. This is connected to the /out folder inside the container. If you copy the contents of the /out folder in the container to your local machine, you will see that the results are saved in the OUTPUT_DIR.
    • To copy the internal container files: When running the above docker run command, remove the --rm (remove container after completion) option. After completion, execute docker cp CONTAINER_NAME:FILE_PATH LOCAL_PATH.
  • SUB_ID: Subject ID. Multiple IDs can be entered. (e.g. --participant_label 001 002 003)
  • --verbose-reports (Optional): If this flag is included, four additional plots will be reported along with the default visual report plot.

After running the above code, you can check the list of Docker images and containers to see the MRIQC-related items that have been executed.

docker_ex


MRIQC Results

mriqc_ex1_1

When the MRIQC analysis is complete, the above-mentioned files will appear under the OUTPUT_DIR. Among these, the analysis results are contained in the plot image files within the figures folder, and the JSON and HTML files named after the respective files, such as sub-0_ses-0_T1w.json and sub-0_ses-0_T1w.html in this example. The results report is generated as an HTML file based on the plot images and JSON files.

ex1 ex2 ex3

By opening the HTML file, you can view a report like the one above. By interpreting the report using the visualized plots and quality metric scores, you can determine the quality of the images.


References


Related posts