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.5 Beta (May 24, 2023)#
New Features
Extension of Template-Space Processing.
In an effort to support compatibility with other tools being used in the field, C-PAC now has the option of performing several operations in template space, where they have historically only been supported within C-PAC in native space. These features now include:
Time series despiking via AFNI 3dDespike.
Nuisance correction and denoising.
Calculation of the ALFF, f/ALFF and ReHo derivatives.
Connectome computation (already supported; included for completeness)
Improved Robustness of Default Pipeline Configuration.
A modified version of the legacy C-PAC default pipeline has been released that improves stability across datasets. This pipeline largely maintains the original preprocessing choices, with the modification of employing robust FSL BET for T1w brain mask generation rather than AFNI. This change was motivated by a difference in design of these two components, where AFNI would exclude ventricles from brain mask generation, occasionally leading to downstream errors in nuisance signal correction.
The pre-1.8.5 default pipeline is still available for users as a preconfigured pipeline under the name
default-deprecated.
Downsampling of surface data.
While surface analysis is typically performed on high resolution surfaces and then downsampled to the resolution of the structural images being acquired, further downsampling may be required when working with functional data. To minimize the influence of signal interpolation on downstream markers, such as Regional Homogeneity, we now support downsampling of surface data to a resolution that matches the input functional data resolution.
Motion estimate filter forking capability expanded.
Previous versions of C-PAC allowed for the application of 0‒1 motion estimate filters. C-PAC now supports configuring any number of motion estimate filters; each filter is applied independently.
Support for Fail-Fast workflow execution.
To minimize waste of computational resources and reduce the possibility of misunderstanding of partial derived datasets, the new
fail-fastoption in C-PAC tells the workflow engine to stop running in the event of any failed or incomplete processing step.
Improvements
Freesurfer outputs ingress overhaul.
The process of ingressing Freesurfer recon-all outputs into the C-PAC pipeline has been streamlined. Freesurfer output directories are now linked in the C-PAC data configuration YAML files, rather than pipeline configurations, for each participant and session of data.
Preconfigured pipelines which employ Freesurfer-based surface processing, such as the abcd-options pipeline, now use the surface-derived T1w brain mask as the default, rather than redundantly computing separate masks.
Output directory BIDS-Derivatives compliance and naming improvement.
The output files in template space now feature the specific
space-*tag, mapping to standardized names for the template entities, instead of the more genericspace-templatetag.Data that has been nuisance corrected now feature BIDS labels which name the user-provided regressor strategy name, instead of providing this information in the information-dense sidecar JSONs.
Corrected erroneous forking in ABCD-options pipeline.
While no errors were produced in the terminal outputs, redundant computation was previously taking place which led to a slowdown for this configuration, or others which may have used the post-freesurfer processing blocks. The source of this issue has been identified and corrected.
For Nilearn-generated correlation matrices, diagonals are now set to all 1s (were all 0s).
Distortion correction improvements.
Fixed an issue where the distortion correction un-warps were not being applied to the final template-space BOLD time series data, depending on pipeline configuration decisions.
Replaces
DwellTimewithEffectiveEchoSpacingin the application of FSL FUGUE, consistent with the intention of the documentation and correcting inconsistent nomenclature.Added the ability to ingress TotalReadoutTime from epi field map meta-data from JSON sidecars.
Added the ability to use TotalReadoutTime of epi field maps in the calculation of FSL topup distortion correction.
Identified future directions for refining distortion correction further, including the modernization of some libraries to support the adoption of the sdcflows library.
Run directory and logging improvements.
Added a level of depth to working directories to match log and output directory structure.
Renamed participant-pipeline-level output directory prefix to
pipeline_to match log and working paths.Added crash messages from during and before graph building to logs.
Added data-config-specific hash string to C-PAC-generated config files.
Error Fixes
Single-step resampling has been fixed such that motion-corrected BOLD time series data is blocked from being used as the input, as the motion correction transforms are factored into the transform application.
Fixed a bug in which generated pipeline configs were not representative of the input configurations being specified. The only affected configurable option discovered in testing was when seed-based correlation analysis was used, the engine was always reverting to the default configuration.
Fixed bug that was causing
cpac runto fail when passing a manual random seed via--random_seedrather than directly in the pipeline config file.Fixed an issue that was causing some epi field maps to not be ingressed if the BIDS tags were not in a specific (BIDS-compliant) order.
Fixed an issue where phase-difference GRE field map files were not properly being ingressed if the filenames were not expected, such as including an index for cases with multiple maps.
Fixed a bug where ALFF & f/ALFF would not run if frequency filtering was disabled earlier in the pipeline.
Fixed a bug where Freesurfer directories were not successfully ingressed at runtime.
Added public read access to some overly restricted packaged templates.
Fixed a bug where the notch filter was always assuming the sampling frequency was
2.0.
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).