Transform Workflow#

Apply pre-computed ANTs transforms to images defined under config.transforms.jobs. Supports template_to_patient and patient_to_template directions. Registered as transform (singular).

thesis.workflows.transforms.workflow#

Standalone ANTs transform application workflow.

Applies one or more transform jobs defined under transforms.jobs in configuration to a patient, warping images from template space into patient space (or the reverse direction).

Register as thesis run -w transform -p <patient_id> -c <config>.

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

Build a transform workflow from config.transforms.jobs.

Parameters:
Return type:

Workflow

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

Preflight checks: ANTs binary, jobs configured, transform/reference paths exist.

Parameters:
Return type:

List[str]

thesis.workflows.transforms.operations#

Common, reusable ANTs transform operations.

These are pure functions that can be called from any Nipype Function node or used directly. Every function that calls ANTs must be self-contained (no thesis logger) because Nipype Function nodes run in isolated subprocesses.

thesis.workflows.transforms.operations.apply_transform_ants(input_image, output_image, transforms, reference_image, interpolation='Linear', invert_transform_flags=None)[source]#

Apply a sequence of ANTs transforms to a single image.

Wraps ANTs ApplyTransforms and additionally copies qform → sform so that downstream FSL tools (which read sform) work correctly.

Parameters:

  • input_image (Path) – Source image path.

  • output_image (Path) – Destination path for the transformed image.

  • transforms (List[Path]) – Ordered list of transform paths (warp fields, affine mats, …).

  • reference_image (Path) – Reference image that defines the target voxel grid.

  • interpolation (str) – ANTs interpolation mode (e.g. "Linear", "NearestNeighbor", "BSpline").

  • invert_transform_flags (Optional[List[bool]]) – Optional per-transform inversion flags. Defaults to all False when not provided.

Return type:

Path

Returns:

Path to the written output image.

Raises:

  • FileNotFoundError – If input_image, any entry in transforms, or reference_image does not exist.

  • RuntimeError – If the underlying ANTs command fails.

thesis.workflows.transforms.operations.get_transform_type_from_paths(transform_paths)[source]#

Infer a transform type label from the names of transform files.

The label is used in output filenames to document which transforms were applied. Heuristics are based on common ANTs naming conventions.

Parameters:

transform_paths (List[Path]) – List of transform file paths to inspect.

Return type:

str

Returns:

One of "SyN", "Affine", "Rigid", or "transformed" (fallback when no recognisable pattern is found).

Example

>>> paths = [Path("sub_1Warp.nii.gz"), Path("sub_0GenericAffine.mat")]
>>> get_transform_type_from_paths(paths)
'SyN'
thesis.workflows.transforms.operations.build_output_filename(input_path, transform_type, direction, target_space)[source]#

Build a descriptive output filename that encodes transform provenance.

The result follows the pattern {stem}_{transform_type}_{direction}_in_{target_space}_space.nii.gz.

Parameters:

  • input_path (Path) – Original source image path; the stem is reused.

  • transform_type (str) – Short transform label, e.g. "SyN" or "Affine".

  • direction (str) – Transform direction, e.g. "template_to_patient".

  • target_space (str) – Short name of the target space, e.g. "patient" or "template".

Return type:

str

Returns:

Filename string (no directory component) such as "mean_left_SyN_template_to_patient_in_patient_space.nii.gz".

Example

>>> build_output_filename(
...     Path("cohort/atlas/mean_left.nii.gz"),
...     "SyN",
...     "template_to_patient",
...     "patient",
... )
'mean_left_SyN_template_to_patient_in_patient_space.nii.gz'
thesis.workflows.transforms.operations.validate_transform_inputs(input_files, transform_paths, reference_image)[source]#

Return a list of error messages for missing or invalid transform inputs.

An empty list means all files are present and the workflow can proceed.

Parameters:

  • input_files (List[Path]) – Source images that will be transformed.

  • transform_paths (List[Path]) – Warp fields / affine mats that will be applied.

  • reference_image (Path) – Reference image for resampling.

Return type:

List[str]

Returns:

List of human-readable error strings. Empty if everything is valid.

Example

>>> errors = validate_transform_inputs(
...     [Path("mean.nii.gz")],
...     [Path("warp.nii.gz"), Path("affine.mat")],
...     Path("ref.nii.gz"),
... )