`transforms` — pre-computed ANTs transforms#

Schema: TransformsConfig in src/thesis/core/config/validators.py. Drives ROI/atlas warping in the hcp, atlas_to_patient, and transform workflows.

Top-level fields#

Field	Type	Default	Description
`base_dir`	`str \| None`	`None`	Optional base directory prepended to every relative path field on this section (and on each `atlas_transforms` entry) at validation time. Absolute paths are left untouched.
`patient_to_template`	`str`	`""`	Full path pattern for the patient→template warp field. Supports `{patient_id}` substitution.
`template_to_patient`	`str \| List[str]`	`""`	Full path pattern (or ordered transform chain) for template→patient transforms. Supports `{patient_id}` substitution.
`reference_image`	`str`	`""`	Patient-space reference image used as the resampling target for template→patient transforms. Supports `{patient_id}` substitution.
`template_reference_image`	`str`	`""`	Template-space reference image used as the resampling target for patient→template transforms.
`atlas_transforms`	`Dict[str, AtlasTransformConfig]`	`{}`	Named atlas-specific template→patient transform pairs. Reference by name from `tractography.atlas_sources[].transform`.
`jobs`	`List[TransformJobConfig]`	`[]`	Transform jobs executed by the standalone `transform` and `atlas_to_patient` workflows.

A model_validator walks patient_to_template, template_to_patient, reference_image, template_reference_image, and every atlas_transforms entry and prepends base_dir to relative paths.

`atlas_transforms[name]` — `AtlasTransformConfig`#

Field	Type	Default	Description
`template_to_patient`	`str \| List[str]`	`""`	Single path or ordered transform chain for this atlas.
`reference_image`	`str`	`""`	Patient-space reference image for this atlas.

`jobs[]` — `TransformJobConfig`#

Field	Type	Default	Constraints	Description
`name`	`str`	—	required	Unique job name (used in output filenames and Nipype node names).
`input_files`	`List[str]`	`[]`	—	Paths to the images to transform. Supports `{patient_id}` substitution.
`direction`	`str`	`"template_to_patient"`	one of `template_to_patient` / `patient_to_template`	Transform direction. `template_to_patient` uses `transforms.template_to_patient` + `transforms.reference_image`; `patient_to_template` uses `transforms.patient_to_template` + `transforms.template_reference_image`.
`interpolation`	`str`	`"Linear"`	ANTs interpolation names	ANTs interpolation method applied to every input image. Valid: `Linear`, `NearestNeighbor`, `BSpline`, `MultiLabel`, `Gaussian`, `CosineWindowedSinc`, `WelchWindowedSinc`, `HammingWindowedSinc`, `LanczosWindowedSinc`, `GenericLabel`.
`output_subdir`	`str`	`"transformed"`	—	Output subdirectory under the patient output directory.
`reference_image`	`str \| None`	`None`	—	Per-job reference image override. Useful for resampling a single job onto a different grid (e.g. DWI-space) without affecting other jobs. Supports `{patient_id}` substitution.
`from_registration`	`str \| None`	`None`	must match a resolved registration-job name	Drive this job from a registration job produced in the same run, instead of the static `transforms.` chains. Must match an explicit `registration.jobs` name or the implicit `patient_to_template` job. The job’s `direction` selects which chain is consumed: `template_to_patient` → the registration job’s reverse* chain; `patient_to_template` → its forward chain.

`from_registration` — consuming registration output directly#

When a transform job sets from_registration, its transform chain is read straight from the named registration job’s produced transforms (resolved via get_registration_job_transform_paths) — no transforms.template_to_patient / patient_to_template placeholder paths are needed. This is the mechanism full_pipeline uses to wire the patient→template registration into the atlas-warping jobs without the old placeholder dance.

A PipelineConfig model-validator checks every from_registration value against the resolved registration jobs (the implicit patient_to_template is always valid; an unknown name raises a ValidationError). The direction field then picks forward vs reverse:

direction: template_to_patient → registration job’s reverse chain (template → patient), used to warp atlas/template-space images into patient space.
direction: patient_to_template → registration job’s forward chain.

Still set a per-job reference_image (or rely on transforms.reference_image) to define the output grid — from_registration only supplies the transform chain, not the resampling target. Inside full_pipeline the meta-workflow may override reference_image at runtime with the live patient image; jobs that set their own reference_image (e.g. a DWI-space mask) keep it.

transforms:
  jobs:
    - name: atlas_main
      input_files:
        - data/masks/annotation_full.nii.gz
      direction: template_to_patient
      from_registration: patient_to_template   # consume the registration job's reverse chain
      interpolation: Linear
      output_subdir: atlas_in_patient_space
      reference_image: outputs/{patient_id}/registration/{patient_id}_T1_brain.nii.gz

Example#

transforms:
  base_dir: data/transforms
  patient_to_template: "{patient_id}/patient_to_template_warp.nii.gz"
  template_to_patient: "{patient_id}/template_to_patient_warp.nii.gz"
  reference_image: data/raw/{patient_id}/T1w/T1w_acpc_dc_restore_1.25.nii.gz
  template_reference_image: data/templates/template_T1w.nii.gz

  atlas_transforms:
    homba:
      template_to_patient:
        - "{patient_id}/homba_to_patient_warp.nii.gz"
        - "{patient_id}/homba_to_patient_affine.mat"
      reference_image: "{patient_id}/T1w_in_patient.nii.gz"

  jobs:
    - name: atlas_mean_to_patient
      input_files:
        - results/atlas/atlas_mean.nii.gz
      direction: template_to_patient
      interpolation: Linear
      output_subdir: atlas_in_patient_space

    - name: cohort_mask_to_dwi_space
      input_files:
        - results/atlas/cohort_core_mask.nii.gz
      direction: template_to_patient
      interpolation: NearestNeighbor
      output_subdir: atlas_in_patient_space
      reference_image: data/processed/{patient_id}/T1w/Diffusion/nodif_brain_mask.nii.gz

Notes#

The transform workflow registers under the short name transform (singular), even though the package directory is workflows/transforms/.
For atlas_to_patient, the entire job is driven by transforms.jobs; the workflow factory iterates over the list and creates one Nipype subgraph per job.
{patient_id} is the only substitution token supported in path patterns.

transforms — pre-computed ANTs transforms#