This toolbox contains the magic disco registration technique, waow!
DISCO is a method for cross-subject brain alignment. The distinguishing feature of DISCO is that is uses the cortical sulci as landmarks (using white matter fibre bundles as constraints is available as an experimental feature). DISCO is a template building method: from the N subjects in an experiment (N ≥ 2) are registered toward a group template, which is constructed iteratively as the average sulcal anatomy of the input subjects. There are options to register the data toward an external template (e.g. one of the MNI templates).
The original algorithm is fully described in the following papers. Please cite these papers if you use this toolbox:
This section is a practical a guide to setting up your first DISCO Study. It is strongly recommended that you read this section fully before looking for documentation elsewhere in the toolbox.
You need to configure BrainVISA to use MATLAB (for DISCO) and SPM (for DARTEL) before you can use the toolbox. The core of the algorithm is computed with MATLAB and is tested with MATLAB version R2014a. More recent versions should work (R2019a has been tested), although they are known to give very minor differences in the results. Of course, you will need a valid MATLAB licence in order to compute registrations with the toolbox. If you do not have one, you should still be able to use the toolbox for using the results of an existing DISCO experiment.
In NeuroSpin, these are the recommended settings that should be entered in the BrainVISA Preferences (BrainVISA / Preferences menu):
After having set these values, hit BrainVISA / Reload Toolboxes (or restart BrainVISA).
Link the licence file inside of the container (which uses its own home directory).
$ bv bash
(brainvisa-cea-5.0.0)yl243478@is234203:~$ mkdir -p ~/.matlab
(brainvisa-cea-5.0.0)yl243478@is234203:~$ ln -s /home/yl243478/.matlab/R2014a_licenses/ ~/.matlab/
(brainvisa-cea-5.0.0)yl243478@is234203:~$ ls ~/.matlab/R2014a_licenses
license_*_*_R2014a.lic
(brainvisa-cea-5.0.0)yl243478@is234203:~$ exit
exitPrepare a set of subjects where the Morphologist pipeline has been run entirely (including the sulci recognition step).
For testing, you can use the T1-weighted images of the three subjects found in https://brainvisa.info/download/data/demo_data.zip (sujet01, sujet02, and sujet03).
Import the raw T1 MRIs and run the Morphologist 2021 pipeline (see Morphologist for details).
As for much of BrainVISA, DISCO uses a database (be careful, some steps work with absolute paths so you cannot easily move the database). Databases can be created in the BrainVISA Preferences.
You are advised to always use 00. Copy DISCO/DARTEL inputs in a compatible format (found under Preprocessing) for copying the input data in the database where you will run your Disco studies. This has two purposes:
Use the Check database process, which will find and resolve inconsistencies in the metadata of input files. It can be found in the Data Management toolbox. In particular, it will fix incorrect referentials, which are a common cause of misaligned data in Anatomist.
If sulci have been labelled manually, you should check the sulci graphs for side errors (sulci of the right hemisphere labelled with a left label, or vice versa). Use the Clean database - side error process that is found under Morphologist / Sulci / Recognition.
Under Database_exploration, use QC table of DISCO and DARTEL inputs. Choose your database and leave all other parameters to their default values.
Warning: this process will not complain if the Raw T1 MRI is in an unsupported format such as uncompressed NIfTI.
Across the Disco toolbox, a specific run of DISCO is named a Study. Each Study is contained in a directory named analyzes/DISCO_analyzes/DISCO_<Study> in a BrainVISA database.
Similarly, a specific run of DARTEL is named a Template. Each Template is contained in a directory named analyzes/DISCO_analyzes/DISCO_<Study>/DARTEL_<Template>: it is always nested in a DISCO Study.
The process Create a new DISCO Study from existing parameters (found under Preprocessing) is used to create a new Study, using the parameters of an older Study as a starting point.
If you do not have a Study to start from, you can use the numbered processes under Preprocessing to create and parametrize a new Study.
Run 01. Sulci Label Translation to create the Study directory and create some required files therein.
The sulci_label_translation file is used to assign a numeric labels to each sulcus (Morphologist uses text labels to identify sulci, but the core DISCO algorithms need to represent them as label images).
The sulci_label_translation file created by this process contains numeric labels for all common sulci, so you should not need to edit it, unless you are using exotic sulci.
Run either 02a. Sulci To Be Removed, or 02b. Sulci To Be Added, to initialize the list of sulci that will be used to drive the registration. These processes take opposite approaches:
02a. Sulci To Be Removed will use all sulci defined in the sulci_label_translation file, except for an exclusion list. The default exclusion list is quite short so the study will use many sulci (41 sulci as of BrainVISA 5.0.0), including smaller sulci that may be quite variable and may not be recognized consistently by automatic labelling methods.
02b. Sulci To Be Added will use only the sulci that are explicitly listed. The default list should be a conservative set of large, stable sulci (13 sulci as of BrainVISA 5.0.0). However, please do not trust the default and check which sulci make sense for your study. Beware that this list should be used as-is, some sulci of the default list are meant to be merged (next point).
The resulting list of sulci is stored in the sulci_to_be_studied.txt file, which will be edited in-place by subsequent steps.
Use 03. Sulci Merging to merge sets of sulci: the merged sulcus will serve as a single registration landmark. This is useful for subdivided sulci where the subdivision borders are not reliable across subjects (e.g. the precentral sulcus).
Use 04. Sulci Not to Be Pruned to disable pruning for specific sulci. Pruning is performed by default: only the longest continuous path contained in the sulcus is considered, and small branches are excluded. If you want to retain the shape of branches, diable pruning with this process.
05. Sulci Weight can be used to change the weight of sulci in the landmark-driven registration. Using this option is discouraged: it is mostly untested, you should look deep in the DISCO algorithm to understand exactly what it does.
Here are a few lists of sulci that have been used in past DISCO studies. You may use them as a starting point. The choice of sulcal constraints should be adapted to your population: in general, you can use more constraints in less diverse populations, and conversely, you must restrict the list to very stable sulci when dealing with heterogeneous populations.
sulci_to_be_studied_20160308_MultiDatabase.txt: a list of 11 sulcal constraints (encompassing 13 elementary sulci) used for registering human subjects in a wide age range, from preterm newborns to 85 years of age. See Lebenberg, J. et al. A framework based on sulcal constraints to align preterm, infant and adult human brain images acquired in vivo and post mortem. Brain Struct Funct 223, 4153–4168 (2018). DOI: 10.1007/s00429-018-1735-9
sulci_to_be_studied_Adults_MultiDatabase_Exp_20170921.txt: a list of 30 sulcal constraints (encompassing 41 elementary sulci) used for registering 88 adult subjects (subjects of the ARCHI database and 3 template brains: MNI ICBM152 nlin asym 2009c, MNI Colin27, and BigBrain 2015 release).
sulci_to_be_studied_20181004_sigV30.txt: a list of 22 sulcal constraints (encompassing 31 elementary sulci) used for registering 4 template human brains in the frame of the HBP, see DOI: 10.25493/GA3Y-9V8.
sulci_to_be_studied_Chimps_20191127.txt: a list of 22 sulcal constraints (encompassing 25 elementary sulci) used for registering chimpanzee brains. It contains sulci that are not present in the human nomenclature (S.F.sup.post., S.Lu., S.O.t.), as a result, it must be used along with two other files to enable these sulci: sulci_label_translation_siGraph_Chimps_20191127.txt, and sulci_model_chimp_2019.trl.
The easiest way of running a complete DISCO+DARTEL study is to use the Disco and Dartel complete pipeline, found directly under the Disco toolbox.
Please look at the documentation of Disco and Dartel complete pipeline for the detailed instructions.
You can visualize the sulcal imprints that are extracted from the sulci graphs to be fed into DISCO: Use the process Tools / View Sulcal Imprint Mesh (or Tools / View list of Sulcal Imprint Meshes to visualize multiple imprints simultaneously).
This visualization allows you to verify:
Known issue: if the imprints appear all black (e.g. when using software rendering for OpenGL), open Settings / Anatomist Preferences, go to the OpenGL tab and uncheck Enable OpenGL shaders.
The Disco and Dartel complete pipeline calculates an average cortical ribbon as the last step of the pipeline. This image allows you to assess the quality of registration of the cortical ribbon, and the residual variability after DISCO+DARTEL alignment. This image is calculated in the average common space after DISCO+DARTEL, each voxel contains a value between 0 and 1 representing the proportion of images where the given voxel is contained in the cortical ribbon.
There are different ways of visualizing the deformation fields. You can choose among these viewers by right-clicking the label of the deformation field in a process, and using the Viewer sub-menu. Then, you can open the viewer by left-clicking the eye (right-click the eye to see the full set of viewer parameters). Alternatively, you can find these viewers under the Tools section.
Let's go now and enjoy your registration experience!