Nipype Architecture Diagrams

This page visualizes the current Nipype integration as implemented in the codebase.

1. End-to-End Control Flow

thesis run
  -> resolve workflow entry
  -> load and merge config
  -> create ProcessingContext
  -> entry.verifier(config, context)   # @requires + @verify checks
  -> build_workflow(config, context)
  -> NipypeExecutor.execute(workflow)
  -> collect results
  -> render summary / progress / errors

2. Runtime Layers

+---------------------------------------------------------------+
| CLI + Config + Output                                         |
| thesis.cli, ConfigManager, ProcessingContext, OutputRenderer  |
+------------------------------+--------------------------------+
                               |
+------------------------------v--------------------------------+
| Workflow Factories                                            |
| workflows/*/workflow.py -> build_workflow(config, context)    |
+------------------------------+--------------------------------+
                               |
+------------------------------v--------------------------------+
| Nipype Execution                                              |
| Workflow / Node / MapNode / NipypeExecutor                    |
+------------------------------+--------------------------------+
                               |
+------------------------------v--------------------------------+
| External Tools                                                |
| FSL, ANTs, FreeSurfer / SynthSeg                              |
+---------------------------------------------------------------+

3. HCP Workflow Graph Shape

atlas source 1  -> extractor -> transformer? -> validator? -+
atlas source 2  -> extractor -> transformer? -> validator? -+-> roi_merger* -> probtrackx2
SynthSeg labels -> resampler -> extractor -> validator? -----+

Legend:

• ? = node created only when the config/source requires it (optional/conditional).

• * = fan-in node that reduces multiple ROI sources to one bundle.

Notes:

• Each atlas source can optionally reference a named transform.

• SynthSeg segmentation is resampled to the T1w grid before ROI extraction.

• Multiple ROI sources are reduced to one canonical ROI bundle before tractography.

4. HCP + SynthSeg Meta-Workflow

meta workflow
  +-- synthseg_wf
  |     -> synthseg node -> outputnode.segmentation
  |
  +-- hcp_wf
        -> inputnode.segmentation
        -> optional synthseg_seg_resampler?
        -> atlas/synthseg ROI extraction
        -> probtrackx2

connection (contract-to-contract):
  synthseg_wf.outputnode.<field>
    -> hcp_wf.inputnode.<field>

The meta-workflow wires the published outputnode / inputnode contract fields (from thesis.core.contracts), never a sub-workflow’s internal node names — see src/thesis/workflows/full_pipeline/_core.py for the worked reference.

Legend: ? = node created only when the config/source requires it (optional/conditional), as in diagram 3.

5. Progress Reporting

build_nipype_status_callback()
  -> node started / finished / failed
  -> EventBus emission
  -> OutputRenderer
  -> ProgressTracker / BatchProgress / ClickNodeProgress

This is why nested workflows still show one coherent node-level progress bar in the CLI.

6. Directory Layout

src/thesis/
  cli.py
  core/
    config/
    logging/
    nipype/
      executor.py
      adapters/
      interfaces/
    output/
  workflows/
    hcp/
    tract_synthseg/
    qc/
    synthseg/
    minimal.py

7. Config to Execution Flow

config/default.yaml
  -> config/hardware.yaml
  -> config/protocols/{protocol}.yaml
  -> config/patients/{patient_id}.yaml
  -> CLI overrides
  -> PipelineConfig
  -> workflow factory
  -> Nipype nodes and interfaces

8. Key Design Choice

The project intentionally builds Nipype graphs directly inside workflow modules. There is no separate workflow-builder abstraction that translates a higher-level DSL into Nipype. This keeps debugging straightforward and makes node wiring explicit.