DOC: Update workflow graph generators

Author: effigies

docs/workflows.rst

@@ -37,7 +37,7 @@ is presented below:
      For example, ``anat_preproc_wf`` is a sub-workflow that is generated by the
      :func:`~smriprep.workflows.anatomical.init_anat_preproc_wf` (see below).
      Because each task and run of functional data is processed separately,
-     :func:`~fmriprep.workflows.bold.base.init_func_preproc_wf` names the
+     :func:`~fmriprep.workflows.bold.base.init_bold_wf` names the
      resulting workflows using input parameters, resulting in
      ``func_preproc_task_{task}_run_{run}_wf``.
    * Datasinks begin with ``ds_``, and save files to the output directory.
@@ -287,19 +287,41 @@ from the ``aseg.mgz`` file as described in
 
 BOLD preprocessing
 ------------------
-:py:func:`~fmriprep.workflows.bold.base.init_func_preproc_wf`
+*fMRIPrep* performs a series of steps to preprocess :abbr:`BOLD (blood-oxygen level-dependent)`
+data. Broadly, these are split into fit and transform stages.
+
+The following figures show the overall workflow graph and the ``bold_fit_wf``
+subgraph:
+
+:py:func:`~fmriprep.workflows.bold.base.init_bold_wf`
 
 .. workflow::
     :graph2use: orig
     :simple_form: yes
 
     from fmriprep.workflows.tests import mock_config
     from fmriprep import config
-    from fmriprep.workflows.bold.base import init_func_preproc_wf
+    from fmriprep.workflows.bold.base import init_bold_wf
     with mock_config():
         bold_file = config.execution.bids_dir / 'sub-01' / 'func' \
             / 'sub-01_task-mixedgamblestask_run-01_bold.nii.gz'
-        wf = init_func_preproc_wf(str(bold_file))
+        wf = init_bold_wf(bold_series=[str(bold_file)])
+
+.. _bold_fit:
+
+:py:func:`~fmriprep.workflows.bold.fit.init_bold_fit_wf`
+
+.. workflow::
+    :graph2use: orig
+    :simple_form: yes
+
+    from fmriprep.workflows.tests import mock_config
+    from fmriprep import config
+    from fmriprep.workflows.bold.fit import init_bold_fit_wf
+    with mock_config():
+        bold_file = config.execution.bids_dir / 'sub-01' / 'func' \
+            / 'sub-01_task-mixedgamblestask_run-01_bold.nii.gz'
+        wf = init_bold_fit_wf(bold_series=[str(bold_file)], fieldmap_id="fmap")
 
 Preprocessing of :abbr:`BOLD (blood-oxygen level-dependent)` files is
 split into multiple sub-workflows described below.
@@ -308,31 +330,31 @@ split into multiple sub-workflows described below.
 
 BOLD reference image estimation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-:py:func:`~niworkflows.func.util.init_bold_reference_wf`
+:py:func:`~fmriprep.workflows.bold.reference.init_raw_boldref_wf`
 
 .. workflow::
     :graph2use: orig
     :simple_form: yes
 
-    from niworkflows.func.util import init_bold_reference_wf
-    wf = init_bold_reference_wf(omp_nthreads=1)
+    from fmriprep.workflows.bold.reference import init_raw_boldref_wf
+    wf = init_raw_boldref_wf()
 
 This workflow estimates a reference image for a
-:abbr:`BOLD (blood-oxygen level-dependent)` series.
-If a single-band reference ("sbref") image associated with the BOLD series is
-available, then it is used directly.
-If not, a reference image is estimated from the BOLD series as follows:
+:abbr:`BOLD (blood-oxygen level-dependent)` series as follows:
 When T1-saturation effects ("dummy scans" or non-steady state volumes) are
 detected, they are averaged and used as reference due to their
 superior tissue contrast.
 Otherwise, a median of motion corrected subset of volumes is used.
 
-The reference image is then used to calculate a brain mask for the
-:abbr:`BOLD (blood-oxygen level-dependent)` signal using *NiWorkflows*'
-:py:func:`~niworkflows.func.util.init_enhance_and_skullstrip_bold_wf`.
-Further, the reference is fed to the :ref:`head-motion estimation
-workflow <bold_hmc>` and the :ref:`registration workflow to map
-BOLD series into the T1w image of the same subject <bold_reg>`.
+This reference is used for :ref:`head-motion estimation <bold_hmc>`.
+
+For the :ref:`registration workflow <bold_reg>`, the reference image is
+either the above described reference image or a single-band reference,
+if one is found in the input dataset.
+In either case, this image is contrast-enhanced and skull-stripped
+(see :py:func:`~niworkflows.func.util.init_enhance_and_skullstrip_bold_wf`).
+If fieldmaps are present, the skull-stripped reference is corrected
+prior to registration.
 
 .. figure:: _static/sub-01_task-balloonanalogrisktask_run-1_desc-rois_bold.svg
 
@@ -418,14 +440,19 @@ Theory, methods and references are found within the
 
 Pre-processed BOLD in native space
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-:py:func:`~fmriprep.workflows.bold.resampling.init_bold_preproc_trans_wf`
+:py:func:`~fmriprep.workflows.bold.fit.init_bold_native_wf`
 
 .. workflow::
     :graph2use: orig
     :simple_form: yes
 
-    from fmriprep.workflows.bold import init_bold_preproc_trans_wf
-    wf = init_bold_preproc_trans_wf(mem_gb=3, omp_nthreads=1)
+    from fmriprep.workflows.tests import mock_config
+    from fmriprep import config
+    from fmriprep.workflows.bold.fit import init_bold_native_wf
+    with mock_config():
+        bold_file = config.execution.bids_dir / 'sub-01' / 'func' \
+            / 'sub-01_task-mixedgamblestask_run-01_bold.nii.gz'
+        wf = init_bold_native_wf(bold_series=[str(bold_file)], fieldmap_id='fmap')
 
 A new *preproc* :abbr:`BOLD (blood-oxygen level-dependent)` series is generated
 from the slice-timing corrected or the original data (if
@@ -442,16 +469,14 @@ Interpolation uses a Lanczos kernel.
 
 EPI to T1w registration
 ~~~~~~~~~~~~~~~~~~~~~~~
-:py:func:`~fmriprep.workflows.bold.registration.init_bold_reg_wf`
+:py:func:`~fmriprep.workflows.bold.registration.init_bbreg_wf`
 
 .. workflow::
-    :graph2use: orig
+    :graph2use: hierarchical
     :simple_form: yes
 
-    from fmriprep.workflows.bold import init_bold_reg_wf
-    wf = init_bold_reg_wf(
-        freesurfer=True,
-        mem_gb=1,
+    from fmriprep.workflows.bold.registration import init_bbreg_wf
+    wf = init_bbreg_wf(
         omp_nthreads=1,
         use_bbr=True,
         bold2t1w_dof=9,
@@ -478,23 +503,14 @@ original, affine registration.
 
 Resampling BOLD runs onto standard spaces
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-:py:func:`~fmriprep.workflows.bold.resampling.init_bold_std_trans_wf`
+:py:func:`~fmriprep.workflows.bold.apply.init_bold_volumetric_resample_wf`
 
 .. workflow::
     :graph2use: colored
     :simple_form: yes
 
-    from niworkflows.utils.spaces import SpatialReferences
-    from fmriprep.workflows.bold import init_bold_std_trans_wf
-    wf = init_bold_std_trans_wf(
-        freesurfer=True,
-        mem_gb=3,
-        omp_nthreads=1,
-        spaces=SpatialReferences(
-            spaces=[('MNI152Lin', {}), ('MNIPediatricAsym', {'cohort': '6'})],
-            checkpoint=True),
-        multiecho=False,
-    )
+    from fmriprep.workflows.bold.apply import init_bold_volumetric_resample_wf
+    wf = init_bold_volumetric_resample_wf(metadata={}, fieldmap_id='fmap')
 
 This sub-workflow concatenates the transforms calculated upstream (see
 `Head-motion estimation`_, `Susceptibility Distortion Correction (SDC)`_ --if
@@ -523,7 +539,10 @@ EPI sampled to FreeSurfer surfaces
     wf = init_bold_surf_wf(
         mem_gb=1,
         surface_spaces=['fsnative', 'fsaverage5'],
-        medial_surface_nan=False)
+        medial_surface_nan=False,
+        metadata={},
+        output_dir='.',
+    )
 
 If FreeSurfer processing is enabled, the motion-corrected functional series
 (after single shot resampling to T1w space) is sampled to the
@@ -540,7 +559,7 @@ HCP Grayordinates
 :py:func:`~fmriprep.workflows.bold.resampling.init_bold_fsLR_resampling_wf`
 
 .. workflow::
-    :graph2use: colored
+    :graph2use: orig
     :simple_form: yes
 
     from fmriprep.workflows.bold.resampling import init_bold_fsLR_resampling_wf
@@ -595,6 +614,17 @@ T2*-driven echo combination
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 :py:func:`~fmriprep.workflows.bold.t2s.init_bold_t2s_wf`
 
+.. workflow::
+    :graph2use: colored
+    :simple_form: yes
+
+    from fmriprep.workflows.bold.t2s import init_bold_t2s_wf
+    wf = init_bold_t2s_wf(
+        echo_times=[0.015, 0.030, 0.045],
+        mem_gb=1,
+        omp_nthreads=1,
+    )
+
 If multi-echo :abbr:`BOLD (blood-oxygen level-dependent)` data is supplied,
 this workflow uses the `tedana`_ `T2* workflow`_ to generate an adaptive T2* map
 and optimally weighted combination of all supplied single echo time series.

fmriprep/workflows/bold/resampling.py

@@ -25,8 +25,6 @@
 ++++++++++++++++++++
 
 .. autofunction:: init_bold_surf_wf
-.. autofunction:: init_bold_std_trans_wf
-.. autofunction:: init_bold_preproc_trans_wf
 .. autofunction:: init_bold_fsLR_resampling_wf
 .. autofunction:: init_bold_grayords_wf
 .. autofunction:: init_goodvoxels_bold_mask_wf
@@ -75,6 +73,8 @@ def init_bold_surf_wf(
             wf = init_bold_surf_wf(mem_gb=0.1,
                                    surface_spaces=["fsnative", "fsaverage5"],
                                    medial_surface_nan=False,
+                                   metadata={},
+                                   output_dir='.',
                                    )
 
     Parameters