Merge pull request #141 from oesteban/fix/checking-target-epi-names

FIX: Correctly check *SDCFlows*' registry of ``IntendedFor`` files

Author: oesteban

dmriprep/config/reports-spec.yml

@@ -27,10 +27,30 @@ sections:
       overlaid on the participant's T1w template.
     subtitle: Surface reconstruction
 - name: Fieldmaps
-  ordering: session,run
+  ordering: session,run,fmapid
   reportlets:
+  - bids: {datatype: figures, desc: mapped, suffix: fieldmap}
+    caption: Inhomogeneities of the <em>B<sub>0</sub></em> field introduce (oftentimes severe) spatial distortions
+      along the phase-encoding direction of the image. Some scanners produce a <em>B<sub>0</sub></em>
+      mapping of the field, using Spiral Echo Imaging (SEI) or postprocessing a "phase-difference"
+      acquisition. The plot below shows an anatomical "magnitude" reference and the corresponding
+      fieldmap.
+    description: Hover over the panels with the mouse pointer to also visualize the intensity of the
+      field inhomogeneity in Hertz.
+    static: false
+    subtitle: "Susceptibility-derived Distortion Correction (SDC): field inhomogeneity estimation"
+  - bids: {datatype: figures, desc: phasediff, suffix: fieldmap}
+    caption: Inhomogeneities of the <em>B<sub>0</sub></em> field introduce (oftentimes severe) spatial distortions
+      along the phase-encoding direction of the image. A Gradient-Recalled Echo (GRE) scheme for the 
+      mapping of the <em>B<sub>0</sub></em> inhomogeneities by subtracting the phase maps obtained at
+      two subsequent echoes. The plot below shows an anatomical "magnitude" reference and the corresponding
+      fieldmap.
+    description: Hover over the panels with the mouse pointer to also visualize the intensity of the
+      field inhomogeneity in Hertz.
+    static: false
+    subtitle: "Susceptibility-derived Distortion Correction (SDC): field inhomogeneity estimation"
   - bids: {datatype: figures, desc: pepolar, suffix: fieldmap}
-    caption: Inhomogeneities of the *B0* field introduce (oftentimes severe) spatial distortions
+    caption: Inhomogeneities of the <em>B<sub>0</sub></em> field introduce (oftentimes severe) spatial distortions
       along the phase-encoding direction of the image. Utilizing two or more images with different
       phase-encoding polarities (PEPolar) or directions, it is possible to estimate the inhomogeneity
       of the field. The plot below shows a reference EPI (echo-planar imaging) volume generated
@@ -44,11 +64,16 @@ sections:
   reportlets:
   - bids: {datatype: figures, desc: validation, suffix: dwi}
   - bids: {datatype: figures, desc: brain, suffix: mask}
-    caption: Average b=0 that serves for reference in early preprocessing steps.
-    descriptions: The reference b=0 is obtained as the voxel-wise median across
-      all b=0 found in the dataset, after accounting for signal drift.
-      The red contour shows the brain mask calculated using this reference b=0.
-    subtitle: Reference b=0 and brain mask
+    caption: Average <em>b=0</em> that serves for reference in early preprocessing steps.
+    descriptions: The reference <em>b=0</em> is obtained as the voxel-wise median across
+      all <em>b=0</em> found in the dataset, after accounting for signal drift.
+      The red contour shows the brain mask calculated using this reference <em>b=0</em>.
+    subtitle: Reference <em>b=0</em> and brain mask
+  - bids: {datatype: figures, desc: sdc, suffix: dwi}
+    caption: Susceptibility distortions correction (SDC).
+    description: The reportlet shows a <em>b=0</em> reference <em>before</em> and <em>after</em> distortion correction.
+    static: false
+    subtitle: Unwarping of susceptibility distortions
   - bids: {datatype: figures, desc: coreg, suffix: dwi}
     caption: Diffusion-weighted data and anatomical data (EPI-space and T1w-space)
       were aligned with <code>mri_coreg</code> (FreeSurfer).

dmriprep/data/boilerplate.bib

@@ -45,12 +45,13 @@ @article{nipype1
 }
 
 @article{nipype2,
-    author = {Gorgolewski, Krzysztof J. and Esteban, Oscar and Markiewicz, Christopher J. and Ziegler, Erik and Ellis, David Gage and Notter, Michael Philipp and Jarecka, Dorota and Johnson, Hans and Burns, Christopher and Manhães-Savio, Alexandre and Hamalainen, Carlo and Yvernault, Benjamin and Salo, Taylor and Jordan, Kesshi and Goncalves, Mathias and Waskom, Michael and Clark, Daniel and Wong, Jason and Loney, Fred and Modat, Marc and Dewey, Blake E and Madison, Cindee and Visconti di Oleggio Castello, Matteo and Clark, Michael G. and Dayan, Michael and Clark, Dav and Keshavan, Anisha and Pinsard, Basile and Gramfort, Alexandre and Berleant, Shoshana and Nielson, Dylan M. and Bougacha, Salma and Varoquaux, Gael and Cipollini, Ben and Markello, Ross and Rokem, Ariel and Moloney, Brendan and Halchenko, Yaroslav O. and Wassermann , Demian and Hanke, Michael and Horea, Christian and Kaczmarzyk, Jakub and Gilles de Hollander and DuPre, Elizabeth and Gillman, Ashley and Mordom, David and Buchanan, Colin and Tungaraza, Rosalia and Pauli, Wolfgang M. and Iqbal, Shariq and Sikka, Sharad and Mancini, Matteo and Schwartz, Yannick and Malone, Ian B. and Dubois, Mathieu and Frohlich, Caroline and Welch, David and Forbes, Jessica and Kent, James and Watanabe, Aimi and Cumba, Chad and Huntenburg, Julia M. and Kastman, Erik and Nichols, B. Nolan and Eshaghi, Arman and Ginsburg, Daniel and Schaefer, Alexander and Acland, Benjamin and Giavasis, Steven and Kleesiek, Jens and Erickson, Drew and Küttner, René and Haselgrove, Christian and Correa, Carlos and Ghayoor, Ali and Liem, Franz and Millman, Jarrod and Haehn, Daniel and Lai, Jeff and Zhou, Dale and Blair, Ross and Glatard, Tristan and Renfro, Mandy and Liu, Siqi and Kahn, Ari E. and Pérez-García, Fernando and Triplett, William and Lampe, Leonie and Stadler, Jörg and Kong, Xiang-Zhen and Hallquist, Michael and Chetverikov, Andrey and Salvatore, John and Park, Anne and Poldrack, Russell and Craddock, R. Cameron and Inati, Souheil and Hinds, Oliver and Cooper, Gavin and Perkins, L. Nathan and Marina, Ana and Mattfeld, Aaron and Noel, Maxime and Lukas Snoek and Matsubara, K and Cheung, Brian and Rothmei, Simon and Urchs, Sebastian and Durnez, Joke and Mertz, Fred and Geisler, Daniel and Floren, Andrew and Gerhard, Stephan and Sharp, Paul and Molina-Romero, Miguel and Weinstein, Alejandro and Broderick, William and Saase, Victor and Andberg, Sami Kristian and Harms, Robbert and Schlamp, Kai and Arias, Jaime and Papadopoulos Orfanos, Dimitri and Tarbert, Claire and Tambini, Arielle and De La Vega, Alejandro and Nickson, Thomas and Brett, Matthew and Falkiewicz, Marcel and Podranski, Kornelius and Linkersdörfer, Janosch and Flandin, Guillaume and Ort, Eduard and Shachnev, Dmitry and McNamee, Daniel and Davison, Andrew and Varada, Jan and Schwabacher, Isaac and Pellman, John and Perez-Guevara, Martin and Khanuja, Ranjeet and Pannetier, Nicolas and McDermottroe, Conor and Ghosh, Satrajit},
-    title = {Nipype},
-    year = 2018,
+    author = {Esteban, Oscar and Markiewicz, Christopher J. and Burns, Christopher and Goncalves, Mathias and Jarecka, Dorota and Ziegler, Erik and Berleant, Shoshana and Ellis, David Gage and Pinsard, Basile and Madison, Cindee and Waskom, Michael and Notter, Michael Philipp and Clark, Daniel and Manhães-Savio, Alexandre and Clark, Dav and Jordan, Kesshi and Dayan, Michael and Halchenko, Yaroslav O. and Loney, Fred and Salo, Taylor and Dewey, Blake E and Johnson, Hans and Bougacha, Salma and Keshavan, Anisha and Yvernault, Benjamin and Hamalainen, Carlo and Christian, Horea and Ćirić, Rastko and Dubois, Mathieu and Joseph, Michael and Cipollini, Ben and Tilley II, Steven and Visconti di Oleggio Castello, Matteo and Wong, Jason and De La Vega, Alejandro and Kaczmarzyk, Jakub and Huntenburg, Julia M. and Clark, Michael G. and Benderoff, Erin and Erickson, Drew and Kent, James D. and Hanke, Michael and Giavasis, Steven and Moloney, Brendan and Nichols, B. Nolan and Tungaraza, Rosalia and Frohlich, Caroline and Wassermann, Demian and de Hollander, Gilles and Eshaghi, Arman and Millman, Jarrod and Mancini, Matteo and Nielson, Dylan M. and Varoquaux, Gael and Watanabe, Aimi and Mordom, David and Guillon, Jérémy and Koudoro, Serge and Chetverikov, Andrey and Rokem, Ariel and Acland, Benjamin and Forbes, Jessica and Markello, Ross and Gillman, Ashley and Kong, Xiang-Zhen and Geisler, Daniel and Salvatore, John and Gramfort, Alexandre and Doll, Anna and Buchanan, Colin and DuPre, Elizabeth and Liu, Siqi and Schaefer, Alexander and Kleesiek, Jens and Sikka, Sharad and Schwartz, Yannick and Lee, John A. and Mattfeld, Aaron and Richie-Halford, Adam and Liem, Franz and Perez-Guevara, Martin Felipe and Heinsfeld, Anibal Sólon and Haselgrove, Christian and Durnez, Joke and Lampe, Leonie and Poldrack, Russell and Glatard, Tristan and Tabas, Alejandro and Cumba, Chad and Pérez-García, Fernando and Blair, Ross and Iqbal, Shariq and Welch, David and Triplett, William and Ghayoor, Ali and Craddock, R. Cameron and Correa, Carlos and Papadopoulos Orfanos, Dimitri and Stadler, Jörg and Warner, Joshua and Sisk, Lucinda M. and Falkiewicz, Marcel and Sharp, Paul and Rothmei, Simon and Kim, Sin and Weinstein, Alejandro and Kahn, Ari E. and Kastman, Erik and Bottenhorn, Katherine and Grignard, Martin and Perkins, L. Nathan and Contier, Oliver and Zhou, Dale and Bielievtsov, Dmytro and Cooper, Gavin and Stojic, Hrvoje and Linkersdörfer, Janosch and Waller, Lea and Renfro, Mandy and Hinds, Oliver and Stanley, Olivia and Küttner, René and Pauli, Wolfgang M. and Glen, Daniel and Kimbler, Adam and Meyers, Benjamin and Tarbert, Claire and Ginsburg, Daniel and Haehn, Daniel and Margulies, Daniel S. and Ma, Feilong and Malone, Ian B. and Snoek, Lukas and Brett, Matthew and Cieslak, Matthew and Hallquist, Michael and Molina-Romero, Miguel and Bilgel, Murat and Lee, Nat and Inati, Souheil and Gerhard, Stephan and Mathotaarachchi, Sulantha and Saase, Victor and Van, Andrew and Steele, Christopher John and Ort, Eduard and Condamine, Eric and Lerma-Usabiaga, Garikoitz and Schwabacher, Isaac and Arias, Jaime and Lai, Jeff and Pellman, John and Huguet, Jordi and Junhao WEN and Leinweber, Katrin and Chawla, Kshitij and Weninger, Leon and Modat, Marc and Harms, Robbert and Andberg, Sami Kristian and Baratz, Zvi and Matsubara, K and González Orozco, Abel A. and Marina, Ana and Davison, Andrew and Floren, Andrew and Park, Anne and Cheung, Brian and McDermottroe, Conor and McNamee, Daniel and Shachnev, Dmitry and Flandin, Guillaume and Gonzalez, Ivan and Varada, Jan and Schlamp, Kai and Podranski, Kornelius and Huang, Lijie and Noel, Maxime and Crusoe, Michael R. and Pannetier, Nicolas and Khanuja, Ranjeet and Urchs, Sebastian and Nickson, Thomas and Huang, Lijie and Broderick, William and Tambini, Arielle and Mihai, Paul Glad and Gorgolewski, Krzysztof J. and Ghosh, Satrajit},
+    title = {Nipype: neuroimaging in {Python} - pipelines and interfaces},
     doi = {10.5281/zenodo.596855},
     publisher = {Zenodo},
-    journal = {Software}
+    journal = {Software},
+    year = 2020,
+    keywords = {neuroimaging, pipeline, workflow}
 }
 
 @article{n4,

dmriprep/workflows/base.py

@@ -253,6 +253,7 @@ def init_single_subject_wf(subject_id):
         spaces=spaces,
         t1w=subject_data["t1w"],
     )
+    anat_preproc_wf.__desc__ = f"\n\n{anat_preproc_wf.__desc__}"
 
     # fmt:off
     workflow.connect([
@@ -290,17 +291,16 @@ def init_single_subject_wf(subject_id):
 
     # Append the dMRI section to the existing anatomical excerpt
     # That way we do not need to stream down the number of DWI datasets
-    anat_preproc_wf.__postdesc__ = (
-        (anat_preproc_wf.__postdesc__ or "")
-        + f"""
+    anat_preproc_wf.__postdesc__ = f"""\
+{anat_preproc_wf.__postdesc__ or ''}
+
 Diffusion data preprocessing
 
 : For each of the {len(subject_data["dwi"])} DWI scans found per subject
  (across all sessions), the gradient table was vetted and converted into the *RASb*
 format (i.e., given in RAS+ scanner coordinates, normalized b-vectors and scaled b-values),
 and a *b=0* average for reference to the subsequent steps of preprocessing was calculated.
 """
-    )
 
     # SDC Step 0: Determine whether fieldmaps can/should be estimated
     fmap_estimators = None
@@ -360,6 +360,12 @@ def init_single_subject_wf(subject_id):
         output_dir=str(output_dir),
         subject=subject_id,
     )
+    fmap_wf.__desc__ = f"""
+*B<sub>0</sub>* fieldmap data preprocessing
+
+: A total of {len(fmap_estimators)} fieldmaps were found available within the input
+BIDS structure for this particular subject.
+"""
 
     # TODO: Requires nipreps/sdcflows#147
     for dwi_preproc_wf in dwi_preproc_list:

dmriprep/workflows/dwi/base.py

@@ -52,7 +52,6 @@ def init_dwi_preproc_wf(dwi_file, has_fieldmap=False):
     fmap_id
         The BIDS modality label of the fieldmap being used
 
-
     Outputs
     -------
     dwi_reference
@@ -81,13 +80,17 @@ def init_dwi_preproc_wf(dwi_file, has_fieldmap=False):
     )
 
     if has_fieldmap:
+        import re
         from sdcflows.fieldmaps import get_identifier
 
-        estimator_key = get_identifier(dwi_file)
+        dwi_rel = re.sub(
+            r"^sub-[a-zA-Z0-9]*/", "", str(dwi_file.relative_to(layout.root))
+        )
+        estimator_key = get_identifier(dwi_rel)
         if not estimator_key:
             has_fieldmap = False
             config.loggers.workflow.critical(
-                f"None of the available B0 fieldmaps are associated to <{dwi_file}>"
+                f"None of the available B0 fieldmaps are associated to <{dwi_rel}>"
             )
 
     # Build workflow
@@ -167,7 +170,8 @@ def init_dwi_preproc_wf(dwi_file, has_fieldmap=False):
 
         ds_report_reg = pe.Node(
             DerivativesDataSink(
-                base_directory=str(config.execution.output_dir), datatype="figures",
+                base_directory=str(config.execution.output_dir),
+                datatype="figures",
             ),
             name="ds_report_reg",
             run_without_submitting=True,
@@ -198,7 +202,10 @@ def _bold_reg_suffix(fallback):
         # fmt: on
 
     # REPORTING ############################################################
-    reportlets_wf = init_reportlets_wf(str(config.execution.output_dir))
+    reportlets_wf = init_reportlets_wf(
+        str(config.execution.output_dir),
+        sdc_report=has_fieldmap,
+    )
     # fmt: off
     workflow.connect([
         (inputnode, reportlets_wf, [("dwi_file", "inputnode.source_file")]),
@@ -221,14 +228,20 @@ def _bold_reg_suffix(fallback):
         # fmt: on
         return workflow
 
+    from niworkflows.interfaces import SimpleBeforeAfter
     from niworkflows.interfaces.utility import KeySelect
     from sdcflows.workflows.apply.registration import init_coeff2epi_wf
     from sdcflows.workflows.apply.correction import init_unwarp_wf
 
     coeff2epi_wf = init_coeff2epi_wf(
-        omp_nthreads=config.nipype.omp_nthreads, write_coeff=True
+        debug=config.execution.debug,
+        omp_nthreads=config.nipype.omp_nthreads,
+        write_coeff=True,
+    )
+    unwarp_wf = init_unwarp_wf(
+        debug=config.execution.debug,
+        omp_nthreads=config.nipype.omp_nthreads
     )
-    unwarp_wf = init_unwarp_wf(omp_nthreads=config.nipype.omp_nthreads)
     unwarp_wf.inputs.inputnode.metadata = layout.get_metadata(str(dwi_file))
 
     output_select = pe.Node(
@@ -243,6 +256,12 @@ def _bold_reg_suffix(fallback):
             f"'IntendedFor' <{dwi_file}>, using {estimator_key[0]}"
         )
 
+    sdc_report = pe.Node(
+        SimpleBeforeAfter(before_label="Distorted", after_label="Corrected",),
+        name="sdc_report",
+        mem_gb=0.1,
+    )
+
     # fmt: off
     workflow.connect([
         (inputnode, output_select, [("fmap", "fmap"),
@@ -260,7 +279,12 @@ def _bold_reg_suffix(fallback):
         (dwi_reference_wf, unwarp_wf, [("outputnode.ref_image", "inputnode.distorted")]),
         (coeff2epi_wf, unwarp_wf, [
             ("outputnode.fmap_coeff", "inputnode.fmap_coeff")]),
-        (unwarp_wf, outputnode, [("outputnode.corrected", "dwi_reference")]),
+        (dwi_reference_wf, sdc_report, [("outputnode.ref_image", "before")]),
+        (unwarp_wf, sdc_report, [("outputnode.corrected", "after"),
+                                 ("outputnode.corrected_mask", "wm_seg")]),
+        (sdc_report, reportlets_wf, [("out_report", "inputnode.sdc_report")]),
+        (unwarp_wf, outputnode, [("outputnode.corrected", "dwi_reference"),
+                                 ("outputnode.corrected_mask", "dwi_mask")]),
     ])
     # fmt: on
 

dmriprep/workflows/dwi/outputs.py

@@ -5,15 +5,15 @@
 from ...interfaces import DerivativesDataSink
 
 
-def init_reportlets_wf(output_dir, name="reportlets_wf"):
+def init_reportlets_wf(output_dir, sdc_report=False, name="reportlets_wf"):
     """Set up a battery of datasinks to store reports in the right location."""
     from niworkflows.interfaces.masks import SimpleShowMaskRPT
 
     workflow = Workflow(name=name)
 
     inputnode = pe.Node(
         niu.IdentityInterface(
-            fields=["source_file", "dwi_ref", "dwi_mask", "validation_report"]
+            fields=["source_file", "dwi_ref", "dwi_mask", "validation_report", "sdc_report"]
         ),
         name="inputnode",
     )
@@ -44,4 +44,18 @@ def init_reportlets_wf(output_dir, name="reportlets_wf"):
         (mask_reportlet, ds_report_mask, [("out_report", "in_file")]),
     ])
     # fmt:on
+    if sdc_report:
+        ds_report_sdc = pe.Node(
+            DerivativesDataSink(
+                base_directory=output_dir, desc="sdc", suffix="dwi", datatype="figures"
+            ),
+            name="ds_report_sdc",
+            run_without_submitting=True,
+        )
+        # fmt:off
+        workflow.connect([
+            (inputnode, ds_report_sdc, [("source_file", "source_file"),
+                                        ("sdc_report", "in_file")]),
+        ])
+        # fmt:on
     return workflow

setup.cfg

@@ -29,7 +29,7 @@ install_requires =
     numpy
     pybids >= 0.11.1
     pyyaml
-    sdcflows @ git+https://github.com/nipreps/sdcflows.git@9b5c167d81e7670ef2121151b2d59fe190c0167c
+    sdcflows @ git+https://github.com/nipreps/sdcflows.git@f0765424eaf171fc143a6c1d58a221051ee76926
     smriprep >= 0.8.0rc0 
     templateflow ~= 0.6
     toml