C-PAC Quickstart

Let’s Go!

  1. The recommended way to run C-PAC is through the use of a container such as Docker or Singularity. Using these containers can be facilitated by cpac (Python package). C-PAC is also available as a brainlife.io/app.

  2. Containers are completely pre-built environments that help ensure reproducibility (same exact library versions, behavior, etc.).

  3. Docker is the more common option, but may require administrative rights on your system. This is a good option for personal machines.

  4. Singularity is the preferred option for shared resources like servers and clusters with many users. Either you or a system administrator can pull a C-PAC Singularity container for global use across your lab or organization.

  5. C-PAC comes pre-packaged with a default pipeline, as well as a growing library of pre-configured pipelines. You can use these to get started right away.

  6. However, you can edit any of these pipelines, or build your own from scratch, using our pipeline builder.

  7. C-PAC can also pull input data from the cloud (AWS S3 buckets), so you can pull public data from any of the open-data releases immediately.

  8. More information regarding all of these points are available below, and throughout the rest of the User Guide.

cpac (Python package)

cpac is available so that you can easily run analyses without needing interact with the container platform that allows you to run C-PAC without installing all of the underlying software.

cpac requires Python 3.8 or greater. To get cpac, simply

pip install cpac

Run extra packages with cpac

Beginning with v1.8.5, cpac can run ba_timeseries_gradients and/or tsconcat in addition to C-PAC. If either package is already installed, cpac will use the installed version. You can install them with the relevant extras, like one of the following lines:

pip install cpac[ba_timeseries_gradients]
pip install cpac[tsconcat]
pip install cpac[ba_timeseries_gradients,tsconcat]

Note

ba_timeseries_gradients and tsconcat may have more specific dependency requirements than C-PAC. If you run into unclear installation issues when installing these extras, please see the documentation for those packages.

Download / Upgrade C-PAC with cpac

To download or upgrade a particular C-PAC image,

cpac pull

or

cpac upgrade

When downloading/upgrading, the --platform, --image, and --tag let you specify platform (Docker or Singularity), image (Docker image name or URL to image in repository), and tag (version tag), respectively.

For example, a development Docker image can be downloaded with

cpac --platform docker --tag nightly pull

Or a Singularity image built from that Docker image can be downloaded with

cpac --platform singularity --tag nightly pull

Run C-PAC with cpac

To run C-PAC in participant mode for one participant, using a BIDS dataset stored on your machine or server and using the container image’s default pipeline configuration:

cpac run /Users/You/local_bids_data /Users/You/some_folder_for_outputs participant

By default, cpac (the wrapper) will try Docker first and fall back to Singularity if Docker fails. If both fail, an exception is raised.

You can specify a platform with the --platform docker or --platform singularity. If you specify a platform without specifying an image, these are the defaults, using the first successfully found image:

Usage

$ cpac --help

usage: cpac [-h] [--version] [-o OPT] [-B CUSTOM_BINDING]
            [--platform {docker,singularity,apptainer}] [--image IMAGE]
            [--tag TAG] [--working_dir PATH] [-v] [-vv]
            {run,utils,version,group,gradients,tsconcat,pull,upgrade,enter,bash,shell,parse-resources,parse_resources,crash}
            ...

cpac: a Python package that simplifies using C-PAC <http://fcp-indi.github.io> containerized images.

This commandline interface package is designed to minimize repetition.
As such, nearly all arguments are optional.

When launching a container, this package will try to bind any paths mentioned in
 • the command
 • the data configuration

An example minimal run command:
     cpac run /path/to/data /path/for/outputs

An example run command with optional arguments:
     cpac -B /path/to/data/configs:/configs \
             --image fcpindi/c-pac --tag latest \
             run /path/to/data /path/for/outputs \
             --data_config_file /configs/data_config.yml \
             --save_working_dir

Each command can take "--help" to provide additonal usage information, e.g.,

     cpac run --help

Known issues:
- Some Docker containers unexpectedly persist after cpac finishes. To clear them, run
    1. `docker ps` to list the containers
  For each C-PAC conatainer that persists, run
    2. `docker attach <container_name>`
    3. `exit`
- https://github.com/FCP-INDI/cpac/issues

positional arguments:
  {run,utils,version,group,gradients,tsconcat,pull,upgrade,enter,bash,shell,parse-resources,parse_resources,crash}
    run                 Run C-PAC. See
                        "cpac [--platform {docker,apptainer,singularity}] [--image IMAGE] [--tag TAG] run --help"
                        for more information.
    utils               Run C-PAC commandline utilities. See
                        "cpac [--platform {docker,apptainer,singularity}] [--image IMAGE] [--tag TAG] utils --help"
                        for more information.
    version             Print the version of C-PAC that cpac is using.
    group               Run a group level analysis in C-PAC. See
                        "cpac [--platform {docker,apptainer,singularity}] [--image IMAGE] [--tag TAG] group --help"
                        for more information.
    gradients           Run ba_timeseries_gradients. See
                        "cpac [--platform "{docker,singularity}] gradients --help"
                        for more information.
    tsconcat            Run ba-tsconcat (<0.2.0,>=0.1.2)
    pull (upgrade)      Upgrade your local C-PAC version to the latest version
                        by pulling from Docker Hub or other repository.
                        Use with "--image" and/or "--tag" to specify an image
                        other than the default "fcpindi/c-pac:latest" to pull.
    enter (bash, shell)
                        Enter a new C-PAC container via BASH.
    parse-resources (parse_resources)
                        .

                        When provided with a `callback.log` file, this utility can sort through
                        the memory `runtime` usage, `estimate`, and associated `efficiency`, to
                        identify the `n` tasks with the `highest` or `lowest` of each of these
                        categories.
                        "parse-resources" is intended to be run outside a C-PAC container.
                        See "cpac parse-resources --help" for more information.
    crash               Convert a crash pickle to plain text (C-PAC < 1.8.0).

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  -o OPT, --container_option OPT, --container_options OPT
                        parameters and flags to pass through to Docker or Singularity

                        This flag can take multiple arguments so cannot be
                        the final argument before the command argument (i.e.,
                        run or any other command that does not start with - or --)
  -B CUSTOM_BINDING, --custom_binding CUSTOM_BINDING
                        directories to bind with a different path in
                        the container than the real path of the directory.
                        One or more pairs in the format:
                             real_path:container_path
                        (eg, /home/C-PAC/run5/outputs:/outputs).
                        Use absolute paths for both paths.

                        This flag can take multiple arguments so cannot be
                        the final argument before the command argument (i.e.,
                        run or any other command that does not start with - or --)
  --platform {docker,singularity,apptainer}
                        If neither platform nor image is specified,
                        cpac will try Docker first, then try
                        Apptainer/Singularity if Docker fails.
  --image IMAGE         path to Apptainer/Singularity image file OR name of Docker image (eg, "fcpindi/c-pac").
                        Will attempt to pull from Singularity Hub or Docker Hub if not provided.
                        If image is specified but platform is not, platform is
                        assumed to be Apptainer/Singularity if image is a path or
                        Docker if image is an image name.
  --tag TAG             tag of the Docker image to use (eg, "latest" or "nightly").
  --working_dir PATH    working directory
  -v, --verbose         set loglevel to INFO
  -vv, --very-verbose   set loglevel to DEBUG

--platform docker

  • Look for fcpindi/c-pac:latest locally.

  • Pull fcpindi/c-pac:latest from Docker Hub.

--platform singularity

  • Look in the present working directory for any Singularity images. If more than one is found, use the most recently modified.

  • Pull FCP-INDI/C-PAC from Singularity Hub.

  • Pull fcpindi/c-pac:latest from Docker Hub and convert to a Singularity image.

You can also specify a container image with an --image argument, passing an image name (e.g., fcpindi/c-pac) for a Docker image or a filepath (e.g. ~/singularity_images/C-PAC.sif) for a Singularity image. You can also specify a --tag (e.g., latest or nightly).

See also

C-PAC versions

You can also provide a link to an AWS S3 bucket containing a BIDS directory as the data source:

cpac run s3://fcp-indi/data/Projects/ADHD200/RawDataBIDS /Users/You/some_folder_for_outputs participant

In addition to the default pipeline, C-PAC comes packaged with a growing library of pre-configured pipelines that are ready to use. To run C-PAC with one of the pre-packaged pre-configured pipelines, simply invoke the --preconfig flag, shown below. See the full selection of pre-configured pipelines here.

cpac run /Users/You/local_bids_data /Users/You/some_folder_for_outputs --preconfig anat-only

To run C-PAC with a pipeline configuration file other than one of the pre-configured pipelines, assuming the configuration file is in the /Users/You/Documents directory:

cpac run /Users/You/local_bids_data /Users/You/some_folder_for_outputs participant --pipeline-file /Users/You/Documents/pipeline_config.yml

Finally, to run C-PAC with a specific data configuration file (instead of providing a BIDS data directory):

cpac run /Users/You/any_directory /Users/You/some_folder_for_outputs participant --data-config-file /Users/You/Documents/data_config.yml

Note: we are still providing the postionally-required bids_dir input parameter. However C-PAC will not look for data in this directory when you provide a data configuration YAML with the --data-config-file flag. Providing . or $PWD will simply pass the present working directory. In addition, if the dataset in your data configuration file is not in BIDS format, just make sure to add the --skip-bids-validator flag at the end of your command to bypass the BIDS validation process.

The full list of parameters and options that can be passed to C-PAC are shown below:

Usage: cpac run

$ cpac run --help

Loading 🐳 Docker
Loading 🐳 fcpindi/c-pac:latest as "root (0)" with these directory bindings:
  local                         Docker                        mode
  ----------------------------  ----------------------------  ------
  /etc/passwd                   /etc/passwd                   ro
  /root/.cpac                   /root/.cpac                   rw
  /home/circleci/build          /home/circleci/build          rw
  /home/circleci/build/log      /home/circleci/build/log      rw
  /home/circleci/build/working  /home/circleci/build/working  rw
  /home/circleci/build/outputs  /home/circleci/build/outputs  rw
Logging messages will refer to the Docker paths.

usage: run.py [-h] [--pipeline-file PIPELINE_FILE] [--group-file GROUP_FILE]
              [--data-config-file DATA_CONFIG_FILE] [--preconfig PRECONFIG]
              [--aws-input-creds AWS_INPUT_CREDS]
              [--aws-output-creds AWS_OUTPUT_CREDS] [--n-cpus N_CPUS]
              [--mem-mb MEM_MB] [--mem-gb MEM_GB]
              [--runtime-usage RUNTIME_USAGE]
              [--runtime-buffer RUNTIME_BUFFER]
              [--num-ants-threads NUM_ANTS_THREADS]
              [--random-seed RANDOM_SEED]
              [--save-working-dir [SAVE_WORKING_DIR]] [--fail-fast FAIL_FAST]
              [--participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
              [--participant-ndx PARTICIPANT_NDX] [--T1w-label T1W_LABEL]
              [--bold-label BOLD_LABEL [BOLD_LABEL ...]] [-v]
              [--bids-validator-config BIDS_VALIDATOR_CONFIG]
              [--skip-bids-validator] [--anat-only]
              [--user_defined USER_DEFINED] [--tracking-opt-out]
              [--monitoring]
              bids_dir output_dir {participant,group,test_config,cli}

C-PAC Pipeline Runner. Copyright (C) 2022-2024 C-PAC Developers. This program
comes with ABSOLUTELY NO WARRANTY. This is free software, and you are welcome
to redistribute it under certain conditions. For details, see https://fcp-
indi.github.io/docs/nightly/license or the COPYING and COPYING.LESSER files
included in the source code.

positional arguments:
  bids_dir              The directory with the input dataset formatted
                        according to the BIDS standard. Use the format
                        s3://bucket/path/to/bidsdir to read data directly from
                        an S3 bucket. This may require AWS S3 credentials
                        specified via the --aws_input_creds option.
  output_dir            The directory where the output files should be stored.
                        If you are running group level analysis this folder
                        should be prepopulated with the results of the
                        participant level analysis. Use the format
                        s3://bucket/path/to/bidsdir to write data directly to
                        an S3 bucket. This may require AWS S3 credentials
                        specified via the --aws_output_creds option.
  {participant,group,test_config,cli}
                        Level of the analysis that will be performed. Multiple
                        participant level analyses can be run independently
                        (in parallel) using the same output_dir. test_config
                        will run through the entire configuration process but
                        will not execute the pipeline.

options:
  -h, --help            show this help message and exit
  --pipeline-file PIPELINE_FILE, --pipeline_file PIPELINE_FILE
                        Path for the pipeline configuration file to use. Use
                        the format s3://bucket/path/to/pipeline_file to read
                        data directly from an S3 bucket. This may require AWS
                        S3 credentials specified via the --aws_input_creds
                        option.
  --group-file GROUP_FILE, --group_file GROUP_FILE
                        Path for the group analysis configuration file to use.
                        Use the format s3://bucket/path/to/pipeline_file to
                        read data directly from an S3 bucket. This may require
                        AWS S3 credentials specified via the --aws_input_creds
                        option. The output directory needs to refer to the
                        output of a preprocessing individual pipeline.
  --data-config-file DATA_CONFIG_FILE, --data_config_file DATA_CONFIG_FILE
                        Yaml file containing the location of the data that is
                        to be processed. This file is not necessary if the
                        data in bids_dir is organized according to the BIDS
                        format. This enables support for legacy data
                        organization and cloud based storage. A bids_dir must
                        still be specified when using this option, but its
                        value will be ignored. Use the format
                        s3://bucket/path/to/data_config_file to read data
                        directly from an S3 bucket. This may require AWS S3
                        credentials specified via the --aws_input_creds
                        option.
  --preconfig PRECONFIG
                        Name of the preconfigured pipeline to run. Available
                        preconfigured pipelines: ['abcd-options', 'abcd-prep',
                        'anat-only', 'benchmark-FNIRT', 'blank', 'ccs-
                        options', 'default', 'default-deprecated', 'fmriprep-
                        ingress', 'fmriprep-options', 'fx-options', 'monkey',
                        'ndmg', 'nhp-macaque', 'preproc', 'rbc-options',
                        'rodent']. See https://fcp-
                        indi.github.io/docs/nightly/user/pipelines/preconfig
                        for more information about the preconfigured
                        pipelines.
  --aws-input-creds AWS_INPUT_CREDS, --aws_input_creds AWS_INPUT_CREDS
                        Credentials for reading from S3. If not provided and
                        s3 paths are specified in the data config we will try
                        to access the bucket anonymously use the string "env"
                        to indicate that input credentials should read from
                        the environment. (E.g. when using AWS iam roles).
  --aws-output-creds AWS_OUTPUT_CREDS, --aws_output_creds AWS_OUTPUT_CREDS
                        Credentials for writing to S3. If not provided and s3
                        paths are specified in the output directory we will
                        try to access the bucket anonymously use the string
                        "env" to indicate that output credentials should read
                        from the environment. (E.g. when using AWS iam roles).
  --n-cpus N_CPUS, --n_cpus N_CPUS
                        Number of execution resources per participant
                        available for the pipeline. This flag takes precidence
                        over max_cores_per_participant in the pipeline
                        configuration file.
  --mem-mb MEM_MB, --mem_mb MEM_MB
                        Amount of RAM available per participant in megabytes.
                        Included for compatibility with BIDS-Apps standard,
                        but mem_gb is preferred. This flag takes precedence
                        over maximum_memory_per_participant in the pipeline
                        configuration file.
  --mem-gb MEM_GB, --mem_gb MEM_GB
                        Amount of RAM available per participant in gigabytes.
                        If this is specified along with mem_mb, this flag will
                        take precedence. This flag also takes precedence over
                        maximum_memory_per_participant in the pipeline
                        configuration file.
  --runtime-usage RUNTIME_USAGE, --runtime_usage RUNTIME_USAGE
                        Path to a callback.log from a prior run of the same
                        pipeline configuration (including any resource-
                        management parameters that will be applied in this
                        run, like 'n_cpus' and 'num_ants_threads'). This log
                        will be used to override per-node memory estimates
                        with observed values plus a buffer.
  --runtime-buffer RUNTIME_BUFFER, --runtime_buffer RUNTIME_BUFFER
                        Buffer to add to per-node memory estimates if
                        --runtime_usage is specified. This number is a
                        percentage of the observed memory usage.
  --num-ants-threads NUM_ANTS_THREADS, --num_ants_threads NUM_ANTS_THREADS
                        The number of cores to allocate to ANTS-based
                        anatomical registration per participant. Multiple
                        cores can greatly speed up this preprocessing step.
                        This number cannot be greater than the number of cores
                        per participant.
  --random-seed RANDOM_SEED, --random_seed RANDOM_SEED
                        Random seed used to fix the state of execution. If
                        unset, each process uses its own default. If set, a
                        `random.log` file will be generated logging the random
                        state used by each process. If set to a positive
                        integer (up to 2147483647), that integer will be used
                        to seed each process. If set to 'random', a random
                        seed will be generated and recorded for each process.
  --save-working-dir [SAVE_WORKING_DIR], --save_working_dir [SAVE_WORKING_DIR]
                        Save the contents of the working directory.
  --fail-fast FAIL_FAST, --fail_fast FAIL_FAST
                        Stop worklow execution on first crash?
  --participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...], --participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]
                        The label of the participant that should be analyzed.
                        The label corresponds to sub-<participant_label> from
                        the BIDS spec (so it does not include "sub-"). If this
                        parameter is not provided all participants should be
                        analyzed. Multiple participants can be specified with
                        a space separated list.
  --participant-ndx PARTICIPANT_NDX, --participant_ndx PARTICIPANT_NDX
                        The index of the participant that should be analyzed.
                        This corresponds to the index of the participant in
                        the data config file. This was added to make it easier
                        to accommodate SGE array jobs. Only a single
                        participant will be analyzed. Can be used with
                        participant label, in which case it is the index into
                        the list that follows the participant_label flag. Use
                        the value "-1" to indicate that the participant index
                        should be read from the AWS_BATCH_JOB_ARRAY_INDEX
                        environment variable.
  --T1w-label T1W_LABEL, --T1w_label T1W_LABEL
                        C-PAC only runs one T1w per participant-session at a
                        time, at this time. Use this flag to specify any BIDS
                        entity (e.g., "acq-VNavNorm") or sequence of BIDS
                        entities (e.g., "acq-VNavNorm_run-1") to specify which
                        of multiple T1w files to use. Specify "--T1w_label
                        T1w" to choose the T1w file with the fewest BIDS
                        entities (i.e., the final option of [*_acq-
                        VNavNorm_T1w.nii.gz, *_acq-HCP_T1w.nii.gz,
                        *_T1w.nii.gz"]). C-PAC will choose the first T1w it
                        finds if the user does not provide this flag, or if
                        multiple T1w files match the --T1w_label provided. If
                        multiple T2w files are present and a comparable filter
                        is possible, T2w files will be filtered as well. If no
                        T2w files match this --T1w_label, T2w files will be
                        processed as if no --T1w_label were provided.
  --bold-label BOLD_LABEL [BOLD_LABEL ...], --bold_label BOLD_LABEL [BOLD_LABEL ...]
                        To include a specified subset of available BOLD files,
                        use this flag to specify any BIDS entity (e.g., "task-
                        rest") or sequence of BIDS entities (e.g. "task-
                        rest_run-1"). To specify the bold file with the fewest
                        BIDS entities in the file name, specify "--bold_label
                        bold". Multiple `--bold_label`s can be specified with
                        a space-separated list. If multiple `--bold_label`s
                        are provided (e.g., "--bold_label task-rest_run-1
                        task-rest_run-2", each scan that includes all BIDS
                        entities specified in any of the provided
                        `--bold_label`s will be analyzed. If this parameter is
                        not provided all BOLD scans should be analyzed.
  -v, --version         show program's version number and exit
  --bids-validator-config BIDS_VALIDATOR_CONFIG, --bids_validator_config BIDS_VALIDATOR_CONFIG
                        JSON file specifying configuration of bids-validator:
                        See https://github.com/bids-standard/bids-validator
                        for more info.
  --skip-bids-validator, --skip_bids_validator
                        Skips bids validation.
  --anat-only, --anat_only
                        run only the anatomical preprocessing
  --user_defined USER_DEFINED
                        Arbitrary user defined string that will be included in
                        every output sidecar file.
  --tracking-opt-out, --tracking_opt-out
                        Disable usage tracking. Only the number of
                        participants on the analysis is tracked.
  --monitoring          Enable monitoring server on port 8080. You need to
                        bind the port using the Docker flag "-p".

Usage: cpac utils

$ cpac utils --help

Loading 🐳 Docker
Loading 🐳 fcpindi/c-pac:latest as "root (0)" with these directory bindings:
  local                         Docker                        mode
  ----------------------------  ----------------------------  ------
  /etc/passwd                   /etc/passwd                   ro
  /root/.cpac                   /root/.cpac                   rw
  /home/circleci/build          /home/circleci/build          rw
  /home/circleci/build/log      /home/circleci/build/log      rw
  /home/circleci/build/working  /home/circleci/build/working  rw
  /home/circleci/build/outputs  /home/circleci/build/outputs  rw
Logging messages will refer to the Docker paths.

Usage: run.py utils [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  crash
  data-config (data_config)
  group-config (group_config)
  pipe-config (pipe_config)
  repickle
  test
  tools
  workflows

Note that any of the optional arguments above will over-ride any pipeline settings in the default pipeline or in the pipeline configuration file you provide via the --pipeline-file parameter.

Further usage notes:

  • You can run only anatomical preprocessing easily, without modifying your data or pipeline configuration files, by providing the --anat-only flag.

  • As stated, the default behavior is to read data that is organized in the BIDS format. This includes data that is in Amazon AWS S3 by using the format s3://<bucket_name>/<bids_dir> for the bids_dir command line argument. Outputs can be written to S3 using the same format for the output_dir. Credentials for accessing these buckets can be specified on the command line (using --aws-input-creds or --aws-output-creds).

  • When the app is run, a data configuration file is written to the working directory. This directory can be specified with --working-dir or the directory from which you run cpac will be used. This file can be passed into subsequent runs, which avoids the overhead of re-parsing the BIDS input directory on each run (i.e. for cluster or cloud runs). These files can be generated without executing the C-PAC pipeline using test_config as the analysis level.

  • The participant_label and participant_ndx arguments allow the user to specify which of the many datasets should be processed, which is useful when parallelizing the run of multiple participants.

  • If you want to pass runtime options to your container plaform (Docker or Singularity), you can pass them with -o or --container_options.

For instructions to run C-PAC in Docker or Singularity without installing cpac (Python package), see All Run Options

C-PAC brainlife.io app

Please visit DOI:10.25663/brainlife.app.399 to see documentation for C-PAC on brainlife.io and brainlife.io generally.

Default Pipeline

C-PAC is packaged with a default processing pipeline so that you can get your data preprocessing and analysis started immediately. Just pull the C-PAC Docker container and kick off the container with your data, and you’re on your way.

The default processing pipeline performs fMRI processing using four strategies, with and without global signal regression, with and without bandpass filtering.

Anatomical processing begins with conforming the data to RPI orientation and removing orientation header information that will interfere with further processing. A non-linear transform between skull-on images and a 2mm MNI brain-only template are calculated using ANTs [3]. Images are them skull-stripped using AFNI’s 3dSkullStrip [5] and subsequently segmented into WM, GM, and CSF using FSL’s fast tool [6]. The resulting WM mask was multiplied by a WM prior map that was transformed into individual space using the inverse of the linear transforms previously calculated during the ANTs procedure. A CSF mask was multiplied by a ventricle map derived from the Harvard-Oxford atlas distributed with FSL [4]. Skull-stripped images and grey matter tissue maps are written into MNI space at 2mm resolution.

Functional preprocessing begins with resampling the data to RPI orientation, and slice timing correction. Next, motion correction is performed using a two-stage approach in which the images are first coregistered to the mean fMRI and then a new mean is calculated and used as the target for a second coregistration (AFNI 3dvolreg [2]). A 7 degree of freedom linear transform between the mean fMRI and the structural image is calculated using FSL’s implementation of boundary-based registration [7]. Nuisance variable regression (NVR) is performed on motion corrected data using a 2nd order polynomial, a 24-regressor model of motion [8], 5 nuisance signals, identified via principal components analysis of signals obtained from white matter (CompCor, [9]), and mean CSF signal. WM and CSF signals were extracted using the previously described masks after transforming the fMRI data to match them in 2mm space using the inverse of the linear fMRI-sMRI transform. The NVR procedure is performed twice, with and without the inclusion of the global signal as a nuisance regressor. The residuals of the NVR procedure are processed with and without bandpass filtering (0.001Hz < f < 0.1Hz), written into MNI space at 3mm resolution and subsequently smoothed using a 6mm FWHM kernel.

Several different individual level analysis are performed on the fMRI data including:

  • Amplitude of low frequency fluctuations (alff) [10]: the variance of each voxel is calculated after bandpass filtering in original space and subsequently written into MNI space at 2mm resolution and spatially smoothed using a 6mm FWHM kernel.

  • Fractional amplitude of low frequency fluctuations (falff) [11]: Similar to alff except that the variance of the bandpassed signal is divided by the total variance (variance of non-bandpassed signal.

  • Regional homogeniety (ReHo) [12]: a simultaneous Kendalls correlation is calculated between each voxel’s time course and the time courses of the 27 voxels that are face, edge, and corner touching the voxel. ReHo is calculated in original space and subsequently written into MNI space at 2mm resolution and spatially smoothed using a 6mm FWHM kernel.

  • Voxel mirrored homotopic connectivity (VMHC) [13]: an non-linear transform is calculated between the skull-on anatomical data and a symmetric brain template in 2mm space. Using this transform, processed fMRI data are written in to symmetric MNI space at 2mm and the correlation between each voxel and its analog in the contralateral hemisphere is calculated. The Fisher transform is applied to the resulting values, which are then spatially smoothed using a 6mm FWHM kernel.

  • Weighted and binarized degree centrality (DC) [14]: fMRI data is written into MNI space at 2mm resolution and spatially smoothed using a 6mm FWHM kernel. The voxel x voxel similarity matrix is calculated by the correlation between every pair of voxel time courses and then thresholded so that only the top 5% of correlations remain. For each voxel, binarized DC is the number of connections that remain for the voxel after thresholding and weighted DC is the average correlation coefficient across the remaining connections.

  • Eigenvector centrality (EC) [15]: fMRI data is written into MNI space at 2mm resolution and spatially smoothed using a 6mm FWHM kernel. The voxel x voxel similarity matrix is calculated by the correlation between every pair of voxel time courses and then thresholded so that only the top 5% of correlations remain. Weighted EC is calculated from the eigenvector corresponding to the largest eigenvalue from an eigenvector decomposition of the resulting similarity. Binarized EC, is the first eigenvector of the similarity matrix after setting the non-zero values in the resulting matrix are set to 1.

  • Local functional connectivity density (lFCD) [16]: fMRI data is written into MNI space at 2mm resolution and spatially smoothed using a 6mm FWHM kernel. For each voxel, lFCD corresponds to the number of contiguous voxels that are correlated with the voxel above 0.6 (r>0.6). This is similar to degree centrality, except only voxels that it only includes the voxels that are directly connected to the seed voxel.

  • 10 intrinsic connectivity networks (ICNs) from dual regression [17]: a template including 10 ICNs from a meta-analysis of resting state and task fMRI data [18] is spatially regressed against the processed fMRI data in MNI space. The resulting time courses are entered into a multiple regression with the voxel data in original space to calculate individual representations of the 10 ICNs. The resulting networks are written into MNI space at 2mm and then spatially smoothed using a 6mm FWHM kernel.

  • Seed correlation analysis (SCA): preprocessed fMRI data is to match template that includes 160 regions of interest defined from a meta-analysis of different task results [19]. A time series is calculated for each region from the mean of all intra-ROI voxel time series. A separate functional connectivity map is calculated per ROI by correlating its time course with the time courses of every other voxel in the brain. Resulting values are Fisher transformed, written into MNI space at 2mm resolution, and then spatial smoothed using a 6mm FWHM kernel.

  • Time series extraction: similar the procedure used for time series analysis, the preprocessed functional data is written into MNI space at 2mm and then time series for the various atlases are extracted by averaging within region voxel time courses. This procedure was used to generate summary time series for the automated anatomic labelling atlas [20], Eickhoff-Zilles atlas [21], Harvard-Oxford atlas [22], Talaraich and Tournoux atlas [23], 200 and 400 regions from the spatially constrained clustering voxel timeseries [24], and 160 ROIs from a meta-analysis of task results [19]. Time series for 10 ICNs were extracted using spatial regression.

Pre-configured Pipelines

In addition to the default pipeline, C-PAC comes packaged with a growing library of pre-configured pipelines that are ready to use. They can be invoked when running C-PAC using the --preconfig flag detailed above.

Detailed information about the selection of pre-configured pipelines are available here.

Design A Pipeline

Note

The C-PAC pipeline configuration was changed to a nested format with import capabilities in v1.8.0.

With this change, the following configuration keys are deprecated:

  • crashLogDirectory

  • output_tree

  • TR

  • fdCalc

  • reGenerateOutputs

  • runMedianAngleCorrection

  • slice_timing_pattern

  • targetAngleDeg

  • runSymbolicLinks

  • configFileTwomm

  • ref_mask_2mm

  • template_skull_for_anat_2mm

  • surface_reconstruction

See Regressors specification to manually update any of the following keys:

  • nComponents

  • nuisanceBandpassFreq

  • numRemovePrecedingFrames

  • numRemoveSubsequentFrames

  • runFrequencyFiltering

  • runFristonModel

  • runMotionSpike

  • spikeThreshold

  • smoothing_order

  • already_skullstripped

  • roiTSOutputs

Mappings for all other C-PAC 1.7 keys can be found here.

C-PAC offers a graphical interface you can use to quickly and easily modify the default pipeline or create your own from scratch: https://fcp-indi.github.io/C-PAC_GUI/

Currently the GUI creates a C-PAC v1.6.0 pipeline configuration file. This syntax persisted through v1.7.2 but is deprecated with the release of v1.8.0.

If given a pipeline file in the older syntax, C-PAC v1.8 will attempt to convert the pipeline configuration file to the new syntax, saving the converted file in your output directory.

An update to the GUI to create v1.8.0 syntax configuration files is underway.

The newer (v1.8) syntax will not work with older versions of C-PAC.

See Using a Text Editor for configuring a custom pipeline without the GUI.

../_images/gui_home1.png

Once you save the pipeline configuration YAML file, you can provide it to the C-PAC Docker container like so:

docker run -i --rm \
        -v /Users/You/local_bids_data:/bids_dataset \
        -v /Users/You/some_folder:/outputs \
        -v /tmp:/tmp \
        -v /Users/You/Documents:/configs \
        -v /Users/You/resources:/resources \
        fcpindi/c-pac:latest /bids_dataset /outputs participant --pipeline-file /configs/pipeline_config.yml

Or you can provide it to the C-PAC Singularity container like so:

singularity run \
        -B /Users/You/some_folder:/outputs \
        -B /tmp:/tmp \
        -B /Users/You/Documents:/configs \
        fcpindi_c-pac_latest-{date}-{hash value}.img s3://fcp-indi/data/Projects/ADHD200/RawDataBIDS /outputs participant --pipeline-file /configs/pipeline_config.yml

Reporting errors and getting help

Please report errors on the C-PAC GitHub issue tracker. Please use Neurostars for help using C-PAC and this application.

Acknowledgments

We currently have a publication in preparation, in the meantime please cite our poster from INCF:

Craddock C, Sikka S, Cheung B, Khanuja R, Ghosh SS, Yan C, Li Q, Lurie D, Vogelstein J, Burns R, Colcombe S,
Mennes M, Kelly C, Di Martino A, Castellanos FX and Milham M (2013). Towards Automated Analysis of Connectomes:
The Configurable Pipeline for the Analysis of Connectomes (C-PAC). Front. Neuroinform. Conference Abstract:
Neuroinformatics 2013. doi:10.3389/conf.fninf.2013.09.00042

@ARTICLE{cpac2013,
    AUTHOR={Craddock, Cameron  and  Sikka, Sharad  and  Cheung, Brian  and  Khanuja, Ranjeet  and  Ghosh, Satrajit S
        and Yan, Chaogan  and  Li, Qingyang  and  Lurie, Daniel  and  Vogelstein, Joshua  and  Burns, Randal  and
        Colcombe, Stanley  and  Mennes, Maarten  and  Kelly, Clare  and  Di Martino, Adriana  and  Castellanos,
        Francisco Xavier  and  Milham, Michael},
    TITLE={Towards Automated Analysis of Connectomes: The {Configurable Pipeline for the Analysis of Connectomes (C-PAC)}},
    JOURNAL={Frontiers in Neuroinformatics},
    YEAR={2013},
    NUMBER={42},
    URL={http://www.frontiersin.org/neuroinformatics/10.3389/conf.fninf.2013.09.00042/full},
    DOI={10.3389/conf.fninf.2013.09.00042},
    ISSN={1662-5196}
}