Regional Connectivity-Based Parcellation

Python package for regional connectivity-based parcellation (rCBP), 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 an installation guide, visit the documentation

Procedure

The rCBP 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 a clustering algorithm, commonly k-means clustering, 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 rCBP 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.

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. The rcbp package currently supports two neuroimaging modalities: resting-state blood-oxygen-level dependent (BOLD) time-series typically used to measure task-independent functional connectivity, and probabilistic diffusion tractography to estimate anatomical fiber-connectivity.

Installation

Read the documentation for more instructions.

Install from this repository:

git clone git@github.com:nhjjr/rcbp.git
cd rcbp
pip install .

Install via PyPi:

pip install rcbp

Usage example

Read the documentation for a more in-depth guide on using the rcbp package.

The rCBP procedure consists of several steps. Each step has an associated helper that can initialize processing parameters, run the procedure, and store the resulting output. Helpers are part of the rcbp.helpers module. Each helper has its own initialization parameters and run arguments outlined in the documentation. The difference between the initialization parameters and run arguments, is that the former are kept consistent between multiple runs of the procedure (e.g., applying the same clustering algorithm to all connectivity profile samples), whereas the latter concerns the input data and should be unique per run.

For example, to preprocess multiple time-series images from different subjects the procedure would look as follows:

import logging

import rcbp
from rcbp.helpers import TimeSeriesHelper

logger = logging.getLogger('rcbp')
logger.setLevel(logging.INFO)  # get info-level logs
logger.info(f'Installed rcbp version: {rcbp.__version__}')

# List of time-series files to be processed
ts_files = [...]

# Prepare input masks
helper = TimeSeriesHelper(
    seed='path/to/seed.nii.gz', 
    target='path/to/target.nii.gz', 
    smoothing_fwhm=5, 
    bandpass=(0.01, 0.08),
    tr_seconds=2)

for i, file in enumerate(ts_files):
    helper.run(time_series=file)
    helper.save(filename=f'path/to/preprocessed/ts_file_{i}.nii.gz')

This sets up a preprocessing procedure for time-series that includes seed- and target-masking, smoothing with a 5mm FWHM, bandpass filtering with high- and low-pass of 0.01 and 0.08, respectively, and a repetition time of 2 seconds. The procedure is then executed like this for all time-series in a list of time-series files (ts_files), and finally stored to disk.

Testing

Run tests using tox

pip3 install tox
tox

Acknowledgements

This open source software code is based on the original cbptools package, which 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.