NeuroCAPs: Neuroimaging Co-Activation Patterns

NeuroCAPs (Neuroimaging Co-Activation Patterns) is a Python package for performing Co-Activation Patterns (CAPs) analyses on resting-state or task-based fMRI data. CAPs identifies recurring brain states by applying k-means clustering on BOLD timeseries data [1].

Citing

If you would like to cite NeuroCAPs, you can use:

Smith, D., (2025). NeuroCAPs: A Python Package for Performing Co-Activation Patterns Analyses on Resting-State and Task-Based fMRI Data. Journal of Open Source Software, 10(112), 8196, https://doi.org/10.21105/joss.08196

Features

NeuroCAPs is built around two main classes (TimeseriesExtractor and CAP) and includes several features to perform the complete CAPs workflow from postprocessing to visualizations. Notable features includes:

Component	Key Features
Timeseries Extraction (TimeseriesExtractor)	supports Schaefer, AAL, and custom deterministic parcellations performs nuisance regression and motion scrubbing reports quality control based on framewise displacement Important Optimized for BIDS-compliant data preprocessed with fMRIPrep. Refer to NeuroCAPs’ BIDS Structure and Entities Documentation for more information.
CAPs analysis (CAP)	performs k-means clustering finds the optimal number of clusters (silhouette, elbow, variance ratio, Davies-Bouldin) computes temporal dynamic metrics (temporal fraction, persistence, counts, transition frequency and probabilities) [2] [3] converts CAPs to NIfTI images creates visualizations (heatmaps, outer products, surface plots, correlation matrices, cosine similarity radar plots [4] [5] )
Standalone Functions	plots transition matrices merges timeseries data across tasks or sessions [6] generates and fetches custom parcellation approaches

Full details for every function and parameter are available in the API Documentation.

Refer to the demos to the demos or tutorials for an extensive demonstration of the features included in this package.

Dependencies

NeuroCAPs relies on several packages:

dependencies = [
   "numpy>=1.26.3",
   "pandas>=2.1.0",
   "joblib>=1.3.0",
   "matplotlib>=3.6.0",
   "seaborn>=0.11.0",
   "kneed>=0.8.5",
   "nibabel>=5.0.0",
   "nilearn>=0.10.4",
   "scikit-learn>=1.4.0",
   "scipy>=1.10.0",
   "brainspace>=0.1.16",
   "surfplot>=0.2.0",
   "neuromaps>=0.0.5",
   "pybids>=0.16.5; platform_system != 'Windows'",
   "plotly>=6.5.0",
   "nbformat>=5.10.0",
   "kaleido>=1.2.0",
   "setuptools>=77.0.1, <82.0.0",
   "typing_extensions>=4.10.0",
   "vtk>=9.2.0",
   "tqdm>=4.65.0"
   ]

Acknowledgements

Some foundational concepts in NeuroCAPs take inspiration from features or design patterns implemented in other neuroimaging Python packages, specifically:

• mtorabi59’s pydfc, a toolbox that allows comparisons among several popular dynamic functionality methods.

• 62442katieb’s IDConn, a pipeline for assessing individual differences in resting-state or task-based functional connectivity.

References

[1]

Liu, X., Chang, C., & Duyn, J. H. (2013). Decomposition of spontaneous brain activity into distinct fMRI co-activation patterns. Frontiers in Systems Neuroscience, 7. https://doi.org/10.3389/fnsys.2013.00101

[2]

Liu, X., Zhang, N., Chang, C., & Duyn, J. H. (2018). Co-activation patterns in resting-state fMRI signals. NeuroImage, 180, 485–494. https://doi.org/10.1016/j.neuroimage.2018.01.041

[3]

Yang, H., Zhang, H., Di, X., Wang, S., Meng, C., Tian, L., & Biswal, B. (2021). Reproducible coactivation patterns of functional brain networks reveal the aberrant dynamic state transition in schizophrenia. NeuroImage, 237, 118193. https://doi.org/10.1016/j.neuroimage.2021.118193

[4]

Zhang, R., Yan, W., Manza, P., Shokri-Kojori, E., Demiral, S. B., Schwandt, M., Vines, L., Sotelo, D., Tomasi, D., Giddens, N. T., Wang, G., Diazgranados, N., Momenan, R., & Volkow, N. D. (2023). Disrupted brain state dynamics in opioid and alcohol use disorder: attenuation by nicotine use. Neuropsychopharmacology, 49(5), 876–884. https://doi.org/10.1038/s41386-023-01750-w

[5]

Ingwersen, T., Mayer, C., Petersen, M., Frey, B. M., Fiehler, J., Hanning, U., Kühn, S., Gallinat, J., Twerenbold, R., Gerloff, C., Cheng, B., Thomalla, G., & Schlemm, E. (2024). Functional MRI brain state occupancy in the presence of cerebral small vessel disease — A pre-registered replication analysis of the Hamburg City Health Study. Imaging Neuroscience, 2, 1–17. https://doi.org/10.1162/imag_a_00122

[6]

Kupis, L., Romero, C., Dirks, B., Hoang, S., Parladé, M. V., Beaumont, A. L., Cardona, S. M., Alessandri, M., Chang, C., Nomi, J. S., & Uddin, L. Q. (2020). Evoked and intrinsic brain network dynamics in children with autism spectrum disorder. NeuroImage: Clinical, 28, 102396. https://doi.org/10.1016/j.nicl.2020.102396