Disco toolbox

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:

You should also cite this paper if you use DARTEL:

DISCO walkthrough

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.

MATLAB/SPM configuration

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).

If you have a personal MATLAB licence

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
(brainvisa-cea-5.0.0)yl243478@is234203:~$ exit

Input data

Run Morphologist

Prepare a set of subjects where the Morphologist pipeline has been run entirely (including the sulci recognition step).

Prepare a database for the DISCO Study

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:

Checking the input data

Checking the metadata

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.

Checking the sulcal labels

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.

Checking that all required input files exist

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.

General concepts: Study and Template

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.

Preparing the DISCO Study

Creating a Study by copying another 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.

Creating a Study from scratch

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.

  1. 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.

  2. 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:

    The resulting list of sulci is stored in the sulci_to_be_studied.txt file, which will be edited in-place by subsequent steps.

  3. 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).

  4. 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.

  5. 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.

Example sulci lists

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.

Run the DISCO study

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.

Tools for exploring a DISCO/DARTEL study

High-level overview of a Study

Refer to the documentation of the Database_exploration category.

Checking results

Sulcal imprints

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.

Average cortical ribbon

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.

Deformation fields

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.

Using the resulting deformation fields

Refer to the documentation of the Deformation category.

Let's go now and enjoy your registration experience!