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.
Start the Graphical User Interface
In a terminal, enter to following:
$ source activate py39cmp-gui
or:
$ conda activate py39cmp-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
Note
The main window would be blank until you select the BIDS dataset.
Load a BIDS dataset
Click on
File -> Load BIDS dataset...
in the menu bar of the main window. Note that on Mac, Qt turns this menu bar into the native menu bar (top of the screen).The
Connectome Mapper 3
BIDS App Manager gives you two different options:Load BIDS dataset
: load a BIDS dataset stored locally. You only have to select the root directory of your valid BIDS dataset (see note below)Install Datalad BIDS dataset
: create a new datalad/BIDS dataset locally from an existing local or remote datalad/BIDS dataset (This is a feature under development) 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.
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.
The outputs depend on the chosen parameters.
Anatomical pipeline stages
Segmentation
Prior to Lausanne parcellation, CMP3 relies on Freesurfer for the segmentation of the different brain tissues and the reconstruction of the cortical surfaces. If you plan to use a custom parcellation, you will be required here to specify the pattern of the different existing segmentation files that follows BIDS derivatives (See Custom segmentation).
Freesurfer
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 / v7 output data available, CMP3 can use them if there are placed in your output / derivatives directory. Note however that since
v3.0.3
, CMP3 expects to find afreesurfer-7.1.1
, so make sure that your derivatives are organized as follows:your_bids_dataset derivatives/ freesurfer-7.1.1/ sub-01[_ses-01]/ label/ mri/ surf/ ... ... sub-01/ ...
Custom segmentation
You can use any parcellation scheme of your choice as long as you provide a list of segmentation files organized following the BIDS derivatives specifications for segmentation files, provide appropriate
.tsv
sidecar files that describes the index/label/color mapping of the parcellation, and adopt theatlas-<label>
entity to encode the name of the atlas, i.e:<derivatives_directory>/ sub-<participant_label>/ anat/ <source_entities>_desc-brain_mask.nii.gz <source_entities>_label-GM[_desc-<label>]_dseg.nii.gz <source_entities>_label-WM[_desc-<label>]_dseg.nii.gz <source_entities>_label-CSF[_desc-<label>]_dseg.nii.gz <source_entities>_desc-aparcaseg_dseg.nii.gzThe
desc
BIDS entity can be used to target specific mask and segmentation files.For instance, the configuration above would allows us to re-use the outputs of the anatomical pipeline obtained with the previous
v3.0.2
version of CMP3:your_bids_dataset derivatives/ cmp-v3.0.2/ sub-01/ anat/ sub-01_desc-brain_mask.nii.gz sub-01_label-GM_dseg.nii.gz sub-01_label-WM_dseg.nii.gz sub-01_label-CSF_dseg.nii.gz sub-01_desc-aparcaseg_dseg.nii.gz ... ... sub-01/ ...Important
If you plan to use either Anatomically Constrained or Particle Filtering tractography, you will still require to have Freesurfer 7 output data available in your output / derivatives directory, as described the above note in *Freesurfer*.
Parcellation
Generates the Native Freesurfer or Lausanne2018 parcellation from Freesurfer data. Alternatively, since v3.0.3
you can use your own custom parcellation files.
Parcellation scheme
NativeFreesurfer:
Atlas composed of 83 regions from the Freesurfer aparc+aseg file
Lausanne2018:
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.Custom:
You can use any parcellation scheme of your choice as long as they follow the BIDS derivatives specifications for segmentation files, provide appropriate
.tsv
sidecar files that describes the index/label/color mapping of the parcellation, and adopt theatlas-<label>
entity to encode the name of the atlas, i.e:<derivatives_directory>/ sub-<participant_label>/ anat/ <source_entities>[_space-<space>]_atlas-<label>[_res-<label>]_dseg.nii.gz <source_entities>[_space-<space>]_atlas-<label>[_res-<label>]_dseg.tsvThe
res
BIDS entity allows the differentiation between multiple scales of the same atlas.For instance, the above configuration would allows us to re-use the scale 1 of the Lausanne parcellation generated by the anatomical pipeline obtained of the previous
v3.0.2
version of CMP3:your_bids_dataset derivatives/ cmp-v3.0.2/ sub-01/ anat/ sub-01_atlas-L2018_res-scale1_dseg.nii.gz sub-01_atlas-L2018_res-scale1_dseg.tsv ... ... sub-01/ ...
Diffusion pipeline stages
Preprocessing
Preprocessing includes denoising, bias field correction, motion and eddy current correction for diffusion data.
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):
Perform linear registration from T1 to diffusion b0 using FSL’s flirt
Non-linear (ANTS):
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.
Reconstruction tool
Dipy: perform SHORE, tensor, CSD and MAP-MRI reconstruction
SHORE:
SHORE performed only on DSI data
Tensor:
Tensor performed only on DTI data
CSD:
CSD performed on DTI and multi-shell data
MAP_MRI:
MAP-MRI performed only on multi-shell data
MRtrix: perform CSD reconstruction.
CSD:
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:
Deterministic tractography (SD_STREAM) performed on single tensor or CSD reconstruction
Probabilistic tractography:
Probabilistic tractography (iFOD2) performed on SHORE or CSD reconstruction
Probabilistic particle filtering tractography (PFT):
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:
Deterministic tractography (SD_STREAM) performed on single tensor or CSD reconstruction
Deterministic anatomically-constrained tractography (ACT):
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:
Probabilistic tractography (iFOD2) performed on SHORE or CSD reconstruction
Probabilistic anatomically-constrained tractography (ACT):
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, …
Output types
Select in which formats the connectivity matrices should be saved.
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.
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):
Perform linear registration from T1 to mean BOLD using FSL’s flirt.
BBregister (FS)
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
Detrending of BOLD signal using:
linear trend removal algorithm provided by the
scipy
libraryquadratic trend removal algorithm provided by the
obspy
library
Nuisance regression
A number of options for removing nuisance signals is provided. They consist of:
Global signal regression
CSF regression
WM regression
Motion parameters regression
Bandpass filtering
Perform bandpass filtering of the time-series using FSL’s slicetimer
Connectome
Computes ROI-averaged time-series and the correlation connectivity matrices.
Output types
Select in which formats the connectivity matrices should be saved.
EEG pipeline stages
EEG Preprocessing
EEG Preprocessing refers to steps that loads, crop, and save preprocessed EEG epochs data of a given task in fif
format, the harmonized format used further in the pipeline.
EEG data can be provided as:
A
mne.Epochs
object already saved infif
format:A set of the following files and parameters:
Preprocessed EEG recording: store the Epochs * Electrodes dipole time-series in eeglab
set
formatRecording events file in BIDS *_events.tsv format: describe timing and other properties of events recorded during the task
Electrodes file file in `BIDS *_electrodes.tsv format`_ or in Cartool *.xyz format: store the electrode coordinates
Epochs time window: relative start and end time to crop the epochs
EEG Source Imaging
EEG Source Imaging refers to the all the steps necessary to obtain the inverse solutions and extract ROI time-series for a given parcellation scheme.
Structural parcellation: specify the cmp derivatives directory, the parcellation scheme, and the scale (for Lausanne 2018) to retrieve the parcellation files
Tool: CMP3 can either leverage MNE to compute the inverse solutions or take inverse solutions already pre-computed with Cartool as input.
MNE
If
MNE
is selected, all steps necessary to reconstruct the inverse solutions are performed by leveraging MNE. In this case, the following files and parameters need to be provided:
MNE ESI method: Method to compute the inverse solutions
MNE ESI method SNR: SNR level used to regularize the inverse solutions
MNE electrode transform: Additional transform in MNE
trans.fif
format to be applied to electrode coordinates when Apply electrode transform is enabledCartool
If
Cartool
is selected, the following files (generated by this tool) and parameters need to be provided:
Source space file:
*.spi
text file with 3D-coordinates (x, y and z-dimension) with possible solution points necessary to obtain the sources or generators of ERPsInverse solution file:
*.is
binary file that includes number of electrodes and solution pointsCartool esi method: Method used to compute the inverse solutions (Cartool esi method)
Cartool esi lamb: Regularization level of inverse solutions
SVD for ROI time-courses extraction: Start and end TOI parameters for the SVD algorithm that extract single ROI time-series from dipoles.
EEG Connectome
Computes frequency- and time-frequency-domain connectivity matrices with MNE Spectral Connectivity.
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:
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
,<bids_dataset>/code/ref_EEG_config.ini
respectively.You can save individually each of the pipeline configuration files and edit its filename in the File menu (File -> Save anatomical/diffusion/fMRI/EEG 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.
The window of the Connectome Mapper BIDS App GUI will appear, which will help you in setting up and launching the BIDS App run.
Run configuration
Select the output directory for data derivatives
Select the subject labels to be processed
Tune the number of subjects to be processed in parallel
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.
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
Note
The list of pipelines might vary as it is automatically updated based on the availability of raw diffusion MRI, resting-state fMRI, and preprocessed EEG data.
Specify your Freesurfer license
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.If the setup is complete and valid, this will enable the
Run BIDS App
button.
You are ready to launch the BIDS App run!
Execute the BIDS App
Click on the
Run BIDS App
button to execute the BIDS AppYou can see the complete
docker run
command generated by the Connectome Mapper BIDS App GUI from the terminal output such as in this exampleStart 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/Data/ds-demo:/bids_dir', '-v', '/home/localadmin/Data/ds-demo/derivatives:/output_dir', '-v', '/usr/local/freesurfer/license.txt:/bids_dir/code/license.txt', '-v', '/home/localadmin/Data/ds-demo/code/ref_anatomical_config.ini:/code/ref_anatomical_config.ini', '-v', '/home/localadmin/Data/ds-demo/code/ref_diffusion_config.ini:/code/ref_diffusion_config.ini', '-v', '/home/localadmin/Data/ds-demo/code/ref_fMRI_config.ini:/code/ref_fMRI_config.ini', '-u', '1000:1000', 'sebastientourbier/connectomemapper-bidsapp:v3.0.3', '/bids_dir', '/output_dir', 'participant', '--participant_label', '01', '--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', '3', '--ants_number_of_threads', '3'] > BIDS dataset: /bids_dir > Subjects to analyze : ['01'] > 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 3 (total of cores: 11) * ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS set to 3 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-v3.0.3/sub-01/ses-01/sub-01_ses-01_anatomical_config.ini ... Anatomical config created : /output_dir/cmp-v3.0.3/sub-01/ses-01/sub-01_ses-01_anatomical_config.ini WARNING: rewriting config file /output_dir/cmp-v3.0.3/sub-01/ses-01/sub-01_ses-01_diffusion_config.ini ... Diffusion config created : /output_dir/cmp-v3.0.3/sub-01/ses-01/sub-01_ses-01_diffusion_config.ini WARNING: rewriting config file /output_dir/cmp-v3.0.3/sub-01/ses-01/sub-01_ses-01_fMRI_config.ini ... Running pipelines : - Anatomical MRI (segmentation and parcellation) - Diffusion MRI (structural connectivity matrices) ... cmd : connectomemapper3 --bids_dir /bids_dir --output_dir /output_dir --participant_label sub-01 --session_label ses-01 --anat_pipeline_config /output_dir/cmp-v3.0.3/sub-01/ses-01/sub-01_ses-01_anatomical_config.ini --dwi_pipeline_config /output_dir/cmp-v3.0.3/sub-01/ses-01/sub-01_ses-01_diffusion_config.ini --number_of_threads 3
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-v3.X.Y/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.
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):
Segmentation
Select the desired output from the list and click on
view
:
Segmentation results
Surfaces extracted using Freesurfer.
T1 segmented using Freesurfer.
Parcellation
Select the desired output from the list and click on
view
:
Parcellation results
Cortical and subcortical parcellation are shown with Freeview.
Diffusion pipeline stages
Click on the stage you wish to check the output(s):
Preprocessing
Select the desired output from the list and click on
view
:
Registration
Select the desired output from the list and click on
view
:
Registration results
Registration of T1 to Diffusion space (b0). T1 in copper overlayed to the b0 image.
Diffusion reconstruction and tractography
Select the desired output from the list and click on
view
:
Tractography results
DSI Tractography results are displayed with TrackVis.
Connectome
Select the desired output from the list and click on
view
:
Generated connection matrix
Displayed using a:
matrix layout with pyplot
circular layout with pyplot and MNE
FMRI pipeline stages
Click on the stage you wish to check the output(s):
Preprocessing
Select the desired output from the list and click on
view
:
Registration
Select the desired output from the list and click on
view
:
fMRI processing
Select the desired output from the list and click on
view
:
ROI averaged time-series
Connectome
Select the desired output from the list and click on
view
:
Generated connection matrix
Displayed using a:
matrix layout with pyplot
circular layout with pyplot and MNE
EEG pipeline stages
Click on the stage you wish to check the output(s):
EEG Preprocessing
Select the desired output from the list and click on
view
:
Epochs * Electrodes time-series
Plot saved mne.Epochs
object.
EEG Source Imaging
Select the desired output from the list and click on
view
:
BEM surfaces
Surfaces of the boundary-element model used the MNE ESI workflow.
BEM surfaces with sources
Surfaces of the boundary-element model and sources used the MNE ESI workflow.
Noise covariance
Noise covariance matrix and spectrum estimated by the MNE ESI workflow.
ROI time-series
Carpet plot of extracted ROI time-series.
EEG Connectome
Select the desired output from the list and click on
view
:
Generated connection matrix
Displayed using a:
matrix layout with pyplot
circular layout with pyplot and MNE