bl_app_dbb_preprocessing_t1w

This application performs a basic pre-processing of t1-w images:

1. ACPC alignment
2. Bias Field Correction

Author

Gabriele Amorosino (gamorosino@fbk.eu)

Contributors

Matteo Ballabio (matteoballabio99@gmail.com)
Paolo Avesani (avesani@fbk.eu)

Citation

If you use this code for your research please cite:

Gabriele Amorosino, Denis Peruzzo, Daniela Redaelli, Emanuele Olivetti, Filippo Arrigoni, Paolo Avesani,
DBB - A Distorted Brain Benchmark for Automatic Tissue Segmentation in Paediatric Patients,
NeuroImage, 2022, 119486, ISSN 1053-8119, https://doi.org/10.1016/j.neuroimage.2022.119486.

Running the Brainlife App

You can run the BrainLife App DBB_preprocessing_t1w on the brainlife.io platform via the web user interface (UI) or using the brainlife CLI. With both of these two solutions, the inputs and outputs are stored on the brainlife.io platform, under the specified project, and the computations are performed using the brainlife.io cloud computing resources.

On Brainlife.io via UI

You can see DBB_preprocessing_t1w currently registered on Brainlife. Find the App on brainlife.io and click "Execute" tab and specify dataset e.g. "DBB Distorted Brain Benchmark".

On Brainlife.io using CLI

Brainlife CLI could be installed on UNIX/Linux-based system following the instruction reported in https://brainlife.io/docs/cli/install/.

The first time you use the BrainLife CLI on a machine, you need to log in with the brainlife.io credentials

bl login

You can run the App with CLI as follow:

bl app run --id  60cb69e0cdfdb50220fee1c3 --project <project_id> --input t1:<t1_object_id> \
--input mask:<mask_object_id> --input affine:<affine_object_id>

the output is stored in the reference project specified with the id <project_id>. You can retrieve the object_id using the command bl data query, e.g to get the id of the mask file for the subject 0001 :

bl data query --subject 0001 --datatype neuro/mask --project <projectid>

If not present yet, you can upload a new file in a project using bl data upload. For example, in the case of T1-w file, for the subject 0001 you can run:

bl data upload --project <project_id> --subject 0001 --datatype "neuro/anat/t1w" --t1 <full_path>

Running the code locally

You can run the code on your local machine by git cloning this repository. You can choose to run it with dockers, avoiding to install any software except for singularity. Furthermore, you can run the original script using local software installed.

Run the script using the dockers (recommended)

It is possible to run the app locally, using the dockers that embedded all needed software. This is exactly the same way that apps run code on brainlife.io

Inside the cloned directory, create config.json with something like the following content with the fullpaths to your local input files:

{   
    "t1": "./t1.nii.gz",
    "mask": "./mask.nii.gz",
    "affine": "./affine.txt",
}

Launch the app by executing main.

./main

Script Dependecies

The App needs singularity to run.

Output

The output of bl_app_dbb_preprocessing_t1w is the preprocessed T1-w i.e. rigidly reoriented to template space and bias-field corrected

The file is stored in the working directory, under the folder ./outoputdir and has the same basename of the input T1-w file with the suffix "_reoriented_N4"

n.b. You can find a copy of the same file, stored in the working directory under the folder ./T1_reoriented_N4 with the standard brainlife.io name t1.nii.gz

Run the script (local software)

Clone this repository using git on your local machine to run this script.

Usage

The tool can be used through the T1Wbasicpreproc.sh script.

T1Wbasicpreproc.sh -i <T1.ext> -t <template.ext> [-o <outputdir>] [-a <affine.ext>] [-m <mask.ext>] [-n <num>]

There are two mandatory inputs:
    
	-i, --input         T1-w image to be preprocessed    
	-t, --template      template as reference space to be reoriented (e.g. MNI152)
   
and some optional inputs:

	-o, --outputdir     if not provided, the scripts creates the folder "T1w_preproc" in the same folder 
	                    as the input image
	-a, --affine        fullpath of affine matrix to perform rigid transformation to the template
	-m, --mask          full path of the brain mask to limit Bias-field correction on these voxels     
	-n, --threads       number of threads
	
Example:

T1Wbasicpreproc.sh -i ./t1.nii.gz -t ./data/MNI152_T1_1mm.nii.gz -m ./mask.nii.gz -a ./affine.txt

In the repository is present the folder data/ where is stored a reference template in MNI space (MNI152) at the resolution of 1mm (isotropic).

Output

The output of bl_app_dbb_preprocessing_t1w is the preprocessed T1-w i.e. rigidly reoriented to template space and corrected for bias field

The file is stored in the --outputdir folder and has the same basename of the input T1-w file with the suffix "_reoriented_N4"

Script Dependecies

In order to use the script, the following software must be installed: ANTs, Advanced Normalization Tools (version >= 2.1.0)