Release Notes

Version 1.0.1 Beta - 2016.12.09

Participant list builder fixes:

  1. The {participant}, {session}, etc. tags once again work properly, and are now more flexible for custom filepath formats. For example, multiple tags on one directory level, combinations of tags and custom string prefixes/suffixes, and multiple instances of the same tag in one path template are now all supported.
  2. When providing a participant inclusion list (under Subjects to Include) and a site inclusion list (under Sites to Include) at the same time, the builder used to ignore the Sites to Include input. This is no longer the case and will generate an intersection of the Sites and Participant inclusion lists provided.
  3. Including a scan parameters CSV containing information for multiple sites during participant list generation will no longer include scan parameters for sites not included in your data.
  4. Addition of informative messages while constructing the participant list- will warn the user when a participant included in Subjects to Include does not exist or could not be found in the data, and will list these missing participant IDs.
  5. When the input data does not have a session level, the participant list builder will now provide the default session “ses-1” instead of requiring a session level to be included. This is the case for both BIDS and custom data formats.

Installation script updates:

  1. Now more robust to package name differences between different versions of Ubuntu.
  2. Now uses the Neurodebian ants package for all versions of Ubuntu except for 14.04.
  3. Compiles libxp for Ubuntu >= 16.04 for AFNI.

Other updates:

  1. The nuisance regressors are now written out to a 1D file found under “functional_nuisance_regressors” in the output directory.
  2. Fixed a bug where locally-stored input files would potentially deleted if the user would use the “Test Configuration” feature with a participant list that contained both S3 links and local filepath file templates.
  3. A few redundant and unnecessary directories in the individual-level analysis output directory have been removed. These were re-writes of the ANTS-based anatomical registration warp files.
  4. The pipeline configuration file editor now includes the CPAC version number in the configuration YAML file.
  5. More informative error messages for when there is a problem in the pipeline configuration, such as the presence of unreferenced variable names in file paths.

Version 1.0.0 Beta - 2016.11.03

  1. CPAC now calculates network centrality derivatives using the new 3dDegreeCentrality, 3dEigenvectorCentrality, and 3dLFCD AFNI tools implemented by our developers. These implementations are optimized to minimize the memory requirements while speeding up computation time. If you have an already#.existing installation of AFNI that does not have these newer tools, you can update your installation by running “@update.afni.binaries” from your AFNI installation directory.
  2. CPAC inputs can now be directly downloaded from and outputs can be directly uploaded to AWS S3 cloud storage.
  3. SLURM cluster resource scheduler compatibility added.
  4. We removed user specified segmentation thresholds from the segmentation workflow and instead rely on the default thresholds used by FSL’s FAST tool. This removes the issue of choosing an appropriate threshold, which would previously result in no WM or CSF signals for nuisance correction.
  5. The GUI has been reorganized to simplify pipeline configuration, and specifically to improve handling of nuisance correction strategies and specifying ROIs for time series extraction and seed correlation analysis.
  6. Group-level analysis has been over-hauled to make it run more quickly, handle repeated measures, make entering contrasts more intuitive, and improve transparency in to the model generation process.
  7. Nipype and CPAC have been updated to use a resource aware scheduler that incorporates information about the amount of memory and cores currently available when choosing a pipeline step to run. This should maximize running different pipeline steps in parallel while reducing the occurrence of out-of-memory errors and system lock-ups.
  8. The output resolution in MNI space for statistical derivatives (e.g., ReHo, DC, etc) and 4D preprocessed functional data can be specified separately. The user can now also decide not to write the 4D preprocessed data into MNI space. Both of these steps can significantly reduce memory and disk space requirements.
  9. Improved logging.
  10. Column names of ROI time series files and file names for SCA outputs are now based on the unique identifier used for the ROI in the corresponding atlas, making it easier to relate the files back to the ROIs.
  11. For the subject list generated, we replaced the confusing “%s” identifiers in file path templates with {participant}, {site}, {session} to make generating these templates more user friendly.
  12. Added support for BIDS file structure.

Version 0.3.9 Alpha - 2015.04.02

  1. Major group analysis model builder upgrades:

    • F-tests are now fully integrated into the new model builder GUI.
    • Users can now provide their own custom, hand-coded contrasts matrix if they do not wish to use the model builder’s contrast dialog.
    • The “mean of measure” regressor option can now be calculated using a specified mask, in addition to the option of using an automatically created mask for each individual.
    • A custom ROI mask file can now be provided with one or more ROIs - the mean of these ROIs will then be calculated and included as regressors in the model. This will enable for example, including seperate regressors for white matter and CSF.
    • The statistical derivatives to be analyzed can now be specified for each group model, allowing the user more flexibility for using different group models (i.e. include different nuisance regressors) for different derivatives.
    • Better error checking and more informative error and warning messages have been added.
  2. New AWS functionality, which contain utilities for interacting with Amazon Web Services’ S3 storage service, including upload, download, renaming files. Additionally, it provides some tools for local file MD5 sums and AWS credentials fetching.

  3. Scrubbing now works properly.

  4. Pipeline speed-ups gained by ensuring ANTS-based symmetric anatomical registration only runs when necessary.

  5. Moved to Jenkinson’s Mean Framewise Displacement (Mean FD) calculation for MeanFD-related measures.

  6. Made the output file structure for SCA outputs more clear.

  7. Changed the working directory structure for group analysis so that it is more clear.

  8. Fixed a bug where the skull-stripped brain was actually being used when the user selected to calculate the ANTS anatomical-to-template registration with the skull on.

  9. Fixed a bug in group analysis where not all of the selected derivatives would run in some cases.

  10. Fixed a bug where the pipeline would crash if the segmentation thresholds were set too high. This will now result in a easy to understand error message.

  11. Fixed a bug where the cluster size for ReHo would not be properly saved in the pipeline configuration file.

  12. Updated the ANTS registration workflow to work with newer versions of ANTs and ITK.

  13. Fixed a bug where CPAC group-level analysis would not run on a single cluster node, even with “Run CPAC on a Cluster/Grid” turned off.

  14. Introduced more checks and error messages for improper subject-list formatting and inputs.

  15. Introduced checks to determine whether the user has the required software packages installed before starting a pipeline run.

  16. Fixed some bugs where users would run into obstacles when trying to run CPAC on certain installations.

  17. Fixed a bug where AFNI outputs would be written out in the wrong format resulting in a CPAC crash.

Version 0.3.8 Alpha - 2014.12.10

  1. Fixed a bug in which ANTS registration transforms were applied in the wrong order.

  2. “Treatment” coding has been enabled as an option in the Group Analysis Model Builder.

  3. Resolved several errors effecting warping Dual Regression outputs to standard space.

  4. SCA correlation maps now written out into 4D file instead of being stored into a 5D file (with the 4-dimension being a singleton).

  5. Fixed a bug in compCor nuisance regression in which WM and CSF time-series were not variance normalized, as implemented by the original paper.

  6. Updated the cpac_run.py script available in the scripts directory in order to reflect changes in how CPAC is run, update documentation, and enable users to invoke custom installs of Nipype and CPAC.

  7. Several GUI error fixes and improvements:
    • Introduced more descriptive error messages if the subject list is formatted or entered incorrectly.
    • Fixed an issue with input checking in the pipeline configuration editor.
    • Fixed an issue where saving an edited pipeline configuration file would require the user to re-load the file onto the pipeline list.
  8. Developer tools: Created a unit test created for the Network Centrality workflow.

Instructions for Updating to 0.3.8

  1. Download and install the Nipype version 0.10.0, tested to work with CPAC 0.3.8, from Github.
  2. Download the new version from Github or the CPAC homepage.
  3. Replace the old CPAC directory with the new files and then run sudo python setup.py install.

Version 0.3.7 Alpha - 2014.10.29

  1. CPAC 0.3.7 has been migrated to a newer version of Nipype, version 0.10.0. Upgrade instructions are found below.
  2. ANTS anatomical registration now calculates and applies an additional transform which makes registration more robust to certain input images that may have had registration difficulties otherwise.
  3. Users can now set a custom number of cores to dedicate to anatomical registration when using ANTS, enabling faster registration speeds (just be careful not to assign more than you have!).
  4. Group analysis no longer requires symbolic links to be generated in order to run.
  5. Fixed the Network Centrality RAM shortage bug and improved stability of the Network Centrality code.
  6. Network Centrality now produces smoothed non-z-score-standardized outputs.
  7. Bug fixes concerning the GUI and pipeline configuration editor, including an issue where input file paths were checked in the pipeline configuration editor even when the associated workflows were turned off.

Instructions for Updating to 0.3.7

  1. Download and install the Nipype version 0.10.0, tested to work with CPAC 0.3.7, from Github.
  2. Download the new version from Github or the CPAC homepage.
  3. Replace the old CPAC directory with the new files and then run sudo python setup.py install.

Version 0.3.6 Alpha - 2014.10.08

  1. Including EV interactions in group analysis model design is now possible in the CPAC group analysis model builder. Refer to the Patsy documentation for more information on interactions and how to encode them: https://patsy.readthedocs.org/en/latest/formulas.html#the-formula-language
  2. Introduced the option to run ANTS anatomical registration using an input image with the skull on.
  3. Users can now provide CPAC with input anatomical images that have already been skull-stripped.
  4. More flexible slice-timing correction configuration.
  5. z-score standardization and Fisher z-score standardization now take place after registration to template and smoothing, and naming conventions for z-score standardized outputs in the output directory are now more clear.
  6. Dual regression now also outputs anatomically registered and smoothed outputs as files in addition to the regular “stack” (one file with each map included as a volume).
  7. Assorted improvements to error messages and reporting.

Instructions for Updating to 0.3.6

  1. Download the new version from Github or the CPAC homepage.
  2. Replace the old CPAC directory with the new files and then run sudo python setup.py install.

Version 0.3.5 Alpha - 2014.09.22

  1. Upgraded to the newer version of ANTS for anatomical and functional registration, introducing the new tools available and making the installation process more straightforward.

  2. New group analysis model builder:
    • New user-friendly GUI for setting up your group-level analysis model, with an easier interface for configuring your EVs.
    • Design matrices are now generated using the Patsy software package; you can specify your model with a design formula.
    • The ability to include the mean of your output as a regressor has been introduced (mean regression).
    • New interface for specifying contrasts using simple operators (EV1a > EV1b, etc.).
    • Users can now specify a separate output directory for group analysis, so several runs can be completed without having to move previous group-level analysis runs into backup folders.
  3. Improved memory usage during network centrality with sparsity thresholding.

  4. Allowed users to provide their own lateral ventricles mask for CSF nuisance regression and corrected a source of inflexibility regarding how CPAC extracts signal from the ventricles.

  5. Resolved an issue where functional images and derivatives would be written into a resolution other than what the user specified, an issue where f/ALFF outputs would be written into data types more space-consuming than necessary, an issue with an incorrect registration in nuisance correction, and assorted other bug fixes and improved error messages.

  6. Several GUI improvements to user-friendliness in the pipeline configuration editor.

Instructions for Updating to 0.3.5

  1. Download and install the new custom version of Nipype designed to work with CPAC 0.3.5 from Github.
  2. Upgrade your ANTS installation to the newest version - instructions available on the installation page of the CPAC User Guide.
  3. Re-download the CPAC Image Resources to ensure you have the new binarized lateral ventricle masks required for CSF nuisance regression, available here, and follow the instructions available in the User Guide under the section called “Install CPAC Image Resources”.

Version 0.3.4 Alpha - 2014.04.08

  1. Added local Functional Connectivity Density (lFCD) measure to the Network Centrality options.
  2. Added the ability to specify different centrality parameters for each of the measures (degree, eigenvector, lFCD).
  3. Group-level analysis is now able to be run in parallel - simply set the amount of processors you wish to dedicate in the Group
  4. Analysis tab in the pipeline editor window under ‘Number of Models to Run Simultaneously’.
  5. The processing run timing feature is now more polished- look for a cpac_individual_timing_{pipeline name}.csv or cpac_group_timing_{pipeline name}.csv file in your output directory for a breakdown and comparison of information and run times from separate runs.
  6. Introduced the option to turn on/off Z-score standardization of outputs - this can be found within the ‘Derivatives Settings’ tab in the pipeline editor.
  7. GUI fixes and improvements, including errors involving naming the pipeline yaml file and the removal of redundant options.
  8. Group level analysis models no longer overwrite each other within the working directory - all subcategories, ROIs, etc. retain their intermediary files for re-runs.
  9. The ‘Test Configuration’ feature in the pipeline editor is now more robust.
  10. ANTS anatomical registration no longer takes up more processors than has been assigned by the user.
  11. Speed improvements for centrality functions, including new C-based code.
  12. Setting the memory limit for centrality will now work appropriately. Number of voxels to compute connectivity maps for at once will be set to be equal to the memory limit.
  13. Improved unit testing for dual regression, TSE and SCA
  14. TSE can now handle masks and ROIs with floating point values
  15. Pipeline config files with a leading number in their CPAC pipeline name will now load into the GUI properly

Instructions for Updating to 0.3.4

  1. Download the new version from Github or the CPAC homepage.
  2. If you do not have Cython installed already, follow the instructions here.
  3. Replace the old CPAC directory with the new files and then run sudo python setup.py install.

Version 0.3.3 Alpha - 2013.12.31

  1. CPAC is now compatible with Nipy’s Nipype 0.9.
  2. A major group-level analysis error was resolved.
  3. Forking of strategies is now possible through the GUI (for example, running two different registration methods at the same time).
  4. Significant useability improvements to the GUI.
  5. You can now specify separate seeds for timeseries extraction only or timeseries extraction intended for seed correlation analysis (SCA).
  6. A new “Test Configuration” option has been included in the pipeline editor in the GUI which enables users to test their setup before running the pipeline.
  7. An issue where the network centrality workflow would use more cores than assigned has been resolved.
  8. An issue where VMHC maps would only be generated in 2mm resolution despite what was assigned has been resolved.
  9. An issue where the raw correlation map for SCA was only being generated for one seed has been resolved.
  10. An issue where timeseries extraction and seed correlation analysis would not run for new seeds defined in the pipeline editor was resolved.

Version 0.3.2 Alpha - 2013.11.04

  1. The option to use the ANTS registration tool for anatomical registration has been introduced.
  2. The option to toggle Boundary Based Registration on and off for functional to anatomical registration has been introduced.
  3. Automatic QC page creation enabled.
  4. Pipeline configuration files created by older versions of CPAC are now automatically checked for missing parameters.
  5. There have been several assorted GUI fixes and improvements.

Version 0.3.1 Alpha - 2013.09.13

  1. A range of improvements to the GUI and its operation.
  2. Extended improvements to group analysis operation.
  3. Error fix: custom FSL-FNIRT configuration files can now successfully be provided to CPAC.
  4. Error fix: CPAC setup.py would not fully overwrite old files - setup.py now works correctly and also creates a backup folder with the old CPAC install directory.
  5. Addition of some more informative and user-friendly error messages and user warnings.
  6. CPAC pipeline configuration file renamed from config.yml to pipeline_config.yml.
  7. Group analysis function update: the ability to classify EVs as either categorical or continuous has been temporarily removed as we continue our ongoing process of refining CPAC’s group analysis model builder. The user must now provide a phenotypic file (.csv format) with categorical EVs broken out into dummy variables.

Version 0.1.9 Alpha - 2013.03.18

  1. feature: Dual Regression for Spatial Maps and ROIs
  2. feature/issue120: Flexibility with multiple models and model-specific subject list
  3. feature/issue157: Condor cluster job submission support
  4. fix/issue108: (re)check output directory when pipeline is run again
  5. fix/issue147: Split up covariates if create_fsl_model.py when modeling group variances seperately
  6. fix/issue139: Rename “sink” directory to “output” directory

Version 0.1.8 Alpha - 2013.2.20

  1. Modification- replaced all configuration files(config.py, CPAC_subject_list.py, config_fsl.py, data_config.py) to YAML formats
  2. Fix- Ignore empty lines and commented lines in all txt files used as input by CPAC
  3. Fix - Configuration files import issue.
  4. Removed confusing directories with numbers for sca roi outputs and centrality outputs. Now all the ROI outputs go into a single directory per subject and same holds centrality outputs

Version 0.1.7 Alpha - 2013.02.05

  1. Improved Error message for Removing Working Directory
  2. New Centrality Workflow
  3. Fixed underscore problem when no session in the data
  4. FSL model file generator tool : one run, improved error reporting, multicollinearity detection
  5. ROI , mask and template spefications are now files instead of directories
  6. Anatomical and Functional Data can now be registered to different standard resolution templates
  7. Subject processed fully notification after the subject pipeline finishes

Version 0.1.6 Alpha - 2013.01.21

  1. Fix logger in extract_data.py tool
  2. Nuisance code Refactoring
  3. Fixed ROI names in SCA
  4. Added Import for create_fsl_model in local __init__.py
  5. Added New Pipeline names
  6. Fixed Pipeline Naming bug when package is installed
  7. Centrality fix to handle NAN correlation values
  8. Generate ROI nifti files using user co-ordinates
  9. Fix output directory structure to handle multiple model run with single subject list
  10. Fix in Group Analysis, to get 4D EPI as per input subject list
  11. Boundary Based Registration becomes the default registration
  12. New Alff/fAlff workflow
  13. Updates in config file to accomodate new features
  14. Fix to append unit of time(in TR) in slice timing correction: get_scan_parameters
  15. Minor changes in create_fsl_model : replace ‘#’ in output csv name with ‘__’
  16. Feature addition to clear subject level working directory
  17. Added Exception to handle missing dependancy for pygraphviz
  18. Added extract_parameters.py script to consolidate motion parameters

Version 0.1.1 Alpha - 2012.10.15

  • Scrubbing: Users can now specify the number of TRs that should be removed before and after an offending TR.
  • Scrubbing: C-PAC now prints a warning specifying the number of time points left after scrubbing. If no time points are left, C-PAC will crash and print an error.
  • Slice Timing: Users can now specify which sites are run with slice timing correction.
  • Slice Timing: Slice timing correction is now able to read slice timing information directly from an image file, and works on Multiband sequences.
  • Timeseries: Users can now specify a different number of initial TRs to be removed for each site.
  • Data Config: Data extraction now works for the NKI-TRT data set, and automatically extracts scan parameters for each subject from the image file.
  • Fix: C-PAC no longer crashes if dot is not installed. Instead, it prints an error and contines running.