Constellation Individual Clusters from atlas pipeline - FSL connectome

Clustering of a study region using FSL connectivity data and a provided reference group atlas.

Description

Generalities

The principe of this process is simple, but its application not so simple because it depends on many data, preprocessings, and parameters chosen for all of them.

The idea is to match connectivity data of an individual to the connectivity profiles of an "atlas", using a simple nearest neighbor approach, and to keep the label of the selected atlas vertex.

In order to make it right, individual connectivity data must be processed -more or less- the same way as the atlas has been processed. Namely this means:

Same or compatible diffusion data acquisition - this first condition is almost impossible to guarantee, so we will just assume the tractography will behave statistically the same.

Same cortical segmentation method with vertex-wise inter-subject correspondance. The atlas provided with Constellation has been using FreeSurfer segmentation, and mesh resampling on a 32K HCP sphere per hemisphere (thus, 64K for the whole brain).

Same diffusion data preprocessings and tractography. Here we are in the FSL variant of the pipeline, so it's FSL connectivity, but some parameters may be important, see below.

Same tracts filtering (regions used or filtered out, length filtering, ...)

Same connectivity profile reduction, using the atlas watershed basins

Preprocessings

Before running this "individual clusters from atlas pipeline", individual data should have undegone some preprocessings:

Freesurfer segmentation: recon-all, either directly, or via the Freesurfer toolbox in Brainvisa.

Convert Freesurfer meshes and textures to GIFTI format, and resample meshes to the HCP 32k sphere, using the Freesurfer outputs To BrainVisa conversion pipeline - don't forget to select "hcp 32k" for the "icosphere_type" parameter.

FSL connectivity processings using bedpostx and probtrackx. There are more details here.

Parameters

It is easier to enter parameters in the order they are listed.

"study_name" gets a free string value.

The FSL parameters have to be selected using the "folder" button, not the "database" button, because FSL data are not indexed in a BrainVisa database (at least not yet).

The FSL "temp_outdir" parameter can be a temporary working directory (typically /tmp, it is used for intermediate files conversions, and can be removed after the FSL import step is done.

Atlas provided with Constellation

FSL preprocessings and tractography

The atlas distributed with Constellation has been built from 200 subjects of the Human Connectome Project (HCP) data, using the HCP processing pipelines, with one exception:

The fiber tracking mask is the whole brain, with sulci skeleton removed in order to avoid tracts to cross a sulcus wall. This mask has been built using Morphologist segmentation and sulci skeleton.

The tractography was in "omatrix1" mode: seeds in the cortical ribbon, not in the white matter.

Atlas parameters

The atlas has been built in "averaged" mode (of course), with fibers lengths limited to 20-500mm.

The selected regions were "all but main regions", meaning that intra-region tracts (going from the region to be parcelled to itself) were discarded, in order to avoid any bias to the clustering.

Connectivity matrix smoothing was 3mm.

Individual data should thus follow the atlas preprocessing parameters as closely as possible.

Influence of the "method" parameter

As there is no group analysis here, we can wonder why specifying the "method" parameter ? It actually just changes the "region_parcellation" parameter, taking either a group initial parcellation (average Freesurfer gyri) from the template for the "averaged" mode, or an individual Freesurfer gyri texture for the "concatenated" mode.

Usage example
regions_nomenclature:                /casa/build/share/brainvisa-share-4.6/nomenclature/translation/nomenclature_desikan_freesurfer.txt
outputs_database:                    /my/path/brainvisa_db 
study_name:                          studyA  
method:                              averaged approach
region:                              lh.inferiorparietal
probtrackx_indir:                    /my/path/fsl_db/3T_fsl/omatrix1/100206
temp_outdir:                         /tmp 
individual_white_mesh:               /my/path/freesurfer_db/102008/surf/bh.r.aims.white.gii
regions_parcellation:                /casa/build/freesurfer_db/group_analysis/average_group/average_brain/bh.annot.averagebrain.gii
atlas_matrix:                        /casa/build/share/constellation-1.2/constellation_atlas_hcp_200s/constellation_matrix/subjects/group_analysis/200S/connectivity_clustering/
                                     avg/00woA/lh.inferiorparietal/smooth3.0/200S_avg_00woA_lh.inferiorparietal_group_reduced_matrix_20.0to500.0mm.ima
filtered_reduced_group_profile:      /casa/build/share/constellation-1.2/constellation_atlas_hcp_200s/constellation_matrix/subjects/group_analysis/200S/connectivity_clustering/
                                     avg/00woA/lh.inferiorparietal/smooth3.0/200S_avg_00woA_lh.inferiorparietal_filtered_watershed_20.0to500.0mm.gii
group_clustering:                    /casa/build/share/constellation-1.2/constellation_atlas_hcp_200s/constellation_matrix/subjects/group_analysis/200S/connectivity_clustering/
                                     avg/00woA/lh.inferiorparietal/smooth3.0/200S_avg_00woA_lh.inferiorparietal_avgSubject_clustering_20.0to500.0mm.gii
regions_selection:                   Custom
keep_regions:                        'lh.unknown' 'lh.bankssts' 'lh.inferiorparietal'
min_fibers_length:                   20.0  
smoothing:                           3.0  
kmax:                                12  
normalize:                           True  
complete_individual_matrix:          /my/path/brainvisa_db/subjects/102008/diffusion/default_acquisition/default_analysis/default_tracking_session/
                                     connectivity_parcellation/avg/hcp/lh.inferiorparietal/matrix/102008_hcp_lh.inferiorparietal_complete_matrix_smooth0.0_20.0to500.0mm.imas
complete_individual_smoothed_matrix: /my/path/brainvisa_db/subjects/subjects/102008/diffusion/default_acquisition/default_analysis/default_tracking_session/
                                     connectivity_parcellation/avg/hcp/lh.inferiorparietal/matrix/102008_hcp_lh.inferiorparietal_complete_matrix_smooth3.0_20.0to500.0mm.imas
reduced matrix:                      /my/path/brainvisa_db/subjects/subjects/group_analysis/200S/connectivity_clustering/avg/hcp/lh.inferiorparietal/
                                     smooth3.0/200S_avg_hcp_lh.inferiorparietal_102008_reduced_matrix_20.0to500.0mm.nii.gz
individual_clustering:               /my/path/brainvisa_db/subjects/subjects/group_analysis/200S/connectivity_clustering/avg/hcp/lh.inferiorparietal/
                                     smooth3.0/200S_avg_hcp_lh.inferiorparietal_102008_clustering_20.0to500.0mm.gii

Parameters

regions_nomenclature: Nomenclature ROIs File ( input )
Nomenclature of the cortical parcellation used to partition the study.
Example : Freesurfer Desikan_Killiany Atlas

outputs_database: Choice ( input )
This parameter retrieves all databases with brainvisa ontology present in your configuration, the generated files will be written on the chosen one (see the documentation to add a database in the BrainVisa configuration).

study_name: OpenChoice ( input )
General name of the study.

method: Choice ( input )
Two methods are proposed:
(1) averaged approach to obtain an average result on the group.
(2) concatenated approach to obtain individual results across the group.

region: OpenChoice ( input )
The study region based on regions_nomenclature file.

probtrackx_indir: Directory ( input )
Subjects directory in a FSL connectome database, where the fiber tracts files can be found.

temp_outdir: Directory ( input )
Temporary directory where data files will be stored during importation phase.
Example: /tmp, but this directory size should be large enough to store all the temporary files during the process.

individual_white_mesh: White Mesh ( input )
Freesurfer white-grey interface of the cortex.
Should not be inflated.

regions_parcellation: ROI Texture ( input )
Cortical parcellation used to partition the study.
Example : Freesurfer Desikan_Killiany Atlas (?h.aparc.annot).

atlas_matrix: Connectivity Matrix ( input )
Atlas connectivity matrix preprocessed on a reference group of subjects.

filtered_reduced_group_profile: Connectivity ROI Texture ( input )
Watershed obtained on a reference group of subjects.

group_clustering: Connectivity ROI Texture ( input )
Clustering of the average subject of the reference group of subjects.

atlas_silhouette: Clustering Silhouette ( input )

regions_selection: Choice ( input )
This parameter can be used to exclude some regions from the data analysis. This is useful to study the specific connectivity between a given set of regions, or to exclude the initial patch region.

keep_regions: ListOf( OpenChoice ) ( input )
Kept regions for the data analysis.

min_fibers_length: Float ( input )
A filtering parameter to exclude low length fibers. Default to 20mm.

smoothing: Float ( input )
Degree of smoothing (in millimetres).
Default to 3.0 mm.

kmax: Integer ( input )
Maximal number of clusters used to parcellate the study region.
Default to 12.

normalize: Boolean ( input )
By default the connectivity matrices values are normalized to balance any spurious weighting effects due to more connected regions or subjects, or to the tractography algorithm (number of seeds...). But sometimes we also like to see the raw connectivity matrix: in that case, uncheck this normalization.

erase_matrices: Boolean ( input )

complete_individual_matrix: Connectivity Matrix ( output )
Complete mean connectivity matrix.

complete_individual_smoothed_matrix: Connectivity Matrix ( output )
Complete smoothed mean connectivity matrix.

reduced_matrix: Connectivity Matrix ( output )
Reduced mean matrix using the watershed.

individual_clustering: Connectivity ROI Texture ( output )
Clustering that matches a parcellation of the study region.

optimal_clustering: Connectivity ROI Texture ( output )

Technical information

Toolbox : Constellation

User level : 0

Identifier : constel_indiv_clusters_from_atlas_pipeline

File name : brainvisa/toolboxes/constellation/processes/constel_indiv_clusters_from_atlas_pipeline.py

Supported file formats :
regions_nomenclature :
Text file, Text file
probtrackx_indir :
Directory, Directory
temp_outdir :
Directory, Directory
individual_white_mesh :
GIFTI file, GIFTI file, MESH mesh, MNI OBJ mesh, PLY mesh, TRI mesh
regions_parcellation :
GIFTI file, GIFTI file, Texture
atlas_matrix :
gz compressed NIFTI-1 image, GIS image, NIFTI-1 image, gz compressed NIFTI-1 image
filtered_reduced_group_profile :
GIFTI file, GIFTI file, Texture
group_clustering :
GIFTI file, GIFTI file, Texture
atlas_silhouette :
JSON file, JSON file
complete_individual_matrix :
Sparse Matrix, Sparse Matrix
complete_individual_smoothed_matrix :
Sparse Matrix, Sparse Matrix
reduced_matrix :
gz compressed NIFTI-1 image, GIS image, NIFTI-1 image, gz compressed NIFTI-1 image
individual_clustering :
GIFTI file, GIFTI file, Texture
optimal_clustering :
GIFTI file, GIFTI file, Texture