Tractography + SynthSeg Meta-Workflow#

Combined meta-workflow: SynthSeg segmentation feeds ROI labels into a tractography backend selected at build time from config.tractography.method:

probtrackx2 / fsl — the hcp FSL ProbTrackX2 workflow (writes tractography/probtrackx2/).
mrtrix3 / tckgen — the mrtrix3 workflow (5ttgen + dhollander + msmt_csd + mtnormalise + tckgen ACT + tcksift2 + tckmap; writes tractography/mrtrix3/).

thesis.workflows.tract_synthseg#

Combined tractography + SynthSeg segmentation workflow (backend-selectable).

thesis.workflows.tract_synthseg.workflow#

Combined tractography + SynthSeg segmentation workflow (backend-selectable).

Single meta-workflow that joins a SynthSeg segmentation with a tractography backend chosen at build time from config.tractography.method:

probtrackx2 / fsl → the hcp workflow (FSL BedpostX → ProbTrackX2)
mrtrix3 / tckgen → the mrtrix3 workflow (5ttgen → dhollander → msmt_csd → mtnormalise → tckgen ACT → tcksift2 → tckmap)

The two backends write to separate output folders (tractography/probtrackx2 vs tractography/mrtrix3) — that separation is declared by each tractography sub-workflow’s own @produces and is preserved here unchanged.

Architecture:

meta-workflow  (tract_synthseg_{patient_id})
├── inputnode                     ← contract: t1_brain, dwi_mask,
│                                    t1_to_dwi_transform + backend DWI fields
├── synthseg_wf  (synthseg_{patient_id})   [own inputnode/outputnode]
├── tract_wf     (hcp_{pid} | mrtrix3_{pid}) [own inputnode/outputnode]
└── outputnode                    ← contract: fdt_paths

Contract wiring (no node-name introspection):

inputnode.t1_brain                  → synthseg_wf.inputnode.input_image
synthseg_wf.outputnode.segmentation → tract_wf.inputnode.seg_map
inputnode.<field>                   → tract_wf.inputnode.<field>
tract_wf.outputnode.fdt_paths       → outputnode.fdt_paths

The SynthSeg label map is fed into the tractography workflow via a single contract edge; the per-resampler / per-hemisphere fan-out lives inside the tractography workflow. This enables role-per-source mixing without any per-mask resampling step at the meta level:

atlas → seed, waypoint, target (transformed to subject space via ANTs) SynthSeg → avoid (or any combination; already in subject space)

Usage:

thesis run -w tract_synthseg -p 114823 -c tract_synthseg           # ProbTrackX2
thesis run -w tract_synthseg -p 114823 -c tract_synthseg_mrtrix3   # MRtrix3

thesis.workflows.tract_synthseg.workflow.verify_requirements(config, context)[source]#

Pre-run checks for the combined workflow.

Dispatches to the active backend’s verifier (HCP for ProbTrackX2, MRtrix3 for the MRtrix3 backend) based on config.tractography.method, then adds the shared SynthSeg ROI label-file check. The T1w image existence check is provided declaratively by @requires(t1=...) on build_workflow().

Parameters:

config (PipelineConfig) – PipelineConfig
context (ProcessingContext) – ProcessingContext

Return type:

List[str]

Returns:

List of human-readable error strings (empty = all clear).

thesis.workflows.tract_synthseg.workflow.build_workflow(*, t1, config, context)[source]#

Build the combined SynthSeg + tractography meta-workflow.

The tractography backend is chosen from config.tractography.method: probtrackx2/fsl builds the hcp workflow, mrtrix3/tckgen builds the mrtrix3 workflow. Each backend writes to its own tractography/<backend> folder.

ROI source mixing

Configure tractography.atlas_sources for atlas-sourced roles and tractography.synthseg_roi_labels for SynthSeg-sourced roles. Roles can be split arbitrarily:

tractography:
  atlas_sources:
    - name: main                # atlas — seed / waypoint / target
      roi_file: data/masks/annotation_full.nii.gz
      label_file: data/masks/label_map.csv
      waypoint_labels:
        thalamus_left:
          region_kind: seed
          label_name: Thalamus-Left

  synthseg_roi_labels:          # SynthSeg — avoid / stop
    label_file: data/masks/synthseg_lut.csv
    waypoint_labels:
      csf:
        region_kind: avoid
        label_name: CSF

The synthseg_roi_labels section does not include a roi_file because the file is supplied at runtime by connecting the SynthSeg output.

Connection logic

The meta-workflow uses a strict I/O contract — no node-name introspection. inputnode forwards the backend’s contract fields directly to tract_wf.inputnode, and also connects inputnode.t1_brain to synthseg_wf.inputnode.input_image. The single cross-workflow edge synthseg_wf.outputnode.segmentation → tract_wf.inputnode.seg_map delivers the label map; per-resampler / per-hemisphere fan-out is handled inside the tractography workflow. The outputnode re-exposes fdt_paths.

Parameters:

config (PipelineConfig) – PipelineConfig. Must satisfy the active backend’s requirements. May include a synthseg section and/or a tractography.synthseg_roi_labels section.
context (ProcessingContext) – ProcessingContext with patient_id, input_dir, output_dir.
t1 (Path)

Return type:

Workflow

Returns:

Nipype Workflow ready for NipypeExecutor or .run().

thesis.workflows.tract_synthseg.validation#

Validation sub-workflow for tract_synthseg.

Wraps ROI mask validation as a two-node Nipype workflow:: roi_collector → validate_rois

Only used when config.validation.check_rois is True. Backend-agnostic: both the ProbTrackX2 and MRtrix3 tractography sub-workflows re-publish their final ROI sources under the same outputnode contract, so this validation workflow is shared.

thesis.workflows.tract_synthseg.validation.build_validation_workflow(config, context, brain_mask_path)[source]#

Build the ROI validation sub-workflow.

Contains two nodes:

roi_collector — gathers individual ROI path fields into a List[str].
validate_rois — wraps validate_warped_rois_task().

External inputs (connected from the parent meta-workflow):

roi_collector.seed
roi_collector.stop_mask
roi_collector.avoid_mask
roi_collector.target_mask

Parameters:

config (PipelineConfig) – PipelineConfig. Must have a validation section with min_voxels.
context (ProcessingContext) – ProcessingContext with patient_id.
brain_mask_path (str) – Absolute path to the subject-space brain mask used for centroid plausibility check inside validate_warped_rois_task.

Return type:

Workflow

Returns:

Nipype Workflow named validation_{patient_id}.