Prepare — DWI#

What are we preparing?#

Diffusion-weighted imaging (DWI) pipelines (rtppreproc, rtp-pipeline, rtp2-preproc, rtp2-pipeline, anatrois, freesurferator) need their inputs organised in a very specific directory structure before they can be submitted to the cluster. The prepare step:

  1. Validates that all required files exist for each subject/session (T1 anatomical, DWI NIfTI, bval, bvec, FreeSurfer outputs, etc.).

  2. Creates the analysis directory under <bidsdir>/derivatives/<container>-<version>/analysis-<name>/ and writes a frozen copy of every config file into it — so the exact parameters used for a run are always traceable.

  3. Generates per-subject launch scripts (job_scripts_<timestamp>/) ready to be submitted with sbatch, qsub, or run locally.

  4. Copies auxiliary files (annotation files, ROI archives, tract parameter tables, brain masks) into the analysis directory so the container has everything it needs in one place.

No DWI data are modified. The prepare stage only reads from your BIDS tree and writes into the derivatives analysis directory.

How the pipeline works#

Config building (gen_config_dict_and_copy)#

gen_config_dict_and_copy() reads the launchcontainers YAML and builds the inputs dictionary that the container config.json expects. Depending on the active container it also calls copy_rtp2_configs() to copy any optional auxiliary files (annotation .zip, ROI .zip, tract parameter .csv, FreeSurfer mask .nii.gz) into the analysis directory.

Subject-level input preparation (RTP2_prepare_input)#

RTP2_prepare_input handles per-subject input resolution — locating the correct DWI file (or RPE pair), T1, bval / bvec, and FreeSurfer directory — and writes the paths into the per-subject config.json that the container will read at runtime.

Supported containers and their required inputs#

Container

Key inputs validated at prepare time

anatrois

T1 NIfTI (or existing FreeSurfer zip), optional annotation file, optional MNI ROI zip

freesurferator

T1 NIfTI (or existing FreeSurfer zip), optional control points, annotation file, MNI ROI zip

rtppreproc

T1, DWI NIfTI, bval, bvec, FreeSurfer mask

rtp-pipeline

T1, DWI, bval, bvec, FreeSurfer mask, tract parameter CSV, optional FreeSurfer mask NIfTI

rtp2-preproc

T1, DWI, bval, bvec, FreeSurfer mask

rtp2-pipeline

T1, DWI, bval, bvec, FreeSurfer mask, tract parameter CSV, optional FreeSurfer mask NIfTI

API reference#

See API Reference for the full auto-generated documentation of all classes and functions in this module:

  • launchcontainers.prepare.dwi_prepare

  • launchcontainers.prepare.RTP2_prepare_input