disco_subject_to_icbm

Deforms a T1 MRI to the MNI/ICBM template using sulci as deformation landmarks.

Description

Deforms a T1 MRI to the MNI/ICBM template using sulci as deformation landmarks.

This is the simpler main entry point to the DISCO toolbox: it allows to align a brain MRI to the ICBM152 template using non-linear transformations based on individually identified sulci.

BrainVisa pipeline or commandline interface

This pipeline also has a commandline interface:
    disco_subject_to_icbm.py -h
will display the commandline documentation.

The commandline will also handle database creation or update, and multiple subjects processing, which are a bit manual in this pipeline.

Using the pipeline

The deformation fields will be calculated inside the pipeline, which will perform several steps:

T1 MRI segmentation, sulci extraction and identification (Morphologist pipeline)

DISCO/DARTEL pipeline to register the given MRI and the MNI/ICBM template

application of the deformation field of the main data (MRI corrected for inhomogeneities, meshes, sulcal graph...) to the ICBM space

Update of a transformations graph that can be reused later to deform data from any subject to any other one.

The process may be iterated to process several MRIs (subjects), but only after proper setup, please see Iterations and template setup.

Output data will be managed in a "brainvisa database", a data directory which should be created beforehand (or an existing one can be reused). See Output dtabase. There will be many output files for a single subject (segmentations steps, meshes, sulci graphs, DISCO and DARTEL deformation fields toward an intermediate space, resampled data etc. All these data are not exposed by the main parameters, they will follow the BrainVISA data organization model.

The ICBM template is normally provided in an internal dataset of the software distribution. For technical reasons some of its data will be copied in the output database once (when the first subject is processed).

The main final outputs will probably be the deformation fields from the subject to the ICBM template space, and perhaps the resampled data. The deformation fields can be managed through a "transformations graph", a .yaml file which will be found in:

{output_database_dir}/analyzes/DISCO_analyzes/disco_transform_graph.yaml

This file will contain transformation information for all subjects and is modified incrementally when new subjects are processed. It is a yaml (text, readable) file which will indicate where the individual deformation fields files are located relatively to itself.

Deformation fields will follow a pattern of this shape:
{output_database_dir}/analyzes/DISCO_analyzes/DISCO_{subject}_icbm/deformed_output/mni_icbm152_nlin_asym_09c-default_acquisition-default_analysis-folds-3.1/default_session_auto/final_displacement_field/displ_field_DISCO_DARTEL_template_from_{subject}_TO_mni_icbm152_nlin_asym_09c.ima
{output_database_dir}/analyzes/DISCO_analyzes/DISCO_{subject}_icbm/deformed_output/mni_icbm152_nlin_asym_09c-default_acquisition-default_analysis-folds-3.1/default_session_auto/final_displacement_field/displ_field_DISCO_DARTEL_template_from_{subject}_TO_mni_icbm152_nlin_asym_09c.ima
Resampled data can be found in:
{output_database_dir}/analyzes/DISCO_analyzes/DISCO_{subject}_icbm/deformed_output/mni_icbm152_nlin_asym_09c-default_acquisition-disco_analysis-folds-3.1/default_session_2_manual/{type_dir}/*_from_{subject}_default_acquisition_disco_analysis_invDARTEL_template_invDISCO_TO_mni_icbm152_nlin_asym_09c.*
with {type_dir} being "mesh" or "segmentation".

Additional data files can be resampled later, using the processed deformation fields and transformations graph, using the command:
disco_apply_transform_to_icbm.py
See it for details, using the -h option for help.

Execution time

Expect about 1h-1h30 execution time for one subject. Several steps need a substantial amount of processing: Morphologist takes about 15 min, then the long steps are Disco Grid Deformation (maybe 15-20 min), and Dartel template creation (maybe 30-40 min).

As most of the processing is single-threaded, it is efficient to run several subjects in parallel on a multi-core system, as long as the system memory is sufficient.

Output database

The output database cannot actually be created within the pipeline, for technical reasons (the database should exist before database parameters can be propagated in the parameters completion system). Thus the "Create database" and "Update database" should not be activated in the pipeline, or must be the only steps enabled. These steps are here as a hint to show how to create a new database.

Warning

In BrainVisa 6.0 / Disco 6.0, the output database should follow the "brainvisa 3.2.0" ontology, the Bids ontologies are not supported yet.

Iterations and template

Some steps can be optionally run or disabled, and some should be done just once, and not done again when running additional subjects or iterating over several subjects. As you have seen the database creation must be done separately beforehand.

Moreover, the template data are copied into the output database. This should be done once, thus the step "00. Copy DISCO/DARTEL inputs in a compatible format" should be unchecked in an iteration, or when running additional subjects.

Thus, to run an iteration in a new database, do the following beforehand:

Create an output database by running Create database.

Update it using the process Update databases.

Copy the template data using the process 00. Copy DISCO/DARTEL inputs in a compatible format.

Select as the Lgraph parameter, in the database "disco_templates_hbp_morpho" the left ICBM152 sulcal graph with manually corrected labels (manually_labelled: Yes, session: default_session_2).

Select as the target_database the output database created above.

Then you should uncheck the "create database", "Update databases", and "00. Copy DISCO/DARTEL inputs in a compatible format" steps, and iterate the pipeline. Moreover the allow_multithreading parameter in the main pipeline should better be disabled.

What if I have already run Morphologist

Then just un-check the "morphologist_branch" branch.

Parameters

t1mri: Raw T1 MRI ( input )
Input raw T12 MRI. The image will be imported into the output database, thus may be selected anywhere on the disk using the file selection button.

output_database: Directory ( output )
An existing BrainVisa database, following the ontology brainvisa-3.2.0

templates_database: Choice ( input )
The template database contains the MNI ICBM152 template image and its segmentation and sulci. Normally it is found automatically, you just have to leave it unchanged.

center: String ( optional, input )
output center attribute for image importation. If left blank the default "subjects" will be used.

session: String ( optional, input )
output session attribute for image importation. If left blank the default will be used.

subject: String ( optional, input )
output subject attribute for image importation. If left blank the default will be used (the T1 MRI filename).

sulci_to_be_studied: Sulci To Be Studied DISCO ( input )
List of sulci which will be used as sulcal constraints duriung the registration. In most cases, leave the default value, as playing with these may be a bit tricky.

allow_multithreading: Boolean ( input )
Multithreading may be used internallly in a few steps of the pipelines. If run in parallel this option should rahter be disabled in order to fully control the number of processing cores actually used.

Technical information

Toolbox : Disco

User level : 0

Identifier : disco_subject_to_icbm

File name : brainvisa/toolboxes/disco/processes/disco_subject_to_icbm.py

Supported file formats :
t1mri :
gz compressed NIFTI-1 image, Aperio svs, DICOM image, Directory, ECAT i image, ECAT v image, FDF image, FreesurferMGH, FreesurferMGZ, GIS image, Hamamatsu ndpi, Hamamatsu vms, Hamamatsu vmu, JPEG image, Leica scn, MINC image, NIFTI-1 image, SPM image, Sakura svslide, TIFF image, TIFF image, TIFF(.tif) image, TIFF(.tif) image, Ventana bif, Zeiss czi, gz compressed MINC image, gz compressed NIFTI-1 image
output_database :
Directory, Directory
sulci_to_be_studied :
Text file, Text file