Full-Pipeline Meta-Workflow#

Composite per-patient meta-workflow that chains preprocess, registration, SynthSeg-driven tractography, atlas-to-patient transforms, and tract similarity in a single Nipype execution graph.

The backend is selected at runtime by config.tractography.method; the unified tract_synthseg meta-workflow reads the same value to build the matching tractography backend:

"probtrackx2" (default) — tract_synthseg builds the hcp backend with BedpostX.
"mrtrix3" — tract_synthseg builds the mrtrix3 backend; BedpostX is structurally disabled.

To run the MRtrix3 variant use the full_pipeline_mrtrix3 protocol config, which sets tractography.method: mrtrix3:

thesis run -w full_pipeline -p 114823 -c full_pipeline_mrtrix3

Shared scaffold#

Backend-agnostic scaffolding for the unified full_pipeline meta-workflow.

This module factors out the parts of the meta-workflow that are independent of the tractography backend (ProbTrackX2 vs MRtrix3): the cross-stage edges that wire preprocess, registration, atlas_to_patient, and tract_similarity together, plus the BackendDescriptor capturing the per-backend deltas.

full_pipeline builds its sub-workflows, then calls wire_core_scaffold() to install the backend-agnostic contract edges and finalize_tract_similarity_merge() to install the stage-5 barrier. The backend is chosen with select_backend() from tractography.method.

class thesis.workflows.full_pipeline._core.BackendDescriptor[source]#

Bases: object

Captures the per-backend deltas of the full pipeline.

Variables:

name – Canonical backend name ("probtrackx2" | "mrtrix3").
run_bedpostx – Whether preprocess should run BedpostX.
required_binaries – External binaries the verifier checks on PATH.
tractography_edges – (preprocess.outputnode.<src>, tract_synthseg.inputnode.<dst>) field pairs to connect.

Parameters:

name (str)
run_bedpostx (bool)
required_binaries (tuple[str, ...])
tractography_edges (tuple[tuple[str, str], ...])

name: str#

run_bedpostx: bool#

required_binaries: tuple[str, ...]#

tractography_edges: tuple[tuple[str, str], ...]#

__init__(name, run_bedpostx, required_binaries, tractography_edges)#

Parameters:

name (str)
run_bedpostx (bool)
required_binaries (tuple[str, ...])
tractography_edges (tuple[tuple[str, str], ...])

Return type:

None

thesis.workflows.full_pipeline._core.select_backend(method)[source]#

Return the BackendDescriptor for tractography.method.

Raises:: ConfigurationError – when method is not a recognised backend.
Parameters:: method (str)
Return type:: BackendDescriptor

class thesis.workflows.full_pipeline._core.CoreScaffold[source]#

Bases: object

Resolved handles for cross-stage wiring.

Variables:

meta – The meta-workflow being assembled.
preprocess_wf – Patient-level preprocessing sub-workflow.
registration_wf – Patient-to-template registration sub-workflow.
atlas_to_patient_wf – Template-to-patient transform sub-workflow.
tract_similarity_wf – Tract similarity / metrics sub-workflow.
reg_method – Registration backend ("ants" | "fireants").

Parameters:

meta (Workflow)
preprocess_wf (Workflow)
registration_wf (Workflow)
atlas_to_patient_wf (Workflow)
tract_similarity_wf (Workflow)
reg_method (str)

meta: Workflow#

preprocess_wf: Workflow#

registration_wf: Workflow#

atlas_to_patient_wf: Workflow#

tract_similarity_wf: Workflow#

reg_method: str#

__init__(meta, preprocess_wf, registration_wf, atlas_to_patient_wf, tract_similarity_wf, reg_method)#

Parameters:

meta (Workflow)
preprocess_wf (Workflow)
registration_wf (Workflow)
atlas_to_patient_wf (Workflow)
tract_similarity_wf (Workflow)
reg_method (str)

Return type:

None

thesis.workflows.full_pipeline._core.wire_core_scaffold(meta, config, *, preprocess_wf, registration_wf, atlas_to_patient_wf, tract_similarity_wf)[source]#

Wire the backend-agnostic edges between sub-workflows via contracts.

Edges wired (all contract-to-contract, no node-name introspection):

preprocess.outputnode.t1_brain → registration.inputnode.moving_image
registration.outputnode.transform → atlas_to_patient.entry_gate.ready
preprocess.outputnode.dwi_mask → atlas_to_patient.entry_gate.preprocess_done
(FireANTs only) registration.outputnode.{reverse,forward}_transforms → atlas_to_patient.entry_gate.{reverse,forward}_transforms

The runtime T1-brain injection on atlas_to_patient.entry_gate.reference_image is left to the caller (it sources the value from preprocess.outputnode.t1_brain).

Parameters:

meta (Workflow) – The meta-workflow being assembled.
config (PipelineConfig) – Validated pipeline configuration.
preprocess_wf (Workflow) – Pre-built preprocess sub-workflow.
registration_wf (Workflow) – Pre-built registration sub-workflow.
atlas_to_patient_wf (Workflow) – Pre-built atlas_to_patient sub-workflow.
tract_similarity_wf (Workflow) – Pre-built tract_similarity sub-workflow.

Return type:

CoreScaffold

Returns:

A CoreScaffold carrying the sub-workflow handles and the resolved registration backend name.

thesis.workflows.full_pipeline._core.finalize_tract_similarity_merge(scaffold, fdt_sources)[source]#

Wire the tract_similarity stage barrier.

Builds a Merge node with len(fdt_sources) + 1 inputs (one per backend fdt_paths source plus atlas_to_patient.exit_gate.done) and connects its out output to tract_similarity.entry_gate.ready.

Merge is used (not IdentityInterface) because Merge.out fires only when every input is set — a true “wait for all” barrier. IdentityInterface forwards per-field, which would let downstream nodes fire before all upstream stages complete.

Parameters:

scaffold (CoreScaffold) – The scaffold returned by wire_core_scaffold().
fdt_sources (list[tuple[Workflow, str]]) – (sub_workflow, output_port) pairs producing the backend’s fdt_paths outputs. One entry for single-hemisphere runs, two for hemisphere=both-separately.

Return type:

Node

Returns:

The Merge node, in case the caller needs additional wiring.

thesis.workflows.full_pipeline._core.apply_preproc_override(config, override)[source]#

Return a config with preprocess overrides applied.

Used by backend variants that must structurally disable a preprocess feature (e.g. the MRtrix3 variant forces run_bedpostx=False so BedpostX never runs and the bedpostx_done gate field is never created).

Parameters:

config (PipelineConfig) – The original pipeline config.
override (Optional[Mapping[str, Any]]) – Mapping of PreprocessConfig field names to override values, or None for no-op.

Return type:

PipelineConfig

Returns:

A new config with the overrides merged in. config is unchanged.

full_pipeline workflow#

Full-pipeline composite meta-workflow.

Chains all four processing stages into a single Nipype meta-workflow:

preprocess — raw DWI/T1/T2 → HCP-compatible layout
registration — patient T1 brain → template space (ANTs or FireANTS)
tract_synthseg — tractography + SynthSeg (backend per tractography.method)
atlas_to_patient — warp cohort atlas maps into patient space

Execution order:

preprocess_wf
   ↓  (T1 brain image → registration moving_image)
registration_wf
   ↓  (transforms)                       ↓  (DWI inputs + T1 brain + reg)
atlas_to_patient_wf              entry_gate → tract_synthseg_wf
   (parallel)

thesis.workflows.full_pipeline.build_workflow(*, template, config, context)[source]

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.full_pipeline.verify_requirements(config, context, **_)[source]

Preflight checks for the unified full pipeline.

Delegates raw-input checks to the preprocess registered verifier (so it gains preprocess’s implicit @requires existence checks), then adds the backend-driven tool / config availability checks. Downstream stages consume runtime intermediates, so their file-existence checks are intentionally excluded (they would always be false positives).

Parameters:

config (PipelineConfig) – Validated pipeline configuration.
context (ProcessingContext) – Processing context.
_ (object)

Return type:

List[str]

Returns:

Deduplicated list of human-readable error strings.

Composite full-pipeline meta-workflow (backend-parameterized).

Chains preprocess → registration → tract_synthseg → atlas_to_patient → tract_similarity in one Nipype graph, wiring stages only through their inputnode / outputnode contracts (plus the pre-existing entry_gate / exit_gate anchors on transform / tract_similarity). No node-name introspection of nested sub-workflows.

config.tractography.method selects the tractography backend via a BackendDescriptor; the unified tract_synthseg meta-workflow reads the same config value to build the matching backend:

probtrackx2 / fsl → hcp backend (BedpostX enabled)
mrtrix3 / tckgen → mrtrix3 backend (BedpostX disabled)

The backend-agnostic edges (preprocess→registration, registration→atlas, the preprocess→atlas anchor, the FireANTs transform fan-out into atlas) live in thesis.workflows.full_pipeline._core.

thesis.workflows.full_pipeline.workflow.build_workflow(*, template, config, context)[source]#

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.full_pipeline.workflow.verify_requirements(config, context, **_)[source]#

Preflight checks for the unified full pipeline.

Parameters:

config (PipelineConfig) – Validated pipeline configuration.
context (ProcessingContext) – Processing context.
_ (object)

Return type:

List[str]

Returns:

Deduplicated list of human-readable error strings.