cbptools 1.1.6
Regional Connectivity-Based Parcellation tool for Python
License: Apache
Requires Python: >=3.5.0

# 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](https://cbptools.readthedocs.io/en/latest/).

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](http://scikit-learn.org/stable/modules/generated/sklearn.cluster.KMeans.html) 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](https://docs.scipy.org/doc/scipy/reference/cluster.hierarchy.html)
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](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments)):

    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 <data type> 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](https://snakemake.readthedocs.io/en/stable/).

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