The pyAFQ CLI#

pyAFQ provides two command line interfaces that run the same pipeline underneath:

  • pyAFQ takes explicit paths to a single subject’s DWI and T1w files (in the style of MRtrix commands).

  • pyAFQ-bids takes a BIDS dataset and discovers the inputs with pyBIDS (in the style of BIDS Apps). See pyAFQ-bids: BIDS App style.

pyAFQ: single subject with explicit paths#

The following usage is available:

pyAFQ [OPTIONS] dwi t1 o_folder
pyAFQ download
pyAFQ qsiprep

The first form runs the pyAFQ tractometry pipeline on a single subject.

Two subcommands are also available, and take no further arguments:

download

Fetch every template, atlas, and model pyAFQ may need and cache them locally, then exit. Run this once if you intend to use pyAFQ on a machine without internet access, or to build a Docker image.

qsiprep

Write default JSON configuration files into the current working directory and exit. These can be used to define a pyAFQ recon workflow in qsiprep; no pipeline is run.

Positional arguments#

dwi

Path to DWI data file.

t1

Path to T1-weighted image file. Must already be registered to the DWI data, though not resampled.

o_folder

Path to output folder.

Options#

-h, --help

Show this help message and exit.

--bval BVAL

Path to bval file. If none, the DWI data file path will be used to find it.

--bvec BVEC

Path to bvec file. If none, the DWI data file path will be used to find it.

-v, --verbose

Verbose logging.

-d, --dry-run

Perform a dry run — print the recognized arguments without running pyAFQ.

-c TO_CALL, --call TO_CALL

AFQ.api attribute to get using the specified config file. Defaults to all, which performs the entire tractometry pipeline.

Note that all other pyAFQ optional parameters can also be passed in. To see them, use the --help option, i.e., pyAFQ --help. Here is a full example call to the pyAFQ CLI:

pyAFQ ~/AFQ_data/HBN/derivatives/qsiprep/sub-NDARAA948VFH/ses-HBNsiteRU/dwi/sub-NDARAA948VFH_ses-HBNsiteRU_acq-64dir_space-T1w_desc-preproc_dwi.nii.gz ~/AFQ_data/HBN/derivatives/qsiprep/sub-NDARAA948VFH/anat/sub-NDARAA948VFH_desc-preproc_T1w.nii.gz ~/AFQ_data/HBN/derivatives/afq/sub-NDARAA948VFH/ses-HBNsiteRU/dwi --rng_seed=2026 --return_idx=True --pve="multiaxial+brainchop+synthseg"

pyAFQ-bids: BIDS App style#

pyAFQ-bids [OPTIONS] bids_dir {participant,group}

Inputs are found with pyBIDS from the preprocessed derivatives inside bids_dir (for example the output of qsiprep), so no individual file paths are required. This uses AFQ.api.group.GroupAFQ underneath.

Positional arguments#

bids_dir

Root of the BIDS dataset. Must contain a dataset_description.json and a derivatives folder with preprocessed DWI data.

analysis_level

participant runs the tractometry pipeline for each subject (and session) found. group combines tract profiles computed at the participant level into a single tract_profiles.csv.

Options#

–participant-label LABEL [LABEL …]

Participants to process, with or without the sub- prefix. Default: all participants.

–session-id ID [ID …]

Sessions to process, with or without the ses- prefix. Default: all sessions.

--dwi-preproc-pipeline NAME

Derivatives pipeline containing the preprocessed DWI data, e.g. qsiprep. Default: all.

--t1-preproc-pipeline NAME

Derivatives pipeline containing the preprocessed T1w data. Default: same as --dwi-preproc-pipeline.

--bids-filter-file FILE

JSON file of pyBIDS entity filters used to select the DWI files, e.g. {"acquisition": "64dir", "space": "T1w"}. A qsiprep style file with a top-level "dwi" key is also accepted.

--nprocs N

Number of subject/sessions to process in parallel; -1 uses all CPUs. Default: 1.

--parallel-engine NAME

Parallelization engine (serial, joblib, ray, dask). When --nprocs is not 1 and this is left as serial, joblib is used.

--skip-bids-validation

Do not validate or index metadata with pyBIDS. Speeds up indexing of large datasets.

-v, --verbose

Verbose logging.

-d, --dry-run

Print the recognized arguments without running pyAFQ.

-c TO_CALL, --call TO_CALL

AFQ.api attribute to export at the participant level. Defaults to all. Ignored at the group level.

All other pyAFQ optional parameters accepted by pyAFQ are also accepted here (pyAFQ-bids --help lists them). Example:

pyAFQ-bids ~/AFQ_data/HBN participant --dwi-preproc-pipeline qsiprep --participant-label NDARAA948VFH --nprocs 4 --rng_seed=2026
pyAFQ-bids ~/AFQ_data/HBN group