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:latestlocally.Pull
fcpindi/c-pac:latestfrom 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-PACfrom Singularity Hub.Pull
fcpindi/c-pac:latestfrom 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
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-onlyflag.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 thebids_dircommand line argument. Outputs can be written to S3 using the same format for theoutput_dir. Credentials for accessing these buckets can be specified on the command line (using--aws-input-credsor--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-diror the directory from which you runcpacwill 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 usingtest_configas the analysis level.The
participant_labelandparticipant_ndxarguments 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
-oor--container_options.