yaomeng94 / cbptools

CBPtools: A Python package for regional connectivity-based parcellation

CBPtools

Connectivity-Based Parcellation Tools

Regional connectivity-based parcellation (CBP) is a procedure for regional mapping by long-range connectivity profiles (Eickhoff et al., 2015), revealing brain organization within a region-of-interest (ROI).

For a complete overview of the software and a setup guide, visit documentation.

The procedure clusters ROI voxels/vertices based on similarity in their profile of connection strengths to a set of target voxels/vertices, referred to as a connectivity profile. The connectivity profile for each ROI voxel/vertex reflects that voxel/vertex's connectivity to a target space, for instance all gray matter voxels/vertices within the brain for functional data. Voxels/vertices are clustered using the k-means clustering algorithm, which is optimized such that within-group similarity of profiles is high and between-group similarity is low. The resulting clusters form units of homogeneity within an ROI delineated by differences in connectivity, with the units being spatially consistent due to neighboring voxels/vertices having more similar patterns in connectivity than those further away. This provides the CBP procedure with the ability to map distinct brain regions, useful for localizing (dys)function or outlining functional or structural subdivisions/clusters within a particular ROI. Group results are generated by applying a hierarchical clustering algorithm on the individual clustering results. Further processing options can configured by the user.

The type of connectivity depends crucially on the imaging modality, where connectivity means the patterns of anatomical links for structural data through diffusion-weighted imaging (DWI), and statistical dependencies for functional data. CBPtools currently supports two neuroimaging modalities: resting-state bloox-oxygen-level dependent (BOLD) time-series typically used to measure task-independent functional connectivity, and probabilistic diffusion tractography to estimate anatomical fiber-connectivity.

Installation instructions

It is recommended to use a dedicated virtual environment (see virtualenv documentation):

python3 -m venv ~/.venv/cbptools
source ~/.venv/cbptools/bin/activate

CBPtools can be installed using pip by running the following terminal command:

pip install cbptools

Usage example

After installing CBPtools, an example configuration file can be obtained.

cbptools example --get <data type>

Where is replaced by the data you intend to give as input, either rsfmri, dmri, or connectivity. A configuration file with default and placeholder settings will now appear in your current working directory. Edit this file so that it correctly points to the input data and all parameters are set accordingly.

A CBP project can now be created by specifying the location to the configuration file and the working directory in which the project will be created.

cbptools create --config /path/to/config_file.yaml --workdir /path/to/workdir

If any errors appear project creation will fail, and an error log will appear inside of the working directory. If no errors occur, the project will be created. Change directory to the project directory and execute the Snakefile using snakemake, which is installed as a dependency of CBPtools.

cd /path/to/workdir
snakemake

For more customizability on snakemake (Köster and Rahmann, 2012), visit the snakemake documentation.

Licensing

The copyright and all other rights related to the hereby provided products are held by Forschungszentrum Jülich GmbH. The use of the products is only permitted for own educational, scientific or private purposes. The source of the products must be quoted correctly. It is not allowed to revise or amend the provided products or extract only parts of it without the explicit permission of Forschungszentrum Jülich GmbH. Likewise it is not allowed to grant sublicences to third partys.

Acknowledgements

This open source software code was developed in part or in whole in the Human Brain Project, funded from the European Union’s Horizon 2020 Framework Programme for Research and Innovation under the Specific Grant Agreement No. 785907 (Human Brain Project SGA2).

References

Eickhoff SB, Thirion B, Varoquaux G, Bzdok D (2015): Connectivity-based parcellation: Critique and implications. Hum Brain Mapp 36:4771–4792.

Köster J, Rahmann S (2012): Snakemake--a scalable bioinformatics workflow engine. Bioinformatics 28:2520–2522.