How to perform MRI image pre-processing with Python and BASH: From DICOM to NIfTI to bias field correction

Learn how to pre-process 3D T1-weighted MRI images using Python — from DICOM to NIfTI conversion, ACPC alignment, and bias field correction — all in one user-friendly script.

MRI Image Pre-processing with Python and BASH: A Complete Guide

Why are we writing this and how it matters:

Pre-processing can take the longest time -or at least it feels like it takes the longest time, as it stands between you and your analysis, like a giant wall of delay and frustration you want to just push away.

Especially when there is no previous, effective system in place for all the steps that could be required for image processing.

These were our troubles when we tried to pre-process some 500+ 3D T1-weighted MRI brains one particularly cold winter…

We tried many things, but we are fans of one-step processes, or at least one-tool processing (in the end, it is 1 tool to pre-process them all and in quality data bind them. Not two, not 9, cause you will neither find them, nor get anything done. At least we could not!)

Heavily applied method alert coming through (we will put the minimum and maximum acceptable theory in the article below, and link to similar articles and relevant theory at the bottom.)

Photo by Bozhin Karaivanov on Unsplash

Purpose:

So that you do not have to use a Mac and a linux PC, another software, then another one, and then lose some of your sanity in the process.

1 tool, 1 script, all you need is the readme file, python 3 and some fundamental scripting experience.

And your data of course, to be added as a path

Specific materials and methods:

Before you start:

1. 3D T1-weighted MRI sequences acquired with either 1.5 T and 3T scanners. (we can expand the material once we have tested it on other sequences or when we have confirmation that it works on other acquisitions)

2. Basic scripting experience

You’ll need:

• Python 3.7+
• A Unix-based terminal (Linux, macOS, or WSL on Windows)
• Your MRI data in DICOM format

Follow the steps in the description as below:

MRI Pre-processing Tool

Step-by-step pre-processing guide

The main purpose of this python script is to perform a variety of common pre-processing functions for MRI images. From DICOM (.dcm) to NIfTI (.nii) conversion, to ACPC alignment and bias field correction (bfc).

The processing order is customisable, and any of the steps can be skipped through the use of command line flags (described in the ‘How to use’ section).

1. Setup process

To setup the script, Python (version 3.7 >) must be installed on the machine and python3 must be in the system path. To check if this is the case, open a terminal window (on Linux or Mac, or your WSL on windows) and run the following command: python3 — version. If the command returns some python version, everything should be okey. If the output is ‘command not found: python3’, Python is not installed on the machine.

# check if Python 3 is installed and ready for use
user@hostname:$python3 --version
Python 3.10.12

Assuming python is installed correctly, the setup procedure is as follows:

• Open a terminal window and go to the directory where the script is located.
• Enter the command “./setup.sh”. This will create a virtual environment ‘venv’ with the required python packages.

user@hostname:$cd /path/to/your/script #referred to hereafter as "userpath"
user@hostname:~/userpath$./setup.sh

Creating virtual environment...
Installing required packages...
Setup complete.

• Activate the virtual environment with the command “source venv/bin/activate”. The leftmost text in the terminal promts should now have changed to ‘(venv)’.

user@hostname:~/userpath$ source venv/bin/activate
(venv) user@hostname:~/userpath$

• If the following steps could be followed without errors, the script is ready to use.

How to use

To use the script, open a terminal and make sure you move to the directory where the script is located. (If you are picking up from the steps above, remember to ensure and the virtual environment is not active, by entering source venv/bin/activate as above)

The baseline usage of the script is of the form python3 pipeline.py -i <INPUT_DIR> -o <OUTPUT_DIR>, where <INPUT_DIR> and <OUTPUT_DIR> are the absolute or relative paths of the input and output directories respectively. This will perform the default processing step of dicom to niftii conversion.

Limitation: The script currently only accept input folders, so the input path cannot be set to a single dicom or niftii file.

2. DICOM to NIfTI conversion

#Example DICOM to NIfTI
(venv) user@hostname:~/userpath$python3 pipeline.py -i <INPUT_DIR> -o <OUTPUT_DIR>

Output data will by default be placed into <INPUT_DIR>/niftii, with each NIfTI (.nii) file placed into its own subfolder named according to its corresponding dicom folder name.

Using the flags described below you could also convert to a compressed NIfTI (see flags towards the end of the article).

3. ACPC Alignment

Important disclaimer: For this step, you will need to install acpcdetect from NITRC (NeuroImaging Tools and Resources Collaboratory). https://www.nitrc.org/projects/art

If you have acpcdetect installed on your machine, you can use some of its features directly from our github script (find the link at the end of the article). Installing and setting up acpcdetect can be done by following the instructions on their webpage (also provided in the download file) or by reading this easy to follow guide: https://www.nitrc.org/docman/?group_id=90.

Extreme but frequent misalignment in several MRI DICOM files

4. Bias Field Correction

WRITE MORE ON THIS.

#Runs steps in order: NIfTI conversion (n), ACPC alignment (a), Bias Field Correction (b).
(venv) user@hostname:~/userpath$python3 pipeline.py -i <INPUT_DIR> -o <OUTPUT_DIR> --do nab

5. Troubleshooting -Frequently encounted errors with ACPC and BFC: the decapitations

Sometimes violence is the answer

Sometimes you get a brain acquisition that looks like this after ACPC alignment:

After ACPC, malrotated, most likely du to several slices at the cervical level (neck)

The solution: off with the head (from the neck)! Technically, it is off with some neck but it is also a matter of perspective (are we cutting the head off the neck, or the neck off the head?)

So get the code-generated guillotine, and prepare to treat your head-and-neck volumetric file the same way deprived people who have the guts to stand up for themselves treat royal ignoramuses:

python3 pipeline.py -i ./dicom_data -o ./output_folder_name --do na --decap 20

#Removes the bottom 20% of slices and shifts the volume before ACPC alignment.

After 10% decap, malrotation fixed and alignment succeeded

30% decap in this case was too much and resulted in misalignment

Interim step: feel the glee of a successfully pre-processed image!

Final image after pre-processing: DICOM to NIfTI, acpc (Anterior-Posterior Commissure Alignemnt), bfc (Bias Field Correction), decap 10%

6. Miscellanea- Flags

• -i, — inDir — Directory of input data to perform actions on. (required)
• -o, — outDir — Directory to save output data into. (required)
• -z, — doZip — Save output nifti files in compressed format ‘.gz’.
• — do — Specify which processing steps to do. Possible options are:
• ’n’ — dcm to nifti conversion.
• ‘b’ — Bias field correction.
• ‘a’ — ACPC alignment. Default option is ’n’. Multiple steps can be specified by writing a sequence of options, e.g. ‘nab’, where the steps are performed in the order of the string.
• — decap — --decap <fac> will 'decapitate' volume by setting bottom <fac> percent of slices to 0 and shift the remaining volume down by half the amount removed to center it. Is performed prior to ACPC alignment.
• — bfcFac — Shrink factor for bias field correction. Computes correction on a lower resolution image shrunken by in all directions to reduce computational load and increased speed, at the expense of accuracy. Deafult is 4.

python3 pipeline.py -i ./dicom_data -o ./nifti_output -z
✅ Explanation: Adds .gz compression to the output NIfTI files.n3 pipeline.py -i ./dicom_data -o ./nifti_output --do nab
✅ Explanation: Runs steps in order: NIfTI conversion (n), ACPC alignment (a),
 Bias Field Correction (b).

python3 pipeline.py -i ./dicom_data -o ./nifti_output --bfcFac 2
✅ Explanation: Uses a shrink factor of 2 for faster (but less accurate) bias field correction.

see the above Then a pre and post bias field correction

same — one of us, depending who progresses the faster, will need to try the open dataset so that we can also suggest it.

I wonder if it is already pre-processed though! also a decapitation demonstration, with an unavoidable reference to louis seize (XVI) and marie.-antoinette

✅ Want the Script?

Download it from the github link

[embed]GitHub - Snipersune/mrippy: MRI Preprocessing Tool written in Python. Can be used to perform DICOM… MRI Preprocessing Tool written in Python. Can be used to perform DICOM to nifti conversion, bias field correction and…github.com

💬 Have questions or want to share your own tools/pipeline? Drop a comment below.

We welcome constructive feedback and would be particularly interested in learning whether our article and/or tool helped you!

References and Further Reading

https://medium.com/@alexandro.ramr777/how-to-do-bias-field-correction-with-python-156b9d51dd79

https://younsess-elbrag.medium.com/post-processing-medical-images-n4-bias-correction-and-skull-stripping-572a10b4b3

https://www.itksnap.org/pmwiki/pmwiki.php

https://stackoverflow.com/questions/70971630/get-bias-field-using-sitk

https://simpleitk.readthedocs.io/en/v2.0.1/link_N4BiasFieldCorrection_docs.html

https://github.com/ANTsX/ANTs

https://nipy.org/nibabel/gettingstarted.html

https://medium.com/@daminininad/mri-preprocessing-using-fsl-383a67e7185

https://www.humanbrainmapping.org/i4a/pages/index.cfm?pageid=1

https://andysbrainbook.readthedocs.io/en/latest/fMRI_Short_Course/fMRI_04_Preprocessing.html

https://open.win.ox.ac.uk/pages/fslcourse/website/online_materials.html