Skip to content

Commit

Permalink
DOC: Update workflow graph generators
Browse files Browse the repository at this point in the history
  • Loading branch information
@effigies
effigies committed Nov 14, 2023
1 parent 5cdcde7 commit 3991846
Show file tree
Hide file tree
Showing 2 changed files with 72 additions and 42 deletions.
110 changes: 70 additions & 40 deletions docs/workflows.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand All @@ -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

Expand Down Expand Up @@ -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
Expand All @@ -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,
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand Down
4 changes: 2 additions & 2 deletions fmriprep/workflows/bold/resampling.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 3991846

Please sign in to comment.