DOC: Add benchmark page (#3312)

First pass, just translating what's in the OHBM abstract into RST. LMK
if you have comments on the overall presentation style.

Also fixes some warnings/errors during doc builds that weren't caught
before release.

Author: effigies

docs/benchmarks.rst

@@ -0,0 +1,86 @@
+.. include:: links.rst
+
+----------------------
+Performance benchmarks
+----------------------
+
+Datasets and commands
+---------------------
+
+Datasets
+~~~~~~~~
++------------+----------------------------------------------------------------------------------------+
+| Dataset    | Description                                                                            |
++============+========================================================================================+
+| A          | 6 T1w, 3 T2w, 2 PhaseDiff, 4 SE-BOLD (195 volumes / series; total 784), 4 sbref        |
++------------+----------------------------------------------------------------------------------------+
+| B          | 2 T1w, 6 PEPolar fieldmaps, 8 SE-BOLD (4274 volumes total)                             |
++------------+----------------------------------------------------------------------------------------+
+
+fMRIPrep versions and modes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+All commands took the form ``fmriprep sourcedata/raw . participant $OPTIONS``.
+The specific options for each version or mode are presented in the following table.
+
++------------+----------------------------------------------------------------------------------------+
+| Version /  | Options                                                                                |
+| Mode       |                                                                                        |
++============+========================================================================================+
+| 23.1.4     | ``--cifti-output --output-spaces MNI152NLin2009cAsym``                                 |
++------------+----------------------------------------------------------------------------------------+
+| 23.2.0a2 / | ``--level minimal --cifti-output --output-spaces MNI152NLin2009cAsym``                 |
+| fit        |                                                                                        |
++------------+----------------------------------------------------------------------------------------+
+| 23.2.0a2 / | ``--level full --cifti-output --output-spaces MNI152NLin2009cAsym``                    |
+| fit +      |                                                                                        |
+| transform  |                                                                                        |
++------------+----------------------------------------------------------------------------------------+
+
+Machine details
+~~~~~~~~~~~~~~~
+
+Tests were run on a desktop machine running no other significant tests.
+
+* Processor: Intel i9-10900 CPU @ 2.80GHz, 20-core
+* Memory: 64GiB
+* Storage: PC801 NVMe SK hynix 2TB
+* OS: Ubuntu 22.04
+* Environment: Docker images published to https://hub.docker.com/r/nipreps/fmriprep/
+
+Benchmarks
+----------
+
+Dataset A
+~~~~~~~~~
+
++------------+---------+---------+---------+---------+---------+
+| Version /  | Runtime | Scratch | Scratch | Output  | Output  |
+| Mode       |         | Size    | Files   | Size    | files   |
++============+=========+=========+=========+=========+=========+
+| 23.1.4     | 2h24m   | 54.8GB  | 36.8K   | 2.30GB  | 176     |
++------------+---------+---------+---------+---------+---------+
+| 23.2.0a2   | 1h35m   | 2.91GB  | 5.89K   | 602MB   | 128     |
+| / fit      |         |         |         |         |         |
++------------+---------+---------+---------+---------+---------+
+| 23.2.0a2   | 1h47m   | 19.8GB  | 10.0K   | 6.37GB  | 206     |
+| / fit +    |         |         |         |         |         |
+| transform  |         |         |         |         |         |
++------------+---------+---------+---------+---------+---------+
+
+Dataset B
+~~~~~~~~~
+
++------------+---------+---------+---------+---------+---------+
+| Version /  | Runtime | Scratch | Scratch | Output  | Output  |
+| Mode       |         | Size    | Files   | Size    | files   |
++============+=========+=========+=========+=========+=========+
+| 23.1.4     | 4h25m   | 121GB   | 157K    | 5.10GB  | 286     |
++------------+---------+---------+---------+---------+---------+
+| 23.2.0a2   | 1h29m   | 1.88GB  | 12.0K   | 543MB   | 206     |
+| / fit      |         |         |         |         |         |
++------------+---------+---------+---------+---------+---------+
+| 23.2.0a2   | 2h7m    | 56.5GB  | 19.8K   | 14.7GB  | 348     |
+| / fit +    |         |         |         |         |         |
+| transform  |         |         |         |         |         |
++------------+---------+---------+---------+---------+---------+

docs/index.rst

@@ -16,6 +16,7 @@ Contents
    usage
    workflows
    outputs
+   benchmarks
    spaces
    faq
    api

docs/workflows.rst

@@ -62,6 +62,13 @@ single reference template (see `Longitudinal processing`_).
 
     from niworkflows.utils.spaces import Reference, SpatialReferences
     from smriprep.workflows.anatomical import init_anat_preproc_wf
+    spaces=SpatialReferences([
+        ('MNI152Lin', {}),
+        ('fsaverage', {'density': '10k'}),
+        ('T1w', {}),
+        ('fsnative', {})
+    ])
+    spaces.checkpoint()
     wf = init_anat_preproc_wf(
         bids_root='.',
         freesurfer=True,
@@ -71,12 +78,7 @@ single reference template (see `Longitudinal processing`_).
         output_dir='.',
         skull_strip_mode='force',
         skull_strip_template=Reference('MNI152NLin2009cAsym'),
-        spaces=SpatialReferences([
-            ('MNI152Lin', {}),
-            ('fsaverage', {'density': '10k'}),
-            ('T1w', {}),
-            ('fsnative', {})
-        ]),
+        spaces=spaces,
         skull_strip_fixed_seed=False,
         t1w=['sub-01/anat/sub-01_T1w.nii.gz'],
         t2w=[],
@@ -267,9 +269,9 @@ packages, including FreeSurfer and the `Connectome Workbench`_.
     :simple_form: yes
 
     from smriprep.workflows.surfaces import init_surface_recon_wf
-    wf = init_surface_recon_wf(omp_nthreads=1,
-                               hires=True,
-                               precomputed={})
+    wf = init_surface_recon_wf(
+        omp_nthreads=1, hires=True, precomputed={}, fs_no_resume=False,
+    )
 
 See also *sMRIPrep*'s
 :py:func:`~smriprep.workflows.surfaces.init_surface_recon_wf`
@@ -401,6 +403,7 @@ Slice time correction
 
     from fmriprep.workflows.bold import init_bold_stc_wf
     wf = init_bold_stc_wf(
+        mem_gb={'filesize': 1},
         metadata={'RepetitionTime': 2.0,
                   'SliceTiming': [0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]},
     )
@@ -479,8 +482,9 @@ EPI to T1w registration
     wf = init_bbreg_wf(
         omp_nthreads=1,
         use_bbr=True,
-        bold2t1w_dof=9,
-        bold2t1w_init='register')
+        bold2anat_dof=9,
+        bold2anat_init='t2w',
+    )
 
 The alignment between the reference :abbr:`EPI (echo-planar imaging)` image
 of each run and the reconstructed subject using the gray/white matter boundary
@@ -510,7 +514,16 @@ Resampling BOLD runs onto standard spaces
     :simple_form: yes
 
     from fmriprep.workflows.bold.apply import init_bold_volumetric_resample_wf
-    wf = init_bold_volumetric_resample_wf(metadata={}, fieldmap_id='fmap')
+    wf = init_bold_volumetric_resample_wf(
+        metadata={
+            'RepetitionTime': 2.0,
+            'PhaseEncodingDirection': 'j-',
+            'TotalReadoutTime': 0.03
+        },
+        mem_gb={'resampled': 1},
+        jacobian=True,
+        fieldmap_id='fmap',
+    )
 
 This sub-workflow concatenates the transforms calculated upstream (see
 `Head-motion estimation`_, `Susceptibility Distortion Correction (SDC)`_ --if
@@ -564,7 +577,6 @@ HCP Grayordinates
 
     from fmriprep.workflows.bold.resampling import init_bold_fsLR_resampling_wf
     wf = init_bold_fsLR_resampling_wf(
-        estimate_goodvoxels=True,
         grayord_density='92k',
         omp_nthreads=1,
         mem_gb=1,

fmriprep/workflows/bold/apply.py

@@ -36,6 +36,8 @@ def init_bold_volumetric_resample_wf(
                 'PhaseEncodingDirection': 'j-',
                 'TotalReadoutTime': 0.03
             },
+            mem_gb={'resampled': 1},
+            jacobian=True,
             fieldmap_id='my_fieldmap',
         )
 

fmriprep/workflows/bold/registration.py

@@ -80,7 +80,7 @@ def init_bold_reg_wf(
                                   omp_nthreads=1,
                                   use_bbr=True,
                                   bold2anat_dof=9,
-                                  bold2anat_init='auto')
+                                  bold2anat_init='t2w')
 
     Parameters
     ----------

fmriprep/workflows/bold/stc.py

@@ -73,6 +73,7 @@ def init_bold_stc_wf(
 
             from fmriprep.workflows.bold import init_bold_stc_wf
             wf = init_bold_stc_wf(
+                mem_gb={'filesize': 1},
                 metadata={"RepetitionTime": 2.0,
                           "SliceTiming": [0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]},
                 )