Configuration & spec files

Both BDT and BAT are driven by a YAML spec file, passed with --spec. The spec file names what to do: which atlases to apply to which data, and which operations to run. Run-level settings (paths, participants, resources) come from the command line and are stored in a configuration singleton (see Run configuration below).

Warning

The spec grammar described here reflects the intended design of BDT/BAT and may not yet be fully wired up in the installed version.

bdt_spec.yaml

The BDT spec is a list of sources. Each source binds a derivative type (identified by BIDS entities) to a set of atlases and operations. Atlases are specified as lists of entity-filter dicts, which are passed directly to PyBIDS .get(). The file format (NIfTI / GIFTI / CIFTI) is auto-detected from the matched file’s extension at workflow-build time, so a single spec entry works regardless of the format of the underlying derivative.

sources:
  - suffix: bold
    datasets: [fmriprep]
    operations: [parcellate_timeseries, functional_connectivity]
    atlases:
      - atlas: HCPMMP1
      - atlas: Schaefer2018
        seg: 17networks
        scale: 400          # scale- = region count

  - suffix: cbf
    datasets: [aslprep]
    operations: [parcellate_scalar]
    atlases:
      - atlas: HCPMMP1
        res: 2

  - suffix: asl
    datasets: [aslprep]
    operations: [parcellate_timeseries]
    atlases:
      - atlas: HCPMMP1

  - suffix: tractogram         # BEP 046
    datasets: [qsirecon]
    operations: [streamline_connectivity, bundle_stats]
    atlases:
      - atlas: Schaefer2018
        seg: 17networks
        scale: 400

  - suffix: dwimap             # BEP 016: model-/param- diffusion model
    datasets: [qsirecon]
    model: csd
    param: wm
    operations: [parcellate_odf]
    atlases:
      - atlas: HCPMMP1

Each source entry accepts:

• BIDS entity filters (suffix, datasets, model, param, task, desc, …) used to collect the derivative files to process. datasets names the derivative dataset(s) registered on the command line with --datasets.

• operations — a list of operations to run on each matched file (see below).

• atlases — a list of entity-filter dicts selecting atlases from the BIDS Atlas dataset. Each dict may include atlas, seg, scale, res, desc, and so on.

Supported operations

Operation	Description
parcellate_timeseries	Extract per-parcel mean time series from a 4D image (BOLD, ASL).
parcellate_scalar	Extract per-parcel means from a scalar map (CBF, FA/MD, thickness, …).
functional_connectivity	Build a region-by-region connectivity matrix from parcellated time series.
streamline_connectivity	Warp a tractogram into the atlas’s space and assign each streamline’s two endpoints to parcels, producing an N×N connectivity matrix.
bundle_stats	Per-tractogram summary statistics (count, mean length, density). This is a whole-tractogram summary, not a connectivity matrix.
parcellate_fixel	Per-parcel fixel summary (respects fixel cardinality/direction).
parcellate_odf	Per-parcel ODF/SH-coefficient summary.

Note

Tractography I/O. The only BIDS-compliant tractography format is TRX (.trx). .tck/.trk are accepted only as ingest conveniences and are converted to .trx on the way in. The tractogram suffix is tractogram, optionally carrying tract-<name> (anatomical structure) and track-<method>.

Note

Entities from BIDS Extension Proposals. Because sources are selected with BIDS entities, the spec understands the entities defined by the relevant BEPs: model-/param- for diffusion models (BEP 016), tract-/track- for tractograms (BEP 046), and seg-/scale- for atlas realizations (BEP 017). scale- is the BIDS-blessed encoding of a parcellation’s region count (e.g., Schaefer’s 400), replacing the older desc-400Parcels17Networks idiom.

bat_spec.yaml

The BAT spec is a list of operations. Each operation names an atlas-algebra step, its inputs (entity-filter dicts), and the BIDS entities for the output atlas. Entity values must be alphanumeric (a BIDS requirement — no hyphens or underscores).

operations:
  - name: corticalSubcortical
    operation: union
    inputs:
      - atlas: HCPMMP1
      - atlas: Tian
        seg: S2
    output_entities:
      atlas: HCPMMPTian

  - name: networkParcels
    operation: intersect
    inputs:
      - atlas: Schaefer2018
        seg: 17networks
        scale: 400
      - atlas: RSN
        desc: networks
    output_entities:
      atlas: Schaefer2018RSN
      desc: 400Parcels17NetworksRSN

  - name: parcelBundles
    operation: outer_product
    inputs:
      - atlas: Schaefer2018
        seg: 17networks
        scale: 400
      - atlas: AFQ
        seg: bundles
    output_entities:
      atlas: Schaefer2018AFQ

Supported operations

Operation	Description
intersect	Voxel-wise label restriction: keep voxels labeled in both atlases and relabel to the first atlas’s parcel.
union	Combine two atlas label images; overlaps are resolved by a precedence rule rather than an error.
outer_product	Cartesian sub-parcels: combine the two atlases’ labels into one label per overlapping region (e.g., Schaefer parcels × AFQ bundles).

Note

Scope. BAT operates on discrete label images (dseg) only and emits dseg. All inputs to a given operation must share the same template (tpl-) space; BAT raises an error if they do not. Probabilistic (probseg) atlases and streamline data are out of scope, but a bundle atlas already rasterized to a dseg label image is a valid input.

Run configuration

Beyond the spec file, run-level settings are held in a configuration singleton (config.py), serialized to TOML so it can be shared across processes. A copy of the resolved settings is written under the log directory for each run. The configuration is organized into sections:

Section	Scope	Key fields
environment	shared	version, nipype_version, exec_env (read-only; recorded for reporting)
execution	shared	bids_dir, output_dir, datasets, spec, participant_label
workflow	shared	spaces, file_format (auto / nifti / gifti / cifti)
bdt_workflow	BDT only	min_coverage, dummy_scans, correlation_lengths, output_correlations
bat_workflow	BAT only	output_space, interpolation
nipype	shared	nprocs, omp_nthreads, plugin

With file_format = auto (the default), the format of each collected file is detected from its extension at workflow-build time and used to route the file to the appropriate format-specific parcellation subworkflow.