Graphical User Interface

Introduction

Connectome Mapper 3 comes with a Graphical User Interface, the Connectome Mapper BIDS App manager, designed to facilitate the configuration of all pipeline stages, the configuration of the BIDS App run and its execution, and the inspection of the different stage outputs with appropriate viewers.

_images/mainWindow.png

Main window of the Connectome Mapper BIDS App Manager

Start the Graphical User Interface

In a terminal, enter to following:

$ source activate py37cmp-gui

or:

$ conda activate py37cmp-gui

Please see Section Installation for more details about installation.

After activation of the conda environment, start the graphical user interface called Connectome Mapper 3 BIDS App Manager

$ cmpbidsappmanager

Load a BIDS dataset

The Connectome Mapper 3 BIDS App Manager allows you to:

  • load a BIDS dataset stored locally.

You only have to select the root directory of your valid BIDS dataset (see note below)

  • create a new datalad/BIDS dataset locally from an existing local or remote datalad/BIDS dataset (This is a feature under development)

Select the mode “Install a Datalad/BIDS dataset”.

If ssh connection is used, make sure to enable the “install via ssh” and to provide all connection details (IP address / Remote host name, remote user, remote password)

Note

The input dataset MUST be a valid BIDS structured dataset and must include at least one T1w or MPRAGE structural image. We highly recommend that you validate your dataset with the free, online BIDS Validator.

Pipeline stage configuration

Start the Configurator Window

  • From the main window, click on the left button to start the Configurator Window.

_images/mainWindow_configurator.png
  • The window of the Connectome Mapper BIDS App Configurator will appear, which will assist you note only in configuring the pipeline stages (each pipeline has a tab panel), but also in creating appropriate configuration files which could be used outside the Graphical User Interface.

_images/configurator_window.png

Configurator Window of the Connectome Mapper

The outputs depend on the chosen parameters.

Anatomical pipeline stages

_images/configurator_pipeline_anat.png

Panel for configuration of anatomical pipeline stages

Segmentation

Performs tissue segmentation using Freesurfer.

Freesurfer

_images/segmentation_fs.png
  • Number of threads: used to specify how many threads are used for parallelization

  • Brain extraction tools: alternative brain extraction methods injected in Freesurfer

  • Freesurfer args: used to specify extra Freesurfer processing options

Note

If you have already Freesurfer v5 / v6 output data available, CMP3 can use them if there are placed in your output / derivatives directory. Note however that since v3.0.0, CMP3 expects to find a freesurfer-6.0.1, so make sure that your derivatives are organized as follows:

your_bids_dataset

|______ derivatives/ | |______ freesurfer-6.0.1/ | |______ sub-01[_ses-01]/ | | |______ label/ | | |______ mri/ | | |______ surf/ | | |______ … | |______ … |______ sub-01/ |______ …

Parcellation

Generates the Native Freesurfer or Lausanne2008/Lausanne2018 parcellation from Freesurfer data.

Parcellation scheme

  • NativeFreesurfer:

    _images/parcellation_fs.png

    Atlas composed of 83 regions from the Freesurfer aparc+aseg file

  • Lausanne2018:

    _images/parcellation_lausanne2018.png

    New version of Lausanne parcellation atlas, corrected, and extended with 7 thalamic nuclei, 12 hippocampal subfields, and 4 brainstem sub-structure per hemisphere

    Since v3.0.0, Lausanne2018 parcellation has completely replaced the old Lausanne2008 parcellation.

    As it provides improvements in the way Lausanne parcellation label are generated, any code and data related to Lausanne2008 has been removed. If you still wish to use this old parcellation scheme, please use v3.0.0-RC4 which is the last version that supports it.

Diffusion pipeline stages

_images/configurator_pipeline_dwi.png

Panel for configuration of diffusion pipeline stages

Preprocessing

Preprocessing includes denoising, bias field correction, motion and eddy current correction for diffusion data.

_images/preprocessing.png

Denoising

Remove noise from diffusion images using (1) MRtrix3 MP-PCA method or (2) Dipy Non-Local Mean (NLM) denoising with Gaussian or Rician noise models

Bias field correction

Remove intensity inhomogeneities due to the magnetic resonance bias field using (1) MRtrix3 N4 bias field correction or (2) the bias field correction provided by FSL FAST

Motion correction

Aligns diffusion volumes to the b0 volume using FSL’s MCFLIRT

Eddy current correction

Corrects for eddy current distortions using FSL’s Eddy correct tool

Resampling

Resample morphological and diffusion data to F0 x F1 x F2 mm^3

Registration

Registration mode

  • FSL (Linear):

    _images/registration_flirt.png

    Perform linear registration from T1 to diffusion b0 using FSL’s flirt

  • Non-linear (ANTS):

    _images/registration_ants.png

    Perform symmetric diffeomorphic SyN registration from T1 to diffusion b=0

Diffusion reconstruction and tractography

Perform diffusion reconstruction and local deterministic or probabilistic tractography based on several tools. ROI dilation is required to map brain connections when the tracking only operates in the white matter.

_images/diffusion_config_window.png

Diffusion stage configuration window

Reconstruction tool

Dipy: perform SHORE, tensor, CSD and MAP-MRI reconstruction

  • SHORE:

    _images/diffusion_dipy_shore.png

    SHORE performed only on DSI data

  • Tensor:

    _images/diffusion_dipy_tensor.png

    Tensor performed only on DTI data

  • CSD:

    _images/diffusion_dipy_csd.png

    CSD performed on DTI and multi-shell data

  • MAP_MRI:

    _images/diffusion_dipy_mapmri.png

    MAP-MRI performed only on multi-shell data

MRtrix: perform CSD reconstruction.

  • CSD:

    _images/diffusion_mrtrix_csd.png

    CSD performed on DTI and multi-shell data

Tractography tool

Dipy: perform deterministic and probabilistic fiber tracking as well as particle filtering tractography.

  • Deterministic tractography:

    _images/diffusion_dipy_deterministic.png

    Deterministic tractography (SD_STREAM) performed on single tensor or CSD reconstruction

  • Probabilistic tractography:

    _images/diffusion_dipy_probabilistic.png

    Probabilistic tractography (iFOD2) performed on SHORE or CSD reconstruction

  • Probabilistic particle filtering tractography (PFT):

    _images/diffusion_dipy_probabilistic_PFT.png

    Probabilistic PFT tracking performed on SHORE or CSD reconstruction. Seeding from the gray matter / white matter interface is possible.

Note

We noticed a shift of the center of tractograms obtained by dipy. As a result, tractograms visualized in TrackVis are not commonly centered despite the fact that the tractogram and the ROIs are properly aligned.

MRtrix: perform deterministic and probabilistic fiber tracking as well as anatomically-constrained tractography. ROI dilation is required to map brain connections when the tracking only operates in the white matter.

  • Deterministic tractography:

    _images/diffusion_mrtrix_deterministic.png

    Deterministic tractography (SD_STREAM) performed on single tensor or CSD reconstruction

  • Deterministic anatomically-constrained tractography (ACT):

    _images/diffusion_mrtrix_deterministic_ACT.png

    Deterministic ACT tracking performed on single tensor or CSD reconstruction. Seeding from the gray matter / white matter interface is possible. Backtrack option is not available in deterministic tracking.

  • Probabilistic tractography:

    _images/diffusion_mrtrix_probabilistic.png

    Probabilistic tractography (iFOD2) performed on SHORE or CSD reconstruction

  • Probabilistic anatomically-constrained tractography (ACT):

    _images/diffusion_mrtrix_probabilistic_ACT.png

    Probabilistic ACT tracking performed on SHORE or CSD reconstruction. Seeding from the gray matter / white matter interface is possible.

Connectome

Compute fiber length connectivity matrices. If DTI data is processed, FA additional map is computed. In case of DSI, additional maps include GFA and RTOP. In case of MAP-MRI, additional maps are RTPP, RTOP, …

_images/connectome.png

Output types

Select in which formats the connectivity matrices should be saved.

FMRI pipeline stages

_images/configurator_pipeline_fmri.png

Panel for configuration of fMRI pipeline stages

Preprocessing

Preprocessing refers to processing steps prior to registration. It includes discarding volumes, despiking, slice timing correction and motion correction for fMRI (BOLD) data.

_images/preprocessing_fmri.png

Discard n volummes

Discard n volumes from further analysis

Despiking

Perform despiking of the BOLD signal using AFNI.

Slice timing and Repetition time

Perform slice timing correction using FSL’s slicetimer.

Motion correction

Align BOLD volumes to the mean BOLD volume using FSL’s MCFLIRT.

Registration

Registration mode

  • FSL (Linear):

    _images/registration_flirt_fmri.png

    Perform linear registration from T1 to mean BOLD using FSL’s flirt.

  • BBregister (FS)

    _images/registration_fs_fmri.png

    Perform linear registration using Freesurfer BBregister tool from T1 to mean BOLD via T2.

    Warning

    development in progress

fMRI processing

Performs detrending, nuisance regression, bandpass filteringdiffusion reconstruction and local deterministic or probabilistic tractography based on several tools. ROI dilation is required to map brain connections when the tracking only operates in the white matter.

Detrending

_images/detrending.png

Detrending of BOLD signal using:

  1. linear trend removal algorithm provided by the scipy library

  2. quadratic trend removal algorithm provided by the obspy library

Nuisance regression

_images/nuisance.png

A number of options for removing nuisance signals is provided. They consist of:

  1. Global signal regression

  2. CSF regression

  3. WM regression

  4. Motion parameters regression

Bandpass filtering

_images/bandpass.png

Perform bandpass filtering of the time-series using FSL’s slicetimer

Connectome

Computes ROI-averaged time-series and the correlation connectivity matrices.

_images/connectome_fmri.png

Output types

Select in which formats the connectivity matrices should be saved.

Save the configuration files

You can save the pipeline stage configuration files in two different way:

  1. You can save all configuration files at once by clicking on the Save All Pipeline Configuration Files. This will save automatically the configuration file of the anatomical / diffusion / fMRI pipeline to <bids_dataset>/code/ref_anatomical_config.ini / <bids_dataset>/code/ref_diffusion_config.ini / <bids_dataset>/code/ref_fMRI_config.ini respectively.

  2. You can save individually each of the pipeline configuration files and edit its filename in the File menu (File -> Save anatomical/diffusion/fMRI configuration file as…)

Nipype

Connectome Mapper relies on Nipype. All intermediate steps for the processing are saved in the corresponding <bids_dataset/derivatives>/nipype/sub-<participant_label>/<pipeline_name>/<stage_name> stage folder (See Nipype workflow outputs for more details).

Run the BIDS App

Start the Connectome Mapper BIDS App GUI

  • From the main window, click on the middle button to start the Connectome Mapper BIDS App GUI.

_images/mainWindow_bidsapp.png
  • The window of the Connectome Mapper BIDS App GUI will appear, which will help you in setting up and launching the BIDS App run.

_images/bidsapp_window.png

Window of the Connectome Mapper BIDS App GUI

Run configuration

  • Select the output directory for data derivatives

    _images/bidsapp_select_output.png
  • Select the subject labels to be processed

    _images/bidsapp_select_subject.png
  • Tune the number of subjects to be processed in parallel

    _images/bidsapp_subject_parallelization.png
  • Tune the advanced execution settings for each subject process. This include finer control on the number of threads used by each process as well as on the seed value of ANTs and MRtrix random number generators.

    _images/bidsapp_execution_settings.png

    Important

    Make sure the number of threads multiplied by the number of subjects being processed in parallel do not exceed the number of CPUs available on your system.

  • Check/Uncheck the pipelines to be performed

    _images/bidsapp_pipeline_check.png

    Note

    The list of pipelines might vary as it is automatically updated based on the availability of diffusion MRI and resting-state fMRI data.

  • Specify your Freesurfer license

    _images/bidsapp_fslicense.png

    Note

    Your Freesurfer license will be copied to your dataset directory as <bids_dataset>/code/license.txt which will be mounted inside the BIDS App container image.

  • When the run is set up, you can click on the Check settings button.

    _images/bidsapp_checksettings.png
  • If the setup is complete and valid, this will enable the Run BIDS App button.

    _images/bidsapp_checksettings2.png

You are ready to launch the BIDS App run!

Execute the BIDS App

  • Click on the Run BIDS App button to execute the BIDS App

    _images/bidsapp_run.png
  • You can see the complete docker run command generated by the Connectome Mapper BIDS App GUI from the terminal output such as in this example

    Start BIDS App
    > FreeSurfer license copy skipped as it already exists (BIDS App Manager)
    > Datalad available: True
    ... BIDS App execution command: ['docker', 'run', '-it', '--rm', '-v', '/home/localadmin/Desktop/hcp-retest-d2:/bids_dir', '-v', '/home/localadmin/Desktop/hcp-retest-d2/derivatives:/output_dir', '-v', '/usr/local/freesurfer/license.txt:/bids_dir/code/license.txt', '-v', '/home/localadmin/Desktop/hcp-retest-d2/code/ref_anatomical_config.ini:/code/ref_anatomical_config.ini', '-v', '/home/localadmin/Desktop/hcp-retest-d2/code/ref_diffusion_config.ini:/code/ref_diffusion_config.ini', '-v', '/home/localadmin/Desktop/hcp-retest-d2/code/ref_fMRI_config.ini:/code/ref_fMRI_config.ini', '-u', '1000:1000', 'sebastientourbier/connectomemapper-bidsapp:v3.0.0-RC3', '/bids_dir', '/output_dir', 'participant', '--participant_label', '103818', '--anat_pipeline_config', '/code/ref_anatomical_config.ini', '--dwi_pipeline_config', '/code/ref_diffusion_config.ini', '--func_pipeline_config', '/code/ref_fMRI_config.ini', '--fs_license', '/bids_dir/code/license.txt', '--number_of_participants_processed_in_parallel', '1', '--number_of_threads', '10', '--ants_number_of_threads', '10']
    > BIDS dataset: /bids_dir
    > Subjects to analyze : ['103818']
    > Set $FS_LICENSE which points to FreeSurfer license location (BIDS App)
      ... $FS_LICENSE : /bids_dir/code/license.txt
      * Number of subjects to be processed in parallel set to 1 (Total of cores available: 11)
      * Number of parallel threads set to 10 (total of cores: 11)
      * OMP_NUM_THREADS set to 10 (total of cores: 11)
      * ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS set to 10
    Report execution to Google Analytics.
    Thanks to support us in the task of finding new funds for CMP3 development!
    > Sessions to analyze : ['ses-01']
    > Process subject sub-103818 session ses-01
    WARNING: rewriting config file /output_dir/cmp/sub-103818/ses-01/sub-103818_ses-01_anatomical_config.ini
    ... Anatomical config created : /output_dir/cmp/sub-103818/ses-01/sub-103818_ses-01_anatomical_config.ini
    WARNING: rewriting config file /output_dir/cmp/sub-103818/ses-01/sub-103818_ses-01_diffusion_config.ini
    ... Diffusion config created : /output_dir/cmp/sub-103818/ses-01/sub-103818_ses-01_diffusion_config.ini
    WARNING: rewriting config file /output_dir/cmp/sub-103818/ses-01/sub-103818_ses-01_fMRI_config.ini
    ... fMRI config created : /output_dir/cmp/sub-103818/ses-01/sub-103818_ses-01_fMRI_config.ini
    ... Running pipelines :
            - Anatomical MRI (segmentation and parcellation)
            - Diffusion MRI (structural connectivity matrices)
            - fMRI (functional connectivity matrices)
    ... cmd : connectomemapper3 --bids_dir /bids_dir --output_dir /output_dir --participant_label sub-103818 --session_label ses-01 --anat_pipeline_config /output_dir/cmp/sub-103818/ses-01/sub-103818_ses-01_anatomical_config.ini --dwi_pipeline_config /output_dir/cmp/sub-103818/ses-01/sub-103818_ses-01_diffusion_config.ini --func_pipeline_config /output_dir/cmp/sub-103818/ses-01/sub-103818_ses-01_fMRI_config.ini --number_of_threads 10
    

    Note

    Also, this can be helpful in you wish to design your own batch scripts to call the BIDS App with the correct syntax.

Check progress

For each subject, the execution output of the pipelines are redirected to a log file, written as <bids_dataset/derivatives>/cmp/sub-<subject_label>_log.txt. Execution progress can be checked by the means of these log files.

Check stages outputs

Start the Inspector Window

  • From the main window, click on the right button to start the Inspector Window.

_images/mainWindow_outputs.png
  • The Connectome Mapper 3 Inspector Window will appear, which will assist you in inspecting outputs of the different pipeline stages (each pipeline has a tab panel).

Anatomical pipeline stages

  • Click on the stage you wish to check the output(s):

    _images/outputcheck_pipeline_anat.png

    Panel for configuration of anatomical pipeline stages

Segmentation

  • Select the desired output from the list and click on view:

    _images/outputcheck_stage_seg.png

Segmentation results

Surfaces extracted using Freesurfer.

_images/ex_segmentation1.png

T1 segmented using Freesurfer.

_images/ex_segmentation2.png

Parcellation

  • Select the desired output from the list and click on view:

    _images/outputcheck_stage_parc.png

Parcellation results

Cortical and subcortical parcellation are shown with Freeview.

_images/ex_parcellation2.png

Diffusion pipeline stages

  • Click on the stage you wish to check the output(s):

    _images/outputcheck_pipeline_dwi.png

    Panel for configuration of diffusion pipeline stages

Preprocessing

  • Select the desired output from the list and click on view:

    _images/outputcheck_stage_prep.png

Registration

  • Select the desired output from the list and click on view:

    _images/outputcheck_stage_reg.png

Registration results

Registration of T1 to Diffusion space (b0). T1 in copper overlayed to the b0 image.

_images/ex_registration.png

Diffusion reconstruction and tractography

  • Select the desired output from the list and click on view:

    _images/outputcheck_stage_dwi.png

Tractography results

DSI Tractography results are displayed with TrackVis.

_images/ex_tractography1.png _images/ex_tractography2.png

Connectome

  • Select the desired output from the list and click on view:

    _images/outputcheck_stage_conn.png

Generated connection matrix

Displayed using a:

  1. matrix layout with pyplot

_images/ex_connectionmatrix.png
  1. circular layout with pyplot and MNE

_images/ex_connectioncircular.png

FMRI pipeline stages

  • Click on the stage you wish to check the output(s):

    _images/outputcheck_pipeline_fmri.png

    Panel for configuration of fMRI pipeline stages

Preprocessing

  • Select the desired output from the list and click on view:

    _images/outputcheck_stage_prep_fmri.png

Registration

  • Select the desired output from the list and click on view:

    _images/outputcheck_stage_reg_fmri.png

fMRI processing

  • Select the desired output from the list and click on view:

    _images/outputcheck_stage_func.png

ROI averaged time-series

_images/ex_rsfMRI.png

Connectome

  • Select the desired output from the list and click on view:

    _images/outputcheck_stage_conn_fmri.png

Generated connection matrix

Displayed using a:

  1. matrix layout with pyplot

_images/ex_connectionmatrix_fmri.png
  1. circular layout with pyplot and MNE

_images/ex_connectioncircular_fmri.png