registration

Subworkflow to perform registration between a moving and a fixed image (e.g. T1 -> DWI). It requires as input at least a moving (ch_image) and a reference (ch_ref) image to properly perform registration.

Output transformations curated for images for use with the REGISTRATION_ANTSAPPLYTRANSFORMS module are available under the names forward_image_transform and backward_image_transform. The same lists are also available for tractograms (forward_tractogram_transform and backward_tractogram_transform). However, to use the REGISTRATION_TRACTOGRAM module, you have to use the backward_affine and backward_warp channels provided by this subworkflow.

Registration suites:
- EasyReg (ML): params.run_easyreg = true

module: REGISTRATION_EASYREG

Run freesurfer EasyReg any-to-any modality registration.

NOTE: Outputs a combined warp field only, no affine transformations are available. CANNOT BE LINKED WITH THE BUNDLE_SEG SUBWORKFLOW.

- Synthmorph (ML): params.run_synthmorph = true

module: REGISTRATION_SYNTHMORPH

Run SynthMorph any-to-any modality registration. By default, the algorithm is configured to run a chain of affin+deformable transformations, making it suitable for use with most modules and subworkflows like BUNDLE_SEG.

NOTE: the output affine transformation file is in .lta format and needs to be converted to .mat to be used with ANTs using the REGISTRATION_CONVERT module.

- ANTs (SyN+SyN Quick): params.run_easyreg = false && params.run_synthmorph = false

module: REGISTRATION_ANTS or REGISTRATION_ANATTODWI

Run ANTs registration using antsRegistrationSyN.sh (quick version also available).

NOTE : Transformation to DWI space is available. To trigger it, supply a metric file (ch_metric) in DWI space (e.g. FA map) in addition to the moving (ch_image) and reference (ch_ref) images.

Keywords : Registration, Transformation, DWI, Anatomical

Components : registration/anattodwi, registration/ants, registration/convert, registration/easyreg, registration/synthmorph, utils_options

Inputs

	Type	Description	Mandatory	Pattern
ch_fixed_image	file	The input channel containing the fixed image files. If performing registration to DWI space, this is the reference image (e.g. b0 image). Structure : `tuple val(meta), path(fixed_image)` meta [map] Metadata map. fixed_image [file] Fixed image file.	True	`*.\{nii,nii.gz\}`
ch_moving_image	file	Input channel containing the moving image files. If performing registration to DWI space, this is the anatomical image to be registered. Structure : `tuple val(meta), path(image)` meta [map] Metadata map. image [file] Moving image file.	True	`*.\{nii,nii.gz\}`
ch_metric	file	FOR USE WITH REGISTRATION TO DWI SPACE ONLY. The input channel containing the metric files, typically a FA map. Structure : `tuple val(meta), path(metric)` meta [map] Metadata map. metric [file] Metric image file (e.g., FA map).	False	`*.\{nii,nii.gz\}`
ch_fixed_mask	file	FOR USE WITH ANTS SYN REGISTRATION ONLY. The input channel containing the mask file in fixed image space. Structure : `tuple val(meta), path(mask)` meta [map] Metadata map. mask [file] Fixed image mask file.	False	`*.\{nii,nii.gz\}`
ch_segmentation	file	FOR USE WITH SYNTHMORPH REGISTRATION ONLY. The input channel containing the SynthSeg v2 (non-robust) segmentation + parcellation in fixed image space (reference in Easyreg naming convention) image.	False	`*.\{nii,nii.gz\}`
ch_moving_segmentation	file	FOR USE WITH SYNTHMORPH REGISTRATION ONLY. The input channel containing the SynthSeg v2 (non-robust) segmentation + parcellation in moving image space (floating in Easyreg naming convention) image.	False	`*.\{nii,nii.gz\}`
options	map	Map of options for the registration subworkflow. run_easyreg (boolean) [Default: False] Run EasyReg for registration. If false, SynthMorph will be used if `run_synthmorph` is true, and ANTs SyN will be used if `run_synthmorph` is false. run_synthmorph (boolean) [Default: False] Run SynthMorph for registration. If false, EasyReg will be used if `run_easyreg` is true, and ANTs SyN will be used if `run_easyreg` is false.	False

Outputs

	Type	Description	Mandatory	Pattern
image_warped	file	Channel containing images warped in fixed space. Structure : `tuple val(meta), path(image)` meta [map] Metadata map. image [file] Warped image in fixed space.	True	`*.\{nii,nii.gz\}`
reference_warped	file	ONLY PROVIDED BY REGISTRATION_EASYREG. Channel containing the reference image warped in moving space. Structure : `tuple val(meta), path(image)` meta [map] Metadata map. image [file] Warped reference image in moving space.	False	`*.\{nii,nii.gz\}`
forward_affine	file	Channel containing the affine transformation matrix to fixed space. Structure : `tuple val(meta), path(forward_affine)` meta [map] Metadata map. forward_affine [file] Forward affine transformation file.	False	`__forward.\{lta,mat\}`
forward_warp	file	Channel containing the deformation field to fixed space. Structure : `tuple val(meta), path(forward_warp)` meta [map] Metadata map. forward_warp [file] Forward warp deformation field.	False	`__forward.\{nii,nii.gz\}`
backward_warp	file	Channel containing the deformation field to moving space. Structure : `tuple val(meta), path(backward_warp)` meta [map] Metadata map. backward_warp [file] Backward warp deformation field.	False	`__backward.\{nii,nii.gz\}`
backward_affine	file	Channel containing the affine transformation matrix to moving space. Structure : `tuple val(meta), path(backward_affine)` meta [map] Metadata map. backward_affine [file] Backward affine transformation file.	False	`__backward.\{lta,mat\}`
forward_image_transform	list	Channel containing the transformation tuples to warp images to fixed space, in the correct order for REGISTRATION_ANTSAPPLYTRANSFORMS. Structure : `tuple val(meta), path(transforms)` meta [map] Metadata map. transforms [file] List of forward transformation files.	True	`__forward.\{nii,nii.gz,mat,lta\}`
backward_image_transform	list	Channel containing the transformation tuples to warp images to moving space, in the correct order for REGISTRATION_ANTSAPPLYTRANSFORMS. Structure : `tuple val(meta), path(transforms)` meta [map] Metadata map. transforms [file] List of backward transformation files.	True	`__backward.\{nii,nii.gz,mat,lta\}`
forward_tractogram_transform	list	Channel containing the transformation tuples to warp tractograms to fixed space, in the correct order for REGISTRATION_TRANSFORMTRACTOGRAM. Structure : `tuple val(meta), path(transforms)` meta [map] Metadata map. transforms [file] List of transformation files for tractograms.	True	`__backward.\{nii,nii.gz,mat,lta\}`
backward_tractogram_transform	list	Channel containing the transformation tuples to warp tractograms to moving space, in the correct order for REGISTRATION_TRANSFORMTRACTOGRAM. Structure : `tuple val(meta), path(transforms)` meta [map] Metadata map. transforms [file] List of transformation files for tractograms.	True	`__forward.\{nii,nii.gz,mat,lta\}`
segmentation	file	ONLY PROVIDED BY REGISTRATION_SYNTHMORPH. Channel containing the SynthSeg v2 (non-robust) segmentation + parcellation in moving space (floating in Easyreg naming convention). Structure : `tuple val(meta), path(segmentation)` meta [map] Metadata map. segmentation [file] Segmentation image file.	False	`*.\{nii,nii.gz\}`
reference_segmentation	file	ONLY PROVIDED BY REGISTRATION_SYNTHMORPH. Channel containing the SynthSeg v2 (non-robust) segmentation + parcellation in fixed space (reference in Easyreg naming convention). Structure : `tuple val(meta), path(reference_segmentation)` meta [map] Metadata map. reference_segmentation [file] Reference segmentation image file.	False	`*.\{nii,nii.gz\}`
mqc	file	Channel containing the MultiQC report data for the registration. Structure : `tuple path(mqc)` mqc [file] MultiQC report file.	False	`mqc.`
versions	file	File containing software versions used. Structure : `tuple path(versions)` versions [file] Versions YAML file.	True	`versions.yml`

Authors

Last updated : 2026-03-17