Clean up intramodal template workflows and add boilerplate text (#1095)

* Remove unused workflows.

Remove init_qsiprep_intramodal_template_wf, nonlinear_alignment_iteration, and init_nonlinear_alignment_wf from qsiprep.workflows.dwi.intramodal_template.

If we ever decide to enable these, we can pull them from the history.

* Remove duplicate _list_squeeze function.

* Remove unused mem_gb arg from init_intramodal_template_wf.

* Restructure intramodal template section.

There were unnecessary if statements, separation of workflow connections, etc.

* Reorder parameters.

* Add boilerplate for intramodal template.

* Run ruff.

* Use consistent connection format.

* Fix mistake and clean up init_b0_hmc_wf.

* Fix comment.

* Work on review.

* more informative boilerplate

---------

Co-authored-by: mattcieslak <mattcieslak@gmail.com>

Author: tsalo

qsiprep/cli/parser.py

@@ -669,10 +669,15 @@ def _bids_filter(value, parser):
         action='store',
         default=0,
         type=int,
-        help='Number of iterations for finding the midpoint image '
-        'from the b0 templates from all groups. Has no effect if there '
-        'is only one group. If 0, all b0 templates are directly registered '
-        'to the t1w image.',
+        help=(
+            'Number of iterations for finding the midpoint image '
+            'from the b0 templates from all DWI runs and sessions. '
+            'Has no effect if there is only one group. '
+            'If 0, all b0 templates are directly registered to the t1w image. '
+            'Enabling the intramodal template method when there are multiple runs/sessions '
+            'results in a single DWI reference image, which makes it possible to '
+            'directly compare AC-PC-space preprocessed DWI data across groups.'
+        ),
     )
     g_coreg.add_argument(
         '--intramodal-template-transform',

qsiprep/data/reports-spec.yml

@@ -30,9 +30,9 @@ sections:
     subtitle: Spatial normalization of the anatomical reference
 
   - bids: {datatype: figures, desc: intramodalcoreg, suffix: [T1w, T2w]}
-    caption: Coregistration between the intramodal DWI template to the anatomical reference image.
+    caption: Coregistration of the intramodal DWI template to the anatomical reference image.
     static: false
-    subtitle: Coregistration of the Intramodal to anatomical templates
+    subtitle: Coregistration of the intramodal to anatomical templates
 
 - name: <em>B<sub>0</sub></em> field mapping
   ordering: session,acquisition,run,fmapid
@@ -239,7 +239,7 @@ sections:
     caption: |
       b=0 reference image warped to the across-scan/session intramodal template.
     static: false
-    subtitle: Alignment of dMRI to Intramodal Template
+    subtitle: Alignment of dMRI to intramodal template
 
   - bids: {datatype: figures, desc: acpc, suffix: dwi}
     caption: |

qsiprep/workflows/base.py

@@ -418,25 +418,34 @@ def init_single_subject_wf(subject_id: str, session_ids: list):
         else:
             make_intramodal_template = True
 
-    anat_source_file = fix_multi_source_name(
-        subject_data[info_modality],
-        include_session=config.workflow.subject_anatomical_reference == 'sessionwise',
-        anatomical_contrast=config.workflow.anat_modality,
-    )
-    intramodal_template_wf = init_intramodal_template_wf(
-        t1w_source_file=anat_source_file,
-        inputs_list=sorted(outputs_to_files.keys()),
-        transform=config.workflow.intramodal_template_transform,
-        num_iterations=config.workflow.intramodal_template_iters or 2,
-        name='intramodal_template_wf',
-    )
-    # TemplateQC and the per-group orig->intramodal transform export exist only
-    # for linear templates: mvtc2 exposes no per-input aligned images, and its
-    # per-group transform is an [affine, warp] pair that does not fit a
-    # single-file .mat sink.
-    intramodal_linear = config.workflow.intramodal_template_transform in ('Rigid', 'Affine')
-
     if make_intramodal_template:
+        anat_source_file = fix_multi_source_name(
+            subject_data[info_modality],
+            include_session=config.workflow.subject_anatomical_reference == 'sessionwise',
+            anatomical_contrast=config.workflow.anat_modality,
+        )
+
+        intramodal_template_wf = init_intramodal_template_wf(
+            inputs_list=sorted(outputs_to_files.keys()),
+            t1w_source_file=anat_source_file,
+            transform=config.workflow.intramodal_template_transform,
+            num_iterations=config.workflow.intramodal_template_iters or 2,
+            name='intramodal_template_wf',
+        )
+        workflow.connect([
+            (anat_preproc_wf, intramodal_template_wf, [
+                ('outputnode.t1_preproc', 'inputnode.t1_preproc'),
+                ('outputnode.t1_brain', 'inputnode.t1_brain'),
+                ('outputnode.t1_mask', 'inputnode.t1_mask'),
+                ('outputnode.t1_seg', 'inputnode.t1_seg'),
+                ('outputnode.t1_aseg', 'inputnode.t1_aseg'),
+                ('outputnode.t1_aparc', 'inputnode.t1_aparc'),
+                ('outputnode.t1_2_mni_forward_transform', 'inputnode.t1_2_mni_forward_transform'),
+                ('outputnode.t1_2_mni_reverse_transform', 'inputnode.t1_2_mni_reverse_transform'),
+                ('outputnode.dwi_sampling_grid', 'inputnode.dwi_sampling_grid'),
+            ]),
+        ])  # fmt:skip
+
         ds_intramodal_template = pe.Node(
             DerivativesDataSink(
                 source_file=anat_source_file,
@@ -451,6 +460,15 @@ def init_single_subject_wf(subject_id: str, session_ids: list):
             name='ds_intramodal_template',
             run_without_submitting=True,
         )
+        workflow.connect([
+            (intramodal_template_wf, ds_intramodal_template, [
+                # The ACPC-resampled template, NOT outputnode.intramodal_template:
+                # that one is in the template's own midpoint space, and tagging
+                # it space-ACPC would mislabel it.
+                ('outputnode.intramodal_template_acpc', 'in_file'),
+            ]),
+        ])  # fmt:skip
+
         # Without this the intramodal space is a dead end: nothing can be mapped
         # into or out of it after the fact.
         ds_intramodal_to_acpc = pe.Node(
@@ -466,6 +484,17 @@ def init_single_subject_wf(subject_id: str, session_ids: list):
             name='ds_intramodal_to_acpc',
             run_without_submitting=True,
         )
+        workflow.connect([
+            (intramodal_template_wf, ds_intramodal_to_acpc, [
+                ('outputnode.intramodal_template_to_t1_affine', 'in_file'),
+            ]),
+        ])  # fmt:skip
+
+        # TemplateQC and the per-group orig->intramodal transform export exist only
+        # for linear templates: mvtc2 exposes no per-input aligned images, and its
+        # per-group transform is an [affine, warp] pair that does not fit a
+        # single-file .mat sink.
+        intramodal_linear = config.workflow.intramodal_template_transform in ('Rigid', 'Affine')
         if intramodal_linear:
             ds_template_qc = pe.Node(
                 DerivativesDataSink(
@@ -479,6 +508,12 @@ def init_single_subject_wf(subject_id: str, session_ids: list):
                 name='ds_template_qc',
                 run_without_submitting=True,
             )
+            workflow.connect([
+                (intramodal_template_wf, ds_template_qc, [
+                    ('outputnode.template_qc_file', 'in_file'),
+                ]),
+            ])  # fmt:skip
+
             ds_template_agreement = pe.Node(
                 DerivativesDataSink(
                     source_file=anat_source_file,
@@ -494,44 +529,11 @@ def init_single_subject_wf(subject_id: str, session_ids: list):
                 run_without_submitting=True,
             )
             workflow.connect([
-                (intramodal_template_wf, ds_template_qc, [
-                    ('outputnode.template_qc_file', 'in_file'),
-                ]),
                 (intramodal_template_wf, ds_template_agreement, [
                     ('outputnode.template_agreement_map', 'in_file'),
                 ]),
             ])  # fmt:skip
 
-        workflow.connect([
-            (intramodal_template_wf, ds_intramodal_to_acpc, [
-                ('outputnode.intramodal_template_to_t1_affine', 'in_file'),
-            ]),
-        ])  # fmt:skip
-
-        workflow.connect([
-            (intramodal_template_wf, ds_intramodal_template, [
-                # The ACPC-resampled template, NOT outputnode.intramodal_template:
-                # that one is in the template's own midpoint space, and tagging
-                # it space-ACPC would mislabel it.
-                ('outputnode.intramodal_template_acpc', 'in_file'),
-            ]),
-        ])  # fmt:skip
-
-    if make_intramodal_template:
-        workflow.connect([
-            (anat_preproc_wf, intramodal_template_wf, [
-                ('outputnode.t1_preproc', 'inputnode.t1_preproc'),
-                ('outputnode.t1_brain', 'inputnode.t1_brain'),
-                ('outputnode.t1_mask', 'inputnode.t1_mask'),
-                ('outputnode.t1_seg', 'inputnode.t1_seg'),
-                ('outputnode.t1_aseg', 'inputnode.t1_aseg'),
-                ('outputnode.t1_aparc', 'inputnode.t1_aparc'),
-                ('outputnode.t1_2_mni_forward_transform', 'inputnode.t1_2_mni_forward_transform'),
-                ('outputnode.t1_2_mni_reverse_transform', 'inputnode.t1_2_mni_reverse_transform'),
-                ('outputnode.dwi_sampling_grid', 'inputnode.dwi_sampling_grid'),
-            ]),
-        ])  # fmt:skip
-
     # create a processing pipeline for the dwis in each session
     for output_fname, dwi_info in outputs_to_files.items():
         source_file = get_source_file(dwi_info['dwi_series'], output_fname, suffix='_dwi')
@@ -600,28 +602,6 @@ def init_single_subject_wf(subject_id: str, session_ids: list):
         if make_intramodal_template:
             input_name = f'inputnode.{output_wfname}_b0_template'
             output_name = f'outputnode.{output_wfname}_transform'
-            if intramodal_linear:
-                # Per-group hop into the template space. Paired with
-                # from-intramodal_to-ACPC above, this closes the round trip:
-                # BIDS b=0 -> intramodal -> ACPC -> MNI, and back.
-                ds_orig_to_intramodal = pe.Node(
-                    DerivativesDataSink(
-                        source_file=source_file,
-                        base_directory=config.execution.output_dir,
-                        datatype='anat',
-                        mode='image',
-                        extension='.mat',
-                        **{'from': 'orig', 'to': 'intramodal'},
-                        suffix='xfm',
-                    ),
-                    name=f'ds_orig_to_intramodal_{output_wfname}',
-                    run_without_submitting=True,
-                )
-                workflow.connect([
-                    (intramodal_template_wf, ds_orig_to_intramodal, [
-                        (output_name, 'in_file'),
-                    ]),
-                ])  # fmt:skip
 
             workflow.connect([
                 (dwi_preproc_wf, intramodal_template_wf, [
@@ -645,6 +625,27 @@ def init_single_subject_wf(subject_id: str, session_ids: list):
                 ]),
             ])  # fmt:skip
 
+            if intramodal_linear:
+                # Per-group hop into the template space. Paired with
+                # from-intramodal_to-ACPC above, this closes the round trip:
+                # BIDS b=0 -> intramodal -> ACPC -> MNI, and back.
+                ds_orig_to_intramodal = pe.Node(
+                    DerivativesDataSink(
+                        source_file=source_file,
+                        base_directory=config.execution.output_dir,
+                        datatype='anat',
+                        mode='image',
+                        extension='.mat',
+                        **{'from': 'orig', 'to': 'intramodal'},
+                        suffix='xfm',
+                    ),
+                    name=f'ds_orig_to_intramodal_{output_wfname}',
+                    run_without_submitting=True,
+                )
+                workflow.connect([
+                    (intramodal_template_wf, ds_orig_to_intramodal, [(output_name, 'in_file')]),
+                ])  # fmt:skip
+
         if merging_distortion_groups:
             image_name = f'inputnode.{output_wfname}_image'
             bval_name = f'inputnode.{output_wfname}_bval'