feat: Add registration metadata to boldref-to-anat transforms (#3500)

Closes #3496.

Author: effigies

.git-blame-ignore-revs

@@ -1,10 +1,14 @@
-# 2024-02-05 - [email protected] - STY: ruff --fix + 1 ignore [git-blame-ignore-rev]
+# 2025-08-15 10:33:40 -0400 - [email protected] - sty: Use fmt:skip in workflows.bold.outputs [ignore-rev]
+f97f3439a3897346e961bb0039fc01ac9df3c2ea
+# 2024-11-03 09:52:44 -0500 - [email protected] - STY: ruff [ignore-rev]
+729b5b923599bc80d9d2de6d8fe0e957d4337cab
+# 2024-02-05 12:06:27 -0500 - [email protected] - STY: ruff --fix + 1 ignore [git-blame-ignore-rev]
 e7dc59fbc7df88dfabbff154f4cc3d24721b6b4f
-# 2024-01-16 - [email protected] - STY: ruff --fix --unsafe-fixes (with cleanup) [git-blame-ignore-rev]
+# 2024-01-16 13:47:18 -0500 - [email protected] - STY: ruff --fix --unsafe-fixes (with cleanup) [git-blame-ignore-rev]
 66734bd0164d1dae3cf299fa9d9d682c22eeda66
-# 2024-01-16 - [email protected] - STY: ruff format and ruff --fix [git-blame-ignore-rev]
+# 2024-01-16 13:33:25 -0500 - [email protected] - STY: ruff format and ruff --fix [git-blame-ignore-rev]
 311686eb329d3594732429f7c3d50d212b8dc519
-# 2023-02-02 - [email protected] - STY: black [git-blame-ignore-rev]
+# 2023-02-02 10:57:19 -0500 - [email protected] - STY: black [git-blame-ignore-rev]
 d3f380701b3953087475a18cf23c0fb388f7aed6
 # 2022-09-22 - [email protected] - STY: black/isort the docker wrapper
 9976458388f369cba4b7d81359acc40b52f6621c

fmriprep/workflows/bold/fit.py

@@ -682,7 +682,10 @@ def init_bold_fit_wf(
             (regref_buffer, bold_reg_wf, [('boldref', 'inputnode.ref_bold_brain')]),
             # Incomplete sources
             (regref_buffer, ds_boldreg_wf, [('boldref', 'inputnode.source_files')]),
-            (bold_reg_wf, ds_boldreg_wf, [('outputnode.itk_bold_to_t1', 'inputnode.xform')]),
+            (bold_reg_wf, ds_boldreg_wf, [
+                ('outputnode.itk_bold_to_t1', 'inputnode.xform'),
+                ('outputnode.metadata', 'inputnode.metadata'),
+            ]),
             (ds_boldreg_wf, outputnode, [('outputnode.xform', 'boldref2anat_xfm')]),
             (bold_reg_wf, summary, [('outputnode.fallback', 'fallback')]),
         ])  # fmt:skip

fmriprep/workflows/bold/outputs.py

@@ -267,7 +267,6 @@ def init_func_fit_reports_wf(
         mem_gb=1,
     )
 
-    # fmt:off
     workflow.connect([
         (inputnode, ds_summary, [
             ('source_file', 'source_file'),
@@ -288,8 +287,7 @@ def init_func_fit_reports_wf(
             ('boldref2anat_xfm', 'transforms'),
         ]),
         (t1w_wm, boldref_wm, [('out', 'input_image')]),
-    ])
-    # fmt:on
+    ])  # fmt:skip
 
     # Reportlets follow the structure of init_bold_fit_wf stages
     # - SDC1:
@@ -424,15 +422,13 @@ def init_func_fit_reports_wf(
         name='ds_epi_t1_report',
     )
 
-    # fmt:off
     workflow.connect([
         (inputnode, epi_t1_report, [('coreg_boldref', 'after')]),
         (t1w_boldref, epi_t1_report, [('output_image', 'before')]),
         (boldref_wm, epi_t1_report, [('output_image', 'wm_seg')]),
         (inputnode, ds_epi_t1_report, [('source_file', 'source_file')]),
         (epi_t1_report, ds_epi_t1_report, [('out_report', 'in_file')]),
-    ])
-    # fmt:on
+    ])  # fmt:skip
 
     return workflow
 
@@ -473,15 +469,13 @@ def init_ds_boldref_wf(
         run_without_submitting=True,
     )
 
-    # fmt:off
     workflow.connect([
         (inputnode, sources, [('source_files', 'in1')]),
         (inputnode, ds_boldref, [('boldref', 'in_file'),
                                  ('source_files', 'source_file')]),
         (sources, ds_boldref, [('out', 'Sources')]),
         (ds_boldref, outputnode, [('out_file', 'boldref')]),
-    ])
-    # fmt:on
+    ])  # fmt:skip
 
     return workflow
 
@@ -546,7 +540,7 @@ def init_ds_registration_wf(
     workflow = pe.Workflow(name=name)
 
     inputnode = pe.Node(
-        niu.IdentityInterface(fields=['source_files', 'xform']),
+        niu.IdentityInterface(fields=['source_files', 'xform', 'metadata']),
         name='inputnode',
     )
     outputnode = pe.Node(niu.IdentityInterface(fields=['xform']), name='outputnode')
@@ -574,15 +568,16 @@ def init_ds_registration_wf(
         mem_gb=DEFAULT_MEMORY_MIN_GB,
     )
 
-    # fmt:off
     workflow.connect([
         (inputnode, sources, [('source_files', 'in1')]),
-        (inputnode, ds_xform, [('xform', 'in_file'),
-                               ('source_files', 'source_file')]),
+        (inputnode, ds_xform, [
+            ('xform', 'in_file'),
+            ('source_files', 'source_file'),
+            ('metadata', 'meta_dict'),
+        ]),
         (sources, ds_xform, [('out', 'Sources')]),
         (ds_xform, outputnode, [('out_file', 'xform')]),
-    ])
-    # fmt:on
+    ])  # fmt:skip
 
     return workflow
 
@@ -624,15 +619,13 @@ def init_ds_hmc_wf(
         run_without_submitting=True,
     )
 
-    # fmt:off
     workflow.connect([
         (inputnode, sources, [('source_files', 'in1')]),
         (inputnode, ds_xforms, [('xforms', 'in_file'),
                                 ('source_files', 'source_file')]),
         (sources, ds_xforms, [('out', 'Sources')]),
         (ds_xforms, outputnode, [('out_file', 'xforms')]),
-    ])
-    # fmt:on
+    ])  # fmt:skip
 
     return workflow
 
@@ -1010,15 +1003,13 @@ def init_bold_preproc_report_wf(
         mem_gb=DEFAULT_MEMORY_MIN_GB,
         run_without_submitting=True,
     )
-    # fmt:off
     workflow.connect([
         (inputnode, ds_report_bold, [('name_source', 'source_file')]),
         (inputnode, pre_tsnr, [('in_pre', 'in_file')]),
         (inputnode, pos_tsnr, [('in_post', 'in_file')]),
         (pre_tsnr, bold_rpt, [('stddev_file', 'before')]),
         (pos_tsnr, bold_rpt, [('stddev_file', 'after')]),
         (bold_rpt, ds_report_bold, [('out_report', 'in_file')]),
-    ])
-    # fmt:on
+    ])  # fmt:skip
 
     return workflow

fmriprep/workflows/bold/registration.py

@@ -128,6 +128,8 @@ def init_bold_reg_wf(
         Affine transform from T1 space to BOLD space (ITK format)
     fallback
         Boolean indicating whether BBR was rejected (mri_coreg registration returned)
+    metadata
+        Output metadata from the registration workflow
 
     See Also
     --------
@@ -154,7 +156,7 @@ def init_bold_reg_wf(
     )
 
     outputnode = pe.Node(
-        niu.IdentityInterface(fields=['itk_bold_to_t1', 'itk_t1_to_bold', 'fallback']),
+        niu.IdentityInterface(fields=['itk_bold_to_t1', 'itk_t1_to_bold', 'fallback', 'metadata']),
         name='outputnode',
     )
 
@@ -188,6 +190,7 @@ def init_bold_reg_wf(
             ('outputnode.itk_bold_to_t1', 'itk_bold_to_t1'),
             ('outputnode.itk_t1_to_bold', 'itk_t1_to_bold'),
             ('outputnode.fallback', 'fallback'),
+            ('outputnode.metadata', 'metadata'),
         ]),
     ])  # fmt:skip
 
@@ -268,11 +271,14 @@ def init_bbreg_wf(
         Affine transform from T1 space to BOLD space (ITK format)
     fallback
         Boolean indicating whether BBR was rejected (mri_coreg registration returned)
+    metadata
+        Output metadata from the registration workflow
 
     """
     from nipype.interfaces.freesurfer import BBRegister
     from niworkflows.engine.workflows import LiterateWorkflow as Workflow
     from niworkflows.interfaces.nitransforms import ConcatenateXFMs
+    from niworkflows.interfaces.utility import DictMerge
 
     from fmriprep.interfaces.patches import FreeSurferSource, MRICoreg
 
@@ -309,7 +315,7 @@ def init_bbreg_wf(
         name='inputnode',
     )
     outputnode = pe.Node(
-        niu.IdentityInterface(['itk_bold_to_t1', 'itk_t1_to_bold', 'fallback']),
+        niu.IdentityInterface(['itk_bold_to_t1', 'itk_t1_to_bold', 'fallback', 'metadata']),
         name='outputnode',
     )
 
@@ -341,6 +347,8 @@ def init_bbreg_wf(
             dof=bold2anat_dof,
             contrast_type='t2',
             out_lta_file=True,
+            # Bug in nipype prevents using init_cost_file=True
+            init_cost_file='bbregister.initcost',
         ),
         name='bbregister',
         mem_gb=12,
@@ -357,6 +365,12 @@ def init_bbreg_wf(
     merge_ltas = pe.Node(niu.Merge(2), name='merge_ltas', run_without_submitting=True)
     concat_xfm = pe.Node(ConcatenateXFMs(inverse=True), name='concat_xfm')
 
+    # Set up GeneratedBy metadata and add a merge node for cost, if available
+    gen_by = pe.Node(niu.Merge(2), run_without_submitting=True, name='gen_by')
+    select_gen = pe.Node(niu.Select(index=0), run_without_submitting=True, name='select_gen')
+    metadata = pe.Node(niu.Merge(2), run_without_submitting=True, name='metadata')
+    merge_meta = pe.Node(DictMerge(), run_without_submitting=True, name='merge_meta')
+
     workflow.connect([
         (inputnode, merge_ltas, [('fsnative2t1w_xfm', 'in2')]),
         # Wire up the co-registration alternatives
@@ -365,10 +379,20 @@ def init_bbreg_wf(
         (merge_ltas, concat_xfm, [('out', 'in_xfms')]),
         (concat_xfm, outputnode, [('out_xfm', 'itk_bold_to_t1')]),
         (concat_xfm, outputnode, [('out_inv', 'itk_t1_to_bold')]),
+        # Wire up the metadata alternatives
+        (gen_by, select_gen, [('out', 'inlist')]),
+        (select_gen, metadata, [('out', 'in1')]),
+        (metadata, merge_meta, [('out', 'in_dicts')]),
+        (merge_meta, outputnode, [('out_dict', 'metadata')]),
     ])  # fmt:skip
 
     # Do not initialize with header, use mri_coreg
     if bold2anat_init != 'header':
+        gen_by.inputs.in2 = {
+            'GeneratedBy': [
+                {'Name': 'mri_coreg', 'Version': mri_coreg.interface.version or '<unknown>'}
+            ]
+        }
         workflow.connect([
             (inputnode, mri_coreg, [('subjects_dir', 'subjects_dir'),
                                     ('subject_id', 'subject_id'),
@@ -400,6 +424,26 @@ def init_bbreg_wf(
         (bbregister, transforms, [('out_lta_file', 'in1')]),
     ])  # fmt:skip
 
+    gen_by.inputs.in1 = {
+        'GeneratedBy': [
+            {'Name': 'bbregister', 'Version': bbregister.interface.version or '<unknown>'}
+        ]
+    }
+
+    costs = pe.Node(niu.Merge(2), run_without_submitting=True, name='costs')
+    select_cost = pe.Node(niu.Select(index=0), run_without_submitting=True, name='select_cost')
+    read_cost = pe.Node(niu.Function(function=_read_cost), name='read_cost')
+
+    workflow.connect([
+        (bbregister, costs, [
+            ('min_cost_file', 'in1'),
+            ('init_cost_file', 'in2'),
+        ]),
+        (costs, select_cost, [('out', 'inlist')]),
+        (select_cost, read_cost, [('out', 'cost_file')]),
+        (read_cost, metadata, [('out', 'in2')]),
+    ])  # fmt:skip
+
     # Short-circuit workflow building, use boundary-based registration
     if use_bbr is True:
         outputnode.inputs.fallback = False
@@ -413,6 +457,8 @@ def init_bbreg_wf(
         (transforms, compare_transforms, [('out', 'lta_list')]),
         (compare_transforms, outputnode, [('out', 'fallback')]),
         (compare_transforms, select_transform, [('out', 'index')]),
+        (compare_transforms, select_gen, [('out', 'index')]),
+        (compare_transforms, select_cost, [('out', 'index')]),
     ])  # fmt:skip
 
     return workflow
@@ -493,6 +539,8 @@ def init_fsl_bbr_wf(
         Affine transform from T1 space to BOLD space (ITK format)
     fallback
         Boolean indicating whether BBR was rejected (rigid FLIRT registration returned)
+    metadata
+        Output metadata from the registration workflow
 
     """
     from nipype.interfaces.freesurfer import MRICoreg
@@ -532,7 +580,7 @@ def init_fsl_bbr_wf(
         name='inputnode',
     )
     outputnode = pe.Node(
-        niu.IdentityInterface(['itk_bold_to_t1', 'itk_t1_to_bold', 'fallback']),
+        niu.IdentityInterface(['itk_bold_to_t1', 'itk_t1_to_bold', 'fallback', 'metadata']),
         name='outputnode',
     )
 
@@ -549,6 +597,9 @@ def init_fsl_bbr_wf(
             'T2w intermediate for FSL is not implemented, registering with T1w instead.'
         )
 
+    metadata = pe.Node(niu.Merge(2), run_without_submitting=True, name='metadata')
+    select_meta = pe.Node(niu.Select(index=0), run_without_submitting=True, name='select_meta')
+
     # Mask T1w_preproc with T1w_mask to make T1w_brain
     mask_t1w_brain = pe.Node(ApplyMask(), name='mask_t1w_brain')
 
@@ -565,6 +616,12 @@ def init_fsl_bbr_wf(
         mem_gb=DEFAULT_MEMORY_MIN_GB,
     )
 
+    metadata.inputs.in2 = {
+        'GeneratedBy': [
+            {'Name': 'mri_coreg', 'Version': mri_coreg.interface.version or '<unknown>'}
+        ]
+    }
+
     workflow.connect([
         (inputnode, mask_t1w_brain, [
             ('t1w_preproc', 'in_file'),
@@ -578,6 +635,9 @@ def init_fsl_bbr_wf(
             ('out_xfm', 'itk_bold_to_t1'),
             ('out_inv', 'itk_t1_to_bold'),
         ]),
+        # Wire up the metadata alternatives
+        (metadata, select_meta, [('out', 'inlist')]),
+        (select_meta, outputnode, [('out', 'metadata')]),
     ])  # fmt:skip
 
     # Short-circuit workflow building, use rigid registration
@@ -604,6 +664,10 @@ def init_fsl_bbr_wf(
         LOGGER.warning('FSLDIR unset - using packaged BBR schedule')
         flt_bbr.inputs.schedule = data.load('flirtsch/bbr.sch')
 
+    metadata.inputs.in1 = {
+        'GeneratedBy': [{'Name': 'flirt', 'Version': flt_bbr.interface.version or '<unknown>'}]
+    }
+
     workflow.connect([
         (inputnode, wm_mask, [('t1w_dseg', 'in_seg')]),
         (inputnode, flt_bbr, [('in_file', 'in_file')]),
@@ -658,6 +722,8 @@ def init_fsl_bbr_wf(
         (transforms, select_transform, [('out', 'inlist')]),
         (compare_transforms, select_transform, [('out', 'index')]),
         (select_transform, xfm2itk, [('out', 'in_xfm')]),
+        # Select metadata
+        (compare_transforms, select_meta, [('out', 'index')]),
     ])  # fmt:skip
 
     return workflow
@@ -749,3 +815,10 @@ def _conditional_downsampling(in_file, in_mask, zoom_th=4.0):
     nb.Nifti1Image(newmaskdata, newmask.affine, hdr).to_filename(out_mask)
 
     return str(out_file), str(out_mask)
+
+
+def _read_cost(cost_file) -> dict[str, float]:
+    """Read a cost from a file."""
+    # Cost file contains mincost, WM intensity, Ctx intensity, Pct Contrast
+    with open(cost_file) as fobj:
+        return {'FinalCost': float(fobj.read().split()[0])}