Usage Notes

The bdt package ships two BIDS Apps that share the same code base, infrastructure, and installation:

  • BDT (bdt CLI) — the BIDS Derivatives Transformer. It applies atlases to BIDS derivative datasets and writes out parcellated data and connectivity matrices.

  • BAT (bat CLI) — the BIDS Atlas Transformer. It manipulates BIDS Atlas datasets via atlas algebra (intersection, union, and outer product).

Both tools follow the BIDS-Apps convention and are configured primarily through a YAML spec file (see Configuration & spec files).

Warning

BDT, BAT, and the atlas/spec machinery described here are under active development. Some options documented below describe the intended design and may not yet be wired up in the installed version. The auto-generated command-line table further down always reflects the options actually available in your installation.

Warning

BDT includes a tracking system to report usage statistics and errors for debugging and grant reporting purposes. Users can opt out using the --notrack command-line argument.

Execution and the BIDS format

Both tools take as principal inputs a BIDS-valid dataset (bids_dir) and an output directory (output_dir), followed by an analysis level. The input dataset and any additional datasets are required to be in valid BIDS format. We highly recommend that you validate your dataset with the free, online BIDS Validator.

Further information about BIDS and BIDS-Apps can be found at the NiPreps portal.

BDT (BIDS Derivatives Transformer)

BDT runs at the participant analysis level, following the standard BIDS-App pattern. Derivative datasets (e.g., fMRIPrep, ASLPrep, QSIRecon) and the BIDS Atlas dataset are passed together via --datasets, and the atlases to apply plus the operations to run are configured in the spec file (--spec). Example:

bdt <bids_dir> <output_dir> participant \
  --datasets fmriprep=/path/to/fmriprep \
             aslprep=/path/to/aslprep \
             qsirecon=/path/to/qsirecon \
             atlases=/path/to/bids-atlas-dataset \
  --spec /path/to/bdt_spec.yaml \
  --participant-label sub-01

Named datasets are provided as name=/path pairs. BDT indexes them all, resolves the transforms needed to bring atlases and data into a shared space, and dispatches each matched file to the appropriate parcellation/connectivity workflow based on its data type and the requested operations.

BAT (BIDS Atlas Transformer)

BAT runs at the dataset analysis level, because atlases are not per-subject. For the single-dataset case, bids_dir is the input BIDS Atlas dataset and no --datasets is needed. Example:

bat <bids_dir> <output_dir> dataset \
  --spec /path/to/bat_spec.yaml

If atlases from multiple input datasets need to be combined, --datasets can be used to name additional atlas datasets.

Input datasets

BDT is a post-processing tool: rather than a single raw dataset, it consumes one or more derivative datasets plus a BIDS Atlas dataset.

  • Derivative datasets are the outputs of upstream preprocessing pipelines. Each is registered with a name via --datasets name=/path so the spec file can refer to it (e.g., datasets: [fmriprep]). Supported inputs include volumetric NIfTI, GIFTI surface, and CIFTI dense data (BOLD/ASL time series, CBF, FA/MD and other scalar maps, cortical thickness), tractograms, and diffusion-model images (SH/ODF/fixels).

  • Transforms are discovered automatically from the *_xfm.* files present in the provided derivative datasets and supplemented with TemplateFlow standard-to-standard transforms. This is how BDT knows how to move an atlas into the data’s space (or the data’s coordinates into the atlas space); see Processing pipeline details.

  • BIDS Atlas dataset provides the atlases to apply. Atlases are selected in the spec file using BIDS entities (atlas, seg, scale, res, desc, …). The file format (NIfTI / GIFTI / CIFTI) of each matched file is auto-detected from its extension at workflow-build time.

Note

BDT is strict rather than heuristic about input selection. If a spec entry matches zero files, or matches more than one file for a single run, or if no transform path exists between an atlas’s space and the data’s space, BDT raises an explicit error naming the conflict rather than guessing. Add more BIDS entities to the offending spec entry to disambiguate.

Command-Line Arguments

BDT: BIDS Derivatives Transformer v26.0.0.dev22+gdea68c57e

usage: bdt [-h] [--skip_bids_validation]
           [--participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
           [-d PACKAGE=PATH [PACKAGE=PATH ...]] --spec SPEC
           [--bids-database-dir PATH] [--nprocs NPROCS]
           [--omp-nthreads OMP_NTHREADS] [--mem MEMORY_MB] [--low-mem]
           [--use-plugin FILE] [--sloppy] [--boilerplate-only]
           [--reports-only] [--random-seed _RANDOM_SEED] [--version] [-v]
           [-w WORK_DIR] [--clean-workdir] [--resource-monitor]
           [--config-file FILE] [--write-graph] [--stop-on-first-crash]
           [--notrack]
           [--debug {compcor,fieldmaps,pdb,all} [{compcor,fieldmaps,pdb,all} ...]]
           bids_dir output_dir {participant}

Positional Arguments

bids_dir

The root folder of a BIDS-valid raw dataset (sub-XXXXX folders should be found at the top level in this folder).

output_dir

The output path for the outcomes of preprocessing and visual reports

analysis_level

Possible choices: participant

Processing stage to be run, only ‘participant’ in the case of BDT (see BIDS-Apps specification).

Options for filtering BIDS queries

--skip_bids_validation, --skip-bids-validation

Assume the input dataset is BIDS compliant and skip the validation

--participant-label, --participant_label

A space delimited list of participant identifiers or a single identifier (the sub- prefix can be removed)

-d, --datasets

Search PATH(s) for pre-computed derivatives and atlases. These must be provided as named folders (e.g., –datasets smriprep=/path/to/smriprep atlases=/path/to/atlases); the names are what selection nodes reference in the spec.

--spec

The BDT node-graph spec: a path to a YAML/JSON file, or the name of a pre-packaged spec. Defines the selection and processing nodes to run.

--bids-database-dir

Path to a PyBIDS database folder, for faster indexing (especially useful for large datasets). Will be created if not present.

Options to handle performance

--nprocs, --nthreads, --n_cpus, --n-cpus

Maximum number of threads across all processes

--omp-nthreads

Maximum number of threads per-process

--mem, --mem_mb, --mem-mb

Upper bound memory limit for BDT processes

--low-mem

Attempt to reduce memory usage (will increase disk usage in working directory)

--use-plugin, --nipype-plugin-file

Nipype plugin configuration file

--sloppy

Use low-quality tools for speed - TESTING ONLY

Options for performing only a subset of the workflow

--boilerplate-only, --boilerplate_only

Generate boilerplate only

--reports-only

Only generate reports, don’t run workflows. This will only rerun report aggregation, not reportlet generation for specific nodes.

Workflow configuration

--random-seed

Initialize the random seed for the workflow

Other options

--version

show program’s version number and exit

-v, --verbose

Increases log verbosity for each occurrence, debug level is -vvv

-w, --work-dir

Path where intermediate results should be stored

--clean-workdir

Clears working directory of contents. Use of this flag is not recommended when running concurrent processes of BDT.

--resource-monitor

Enable Nipype’s resource monitoring to keep track of memory and CPU usage

--config-file

Use pre-generated configuration file. Values in file will be overridden by command-line arguments.

--write-graph

Write workflow graph.

--stop-on-first-crash

Force stopping on first crash, even if a work directory was specified.

--notrack

Opt out of sending tracking information of this run to the NiPreps developers. This information helps to improve NiPreps and provides an indicator of real world usage crucial for obtaining funding.

--debug

Possible choices: compcor, fieldmaps, pdb, all

Debug mode(s) to enable. ‘all’ is alias for all available modes.

Reusing precomputed derivatives

Reusing a previous, partial execution of BDT

BDT will pick up where it left off a previous execution, so long as the work directory points to the same location, and this directory has not been changed/manipulated. Some workflow nodes will rerun unconditionally, so there will always be some amount of reprocessing.

Troubleshooting

Logs and crashfiles are output into the <output dir>/logs directory. Information on how to customize and understand these files can be found on the Debugging Nipype Workflows page.

Support and communication

The documentation of this project is found here: https://bdt.org/en/latest/.

All bugs, concerns and enhancement requests for this software can be submitted here: https://github.com/nipreps/bdt/issues.

If you have a problem or would like to ask a question about how to use BDT, please submit a question to NeuroStars.org with a bdt tag. NeuroStars.org is a platform similar to StackOverflow but dedicated to neuroinformatics.

Previous questions about BDT are available here: https://neurostars.org/tag/bdt/

About the NiPreps framework licensing

Please check https://www.nipreps.org/community/licensing/ for detailed information on the criteria we use to license BDT and other projects of the framework.

License information

Copyright (c) the NiPreps Developers.

BDT is licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright (c), the BDT developers and the CRN. All rights reserved.

All trademarks referenced herein are property of their respective holders.