From 399184637ae534aabe58f2bfcc7468ca1266910b Mon Sep 17 00:00:00 2001 From: Chris Markiewicz Date: Tue, 14 Nov 2023 02:27:23 -0500 Subject: [PATCH] DOC: Update workflow graph generators --- docs/workflows.rst | 110 ++++++++++++++++---------- fmriprep/workflows/bold/resampling.py | 4 +- 2 files changed, 72 insertions(+), 42 deletions(-) diff --git a/docs/workflows.rst b/docs/workflows.rst index 12351d5cc..2f9549c99 100644 --- a/docs/workflows.rst +++ b/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,7 +287,13 @@ 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 @@ -295,11 +301,27 @@ BOLD preprocessing 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 ` and the :ref:`registration workflow to map -BOLD series into the T1w image of the same subject `. +This reference is used for :ref:`head-motion estimation `. + +For the :ref:`registration workflow `, 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. diff --git a/fmriprep/workflows/bold/resampling.py b/fmriprep/workflows/bold/resampling.py index 9629d6a04..b4a52d9e1 100644 --- a/fmriprep/workflows/bold/resampling.py +++ b/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