Workflows

The thesis.workflows package contains all neuroimaging pipeline workflows. Each workflow self-registers with thesis.core.registry.WORKFLOW_REGISTRY at import time via a WorkflowEntry. There are 17 registered entries.

• HCP Workflow
• MRtrix3 Workflow
• Tractography + SynthSeg Meta-Workflow
• Full-Pipeline Meta-Workflow
• Preprocess Workflow
• Registration Workflow
• SynthSeg Workflow
• Atlas Workflow
• Learned Atlas Workflow
• Atlas-to-Patient Workflow
• Tract Similarity Analysis Workflow
• Transform Workflow
• QC Visualisation Workflow

thesis.workflows

Workflow modules for neuroimaging data processing.

Package structure:

• hcp: HCP tractography workflow plus config, node, and operation helpers

• mrtrix3: MRtrix3 tractography workflow (drop-in replacement for hcp)

• synthseg: standalone SynthSeg segmentation workflow

• tract_synthseg: combined meta-workflow joining SynthSeg and a tractography backend (hcp/ProbTrackX2 or mrtrix3) selected by tractography.method

• registration: ANTs-based patient-to-template structural registration

• preprocess: raw DWI/T1/T2 preprocessing into an HCP-compatible layout

• qc: quality-control visualisation and reporting workflow

• transforms: reusable ANTs transform application workflow

• atlas_to_patient: transform cohort atlas maps into patient space

• full_pipeline: composite backend-parameterized meta-workflow (preprocess → registration → tract_synthseg ‖ atlas_to_patient → tract_similarity); backend selected by tractography.method

Main entry points:

• thesis.workflows.hcp.build_workflow

• thesis.workflows.mrtrix3.build_workflow

• thesis.workflows.synthseg.workflow.build_workflow

• thesis.workflows.tract_synthseg.workflow.build_workflow

• thesis.workflows.registration.workflow.build_workflow

• thesis.workflows.preprocess.workflow.build_workflow

• thesis.workflows.transforms.workflow.build_workflow

• thesis.workflows.atlas_to_patient.workflow.build_workflow

• thesis.workflows.full_pipeline.workflow.build_workflow

thesis.workflows.hcp_build_workflow(*, t1, mask, bedpostx, tract_dir, config, context)

Build the HCP ProbTrackX2 tractography workflow.

Hemisphere modes via config.tractography.hemisphere: "left"/"right" (single hemisphere via fixed input), "both" (merged ROIs, default), "both-separately" (two hemispheres via Nipype iterables).

Parameters:

• t1 (Path)

• mask (Path)

• bedpostx (GlobGroupResult)

• tract_dir (Path)

• config (PipelineConfig)

• context (ProcessingContext)

Return type:

Workflow

thesis.workflows.mrtrix3_build_workflow(*, t1, mask, dwi, bvec, bval, tract_dir, config, context)

Build the MRtrix3 tractography workflow for one patient.

Hemisphere modes via config.tractography.hemisphere: "left"/"right" (single hemisphere via fixed input), "both" (merged ROIs, default), "both-separately" (two hemispheres via Nipype iterables).

Parameters:

• t1 (Path)

• mask (Path)

• dwi (Path)

• bvec (Path)

• bval (Path)

• tract_dir (Path)

• config (PipelineConfig)

• context (ProcessingContext)

Return type:

Workflow

thesis.workflows.synthseg_build_workflow(*, t1, seg_dir, config, context)

Build a Nipype workflow that segments a T1w image with SynthSeg.

The workflow contains a single node (synthseg) wrapping mri_synthseg. Outputs land in {output_dir}/segmentation/synthseg/{patient_id}_synthseg.nii.gz.

Parameters:

• t1 (Path | None) – Resolved T1-weighted image path (declared via @requires).

• seg_dir (Path) – Resolved segmentation output directory.

• config (PipelineConfig) – PipelineConfig (may include an optional synthseg section).

• context (ProcessingContext) – ProcessingContext carrying patient_id.

Return type:

Workflow

Returns:

Nipype Workflow ready to run or embed in a meta-workflow.

thesis.workflows.tract_synthseg_build_workflow(*, t1, config, context)

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.preprocess_build_workflow(*, t1, t2, dwi_ap, dwi_ap_bval, dwi_ap_bvec, dwi_pa, config, context)

Build the preprocess workflow for one raw patient dataset.

Parameters:

• t1 (Path | None)

• t2 (Path | None)

• dwi_ap (Path | None)

• dwi_ap_bval (Path | None)

• dwi_ap_bvec (Path | None)

• dwi_pa (Path | None)

• config (PipelineConfig)

• context (ProcessingContext)

Return type:

Workflow

thesis.workflows.registration_build_workflow(*, config, context)

Build the configured registration workflow for one patient.

Parameters:

• config (PipelineConfig)

• context (ProcessingContext)

Return type:

Workflow

thesis.workflows.transform_build_workflow(*, config, context)

Build a transform workflow from config.transforms.jobs.

Parameters:

• config (PipelineConfig)

• context (ProcessingContext)

Return type:

Workflow

thesis.workflows.atlas_to_patient_build_workflow(*, config, context)

Build the atlas-to-patient-space transform workflow.

Delegates to the generic transform workflow after validating that the required transforms are configured. Raises ValueError when no jobs are configured.

Parameters:

• config (PipelineConfig)

• context (ProcessingContext)

Return type:

Workflow

thesis.workflows.full_pipeline_build_workflow(*, template, config, context)

Build the unified full-pipeline meta-workflow for one patient.

The backend is selected from config.tractography.method; BedpostX is enabled/disabled structurally to match.

Parameters:

• template (Path) – Registration template (registration.fixed_image), declared via ExternalFile so an out-of-tree absolute template path is allowed and existence-checked.

• config (PipelineConfig) – Validated pipeline configuration.

• context (ProcessingContext) – Processing context carrying the patient ID, paths, and config.

Return type:

Workflow

Returns:

Nipype Workflow ready for NipypeExecutor or .run().

thesis.workflows.minimal

Minimal Nipype workflow example for CLI usage.

thesis.workflows.minimal.build_workflow(*, out_dir, context)

Build a minimal workflow that writes a marker file.