User Documentation¶
Welcome to C-PAC’s user guide!¶
The C-PAC Mission¶
Once a distant goal, discovery science for the human connectome is now a reality. Researchers who previously struggled to obtain neuroimaging data from 20-30 participants are now exploring the functional connectome using data acquired from thousands of participants, made publicly available through the 1000 Functional Connectomes Project and the International Neuroimaging Data-sharing Initiative (INDI). However, in addition to access to data, scientists need access to tools that will facilitate data exploration. Such tools are particularly important for those who are inexperienced with the nuances of fMRI image analysis, or those who lack the programming support necessary for handling and analyzing large-scale datasets.
The Configurable Pipeline for the Analysis of Connectomes (C-PAC) is a configurable, open-source, Nipype-based, automated processing pipeline for resting state functional MRI (R-fMRI) data, for use by both novice and expert users. C-PAC was designed to bring the power, flexibility and elegance of the Nipype platform to users in a plug and play fashion—without requiring the ability to program. Using an easy to read, text-editable configuration file or a graphical user interface, C-PAC users can rapidly orchestrate automated R-fMRI processing procedures, including:
standard quality assurance measurements
standard image preprocessing based upon user specified preferences
generation of functional connectivity maps (e.g., seed-based correlation analyses)
customizable extraction of time-series data
generation of graphical representations of the connectomes at various scales (e.g., voxel, parcellation unit)
generation of local R-fMRI measures (e.g., regional homogeneity, voxel-matched homotopic connectivity, frequency amplitude measures)
Importantly, C-PAC makes it possible to use a single configuration file to launch a factorial number of pipelines differing with respect to specific processing steps (e.g., spatial/temporal filter settings, global correction strategies, motion correction strategies, group analysis models). Additional noteworthy features include the ability to easily:
customize C-PAC to handle any systematic directory organization
specify Nipype distributed processing settings
C-PAC maintains key Nipype strengths, including the ability to:
interface with different software packages (e.g., FSL, AFNI, ANTS)
protect against redundant computation and/or storage
automatically carry out input checking, bug tracking and reporting
Future updates will include more configurability, advanced analytic features (e.g., support vector machines, cluster analysis) and diffusion tensor imaging (DTI) capabilities.
For more information and additional tutorials, check out our YouTube channel, as well as slides from our previous presentations:
Latest Release: Version 1.8.4 Beta (Jun 28, 2022)¶
Critical Alert for fMRIPrep-Options in C-PAC v1.8.1 - v1.8.3
Fixed a bug that was causing
single_step_resampling
, when combined with certain other configurations, to inadvertently cause unexpected forks in the pipeline past transform application.This bug caused any affected
fmriprep-options-based
pipeline configurations (includingfx-options
andrbc-options
) to produce BOLD time series write-outs to the output directory in template space which were not nuisance regressed or filtered, for C-PAC versions 1.8.1 through 1.8.3.Although these outputs were not expressly labeled as nuisance regressed or filtered, they were labeled as preprocessed with
desc-preproc
and were the only functional data transformed to template space and used for downstream processing, such as ROI-based timeseries extraction.If you are unsure if you have been affected, you can check the side-car JSON for your template-space BOLD data from these versions for those pipeline configurations, as the JSON will still accurately reflect what operations had been performed on the data.
Summary Here’s what’s new with C-PAC Version 1.8.4
RBC-options pipeline RBC-options pipeline was built and integrated in C-PAC based on the Reproducible Brain Charts initiative, which aims to aggregate and harmonize phenotypic and neuroimage data to delineate node mechanisms regarding developmental basis of psychopathology in youth and yield reproducible growth charts of brain development (Scopel Hoffman et. al., 2021)
Scopel Hoffmann, M., Salum, G., Moore, T. M., Milham, M., & Sattherwaite, T. (2021, December 13). Reproducible Brain Charts initiative - Reliability and Validity of Bifactor Models of Dimensional Psychopathology in Youth. doi:10.17605/OSF.IO/UWY5N
Surface outputs Previously in C-PAC, the main output for the surface pipeline was the CIFTI timeseries (.dtseries) file. Now we are also outputting CIFTI parcellations (.dlabel) in Desikan-Killiany and Destrieux spaces in 164K and 32K resolutions.
Relicense C-PAC was relicensed from BSD-3-Clause to LGPL-3.0-or-later. This license freely allows use, distribution, and modification under the conditions of disclosing the source, license and copyright notice, propagating the license in redistributions and when modified, stating what was changed. Any modifications to LGPL-covered components are required to be made available under the same version or newer of the LGPL or the more restrictive GPL.
Additional v1.8.4 improvements, changes, and fixes can be seen throughout the rest of this release note.
Pipeline Harmonization Updates
Updated the
rbc-options
configuration, based on the Reproducible Brain Charts (RBC) initiative.Updated XCP-QC files to better adhere to the PennLINC XCPEngine pipeline.
New Features
Surface pipeline now outputs 164k and 32k CIFTI parcellations in each of Desikan-Killiany and Destrieux spaces to output directory.
Added a log of expected outputs, generated at the beginning of each C-PAC run.
Improvements
Made ndmg correlation matrices a configurable option, as it used to automatically run for all pipelines before.
Made surface output filenames more BIDS-compliant.
Added the ability to follow symlinks for BIDS directories.
Updated templates used for rodent pipeline and added outputs that were missing.
Added the ability to disable the exception raised if the initial resource check estimates more memory is needed.
Added
--runtime_usage
and--runtime_buffer
flags and related pipeline config entries and functionality.Added additional error checks and a more informative message for node block connecting in the engine.
Expanded some surface post-processing workflows to be more flexible with other pipeline configurations.
Added list of preconfigured pipelines to the usage string.
Relicensed C-PAC from BSD-3-Clause to LGPL-3.0-or-later.
Bug Fixes
Fixed a bug that was causing
single_step_resampling
to crash with3dVolReg
.Fixed a bug that was causing datasets containing phase-difference field maps to crash.
Fixed a merge error preventing QC files and surface derivatives copying to output directory and renaming connectome→connectivity matrix files.
Fixed a bug where subsequent subjects’ logs were being appended to prior subjects’ logs.
Fixed a bug in which ITK header imprecision was causing N4 bias correction to crash.
Fixed a bug where a node with zero nanoseconds in timing information causes report generation to fail.
Fixed a bug in which
--tracking_opt-out
was not applied to calls to utils.
Developer Improvements
Updated CI to only rebuild software dependencies on change.
Added lint definition file.
Added smoke tests.
The C-PAC Team¶
Funding Acknowledgements¶
Primary support for the work by Michael P. Milham, Cameron Craddock and the INDI team was provided by gifts from Joseph P. Healey and the Stavros Niarchos Foundation to the Child Mind Institute, as well as by NIMH awards to Dr. Milham (R03MH096321) and F.X. Castellanos (R01MH083246).