fix: typos, more refs to BIDS specs, acronyms, etc.

Author: oesteban

docs/methods.rst

@@ -8,15 +8,27 @@ the problem of susceptibility distortions (SD) into two stages:
    discovered and preprocessed to estimate a map of B\ :sub:`0` non-uniformity in Hz (:math:`\Delta B_0`).
    The theory behind these distortions is well described in the literature [Jezzard1995]_ [Hutton2002]_ (Fig. 1).
    *SDCFlows* builds on freely-available software to implement three major strategies for estimating
-   :math:`\Delta B_0` (Eq. 1).
-   These strategies are described below, and implemented within :py:mod:`sdcflows.fit`\ .
+   :math:`\Delta B_0` (Eq. :math:`\eqref{eq:fieldmap-1}`).
+   These strategies are described below, and implemented within :py:mod:`sdcflows.workflows.fit`\ .
 
 #. **Application**:
    the B-Spline basis coefficients used to represent the estimated :math:`\Delta B_0` map mapped into the
-   target EPI scan to be corrected, and a displacement field in NIfTI format that is compatible with ANTs
-   is interpolated from the B-Spline basis.
-   The voxel location error along the PE will be proportional to :math:`\Delta B_0 \cdot T_\text{ro}`,
-   where :math:`T_\text{ro}` is the *total readout time* of the target EPI (Fig. 1).
+   target :abbr:`EPI (echo-planar imaging)` scan to be corrected, and a displacement field in NIfTI
+   format that is compatible with ANTs is interpolated from the B-Spline basis.
+   The voxel location error along the :abbr:`PE (phase-encoding)` will be proportional to :math:`\Delta B_0 \cdot T_\text{ro}`,
+   where :math:`T_\text{ro}` is the *total readout time* of the target :abbr:`EPI (echo-planar imaging)` (Fig. 1).
+   The implementation of these workflows is found in the submodule :py:mod:`sdcflows.workflows.apply`\ .
+
+.. figure:: _static/sdcflows-OHBM21-fig1.png
+   :width: 100%
+   :align: center
+
+   **Figure 1**. Susceptibility distortions in a nutshell
+
+.. admonition:: BIDS Specification
+
+    See the section `Echo-planar imaging and *B0* mapping
+    <https://bids-specification.readthedocs.io/en/latest/04-modality-specific-files/01-magnetic-resonance-imaging-data.html#echo-planar-imaging-and-b0-mapping>`__.
 
 Fieldmap estimation: theory and methods
 ---------------------------------------
@@ -29,29 +41,25 @@ can be derived from Eq. (2) of [Hutton2002]_:
     \label{eq:fieldmap-1}\tag{1}
 
 where
-:math:`\Delta_\text{PE} (i, j, k)` is the *voxel-shift map* (VSM) along the *PE* direction,
+:math:`\Delta_\text{PE} (i, j, k)` is the *voxel-shift map* (VSM) along the :abbr:`PE (phase-encoding)` direction,
 :math:`\gamma` is the gyromagnetic ratio of the H proton in Hz/T
 (:math:`\gamma = 42.576 \cdot 10^6 \, \text{Hz} \cdot \text{T}^\text{-1}`),
 :math:`\Delta B_0 (i, j, k)` is the *fieldmap variation* in T (Tesla), and
-:math:`T_\text{ro}` is the readout time of one slice of the EPI dataset
+:math:`T_\text{ro}` is the readout time of one slice of the :abbr:`EPI (echo-planar imaging)` dataset
 we want to correct for distortions.
 
 Let :math:`V` represent the *fieldmap* in Hz (or equivalently,
 *voxel-shift-velocity map*, as Hz are equivalent to voxels/s), with
 :math:`V(i,j,k) = \gamma \cdot \Delta B_0 (i, j, k)`, then, introducing
 the voxel zoom along the phase-encoding direction, :math:`s_\text{PE}`,
 we obtain the nonzero component of the associated displacements field
-:math:`\Delta D_\text{PE} (i, j, k)` that unwarps the target EPI dataset:
+:math:`\Delta D_\text{PE} (i, j, k)` that unwarps the target :abbr:`EPI (echo-planar imaging)` dataset:
 
 .. math::
 
     \Delta D_\text{PE} (i, j, k) = V(i, j, k) \cdot T_\text{ro} \cdot s_\text{PE}.
     \label{eq:fieldmap-2}\tag{2}
 
-.. image:: _static/sdcflows-OHBM21-fig1.png
-   :width: 100%
-   :align: center
-
 .. _sdc_direct_b0 :
 
 Direct B0 mapping sequences
@@ -84,7 +92,7 @@ Phase-difference B0 estimation
 
 The fieldmap variation in T, :math:`\Delta B_0 (i, j, k)`, that is necessary to obtain
 :math:`\Delta_\text{PE} (i, j, k)` in Eq. :math:`\eqref{eq:fieldmap-1}` can be
-calculated from two subsequient :abbr:`GRE (Gradient-Recalled Echo)` echoes,
+calculated from two subsequent :abbr:`GRE (Gradient-Recalled Echo)` echoes,
 via eq. (1) of [Hutton2002]_:
 
 .. math::
@@ -117,11 +125,11 @@ continuously smooth with its neighbors (*phase-unwrapping*, [Jenkinson2003]_).
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 .. admonition:: BIDS Specification
 
-    See `this section of the BIDS specification
-    <https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/01-magnetic-resonance-imaging-data.html#case-4-multiple-phase-encoded-directions-pepolar>`__.
+    See the section `Types of fieldmaps - Case 4: Multiple phase encoded directions ("pepolar")
+    <https://bids-specification.readthedocs.io/en/latest/04-modality-specific-files/01-magnetic-resonance-imaging-data.html#case-4-multiple-phase-encoded-directions-pepolar>`__.
 
 Alternatively, it is possible to estimate the field by exploiting the symmetry of the
-distortion when the PE polarity is reversed.
+distortion when the :abbr:`PE (phase-encoding)` polarity is reversed.
 *SDCFlows* integrates two implementations based on FSL ``topup`` [Andersson2003]_,
 and AFNI ``3dQwarp`` [Cox1997]_.
 By default, FSL ``topup`` will be used.
@@ -149,16 +157,18 @@ The implementation is a variation on those developed in [Huntenburg2014]_ and
 [Wang2017]_.
 
 The process is divided in two steps.
-First, the two images to be aligned (anatomical and one or more EPI sources) are prepared for
-registration, including a linear pre-alignment of both, calculation of a 3D EPI *reference* map,
+First, the two images to be aligned (anatomical and one or more :abbr:`EPI (echo-planar imaging)` sources) are prepared for
+registration, including a linear pre-alignment of both, calculation of a 3D :abbr:`EPI (echo-planar imaging)` *reference* map,
 intensity/histogram enhancement, and *deobliquing* (meaning, for images where the physical
 coordinates axes and the data array axes are not aligned, the physical coordinates are
 rotated to align with the data array).
-Such a preprocessing is implemented in :py:func:`init_syn_preprocessing_wf`.
-Second, the outputs of the preprocessing workflow are fed into :py:func:`init_syn_sdc_wf`,
+Such a preprocessing is implemented in
+:py:func:`~sdcflows.workflows.fit.syn.init_syn_preprocessing_wf`.
+Second, the outputs of the preprocessing workflow are fed into
+:py:func:`~sdcflows.workflows.fit.syn.init_syn_sdc_wf`,
 which executes the nonlinear, SyN registration.
 To aid the *Mattes* mutual information cost function, the registration scheme is set up
-in *multi-channel* mode, and laplacian-filtered derivatives of both anatomical and EPI
+in *multi-channel* mode, and laplacian-filtered derivatives of both anatomical and :abbr:`EPI (echo-planar imaging)`
 reference are introduced as a second registration channel.
 The optimization gradients of the registration process are weighted, so that deformations
 effectively possible only along the :abbr:`PE (phase-encoding)` axis.
@@ -168,7 +178,7 @@ The anatomical image is used as *fixed image*, and therefore, the registration p
 estimates the transformation function from *unwarped* (anatomically *correct*) coordinates
 to *distorted* coordinates.
 If fed into ``antsApplyTransforms``, the resulting transform will effectively *unwarp* a distorted
-EPI given as input into its *unwarped* mapping.
+:abbr:`EPI (echo-planar imaging)` given as input into its *unwarped* mapping.
 The estimated transform is then converted into a :math:`B_0` fieldmap in Hz, which can be
 stored within the derivatives folder.
 
@@ -186,7 +196,7 @@ surfaces onto the distorted :abbr:`EPI (echo-planar imaging)` data [Esteban2016]
 
 Estimation tooling
 ~~~~~~~~~~~~~~~~~~
-The workflows provided by :py:mod:`sdcflows.fit` make use of several utilities.
+The workflows provided by :py:mod:`sdcflows.workflows.fit` make use of several utilities.
 The cornerstone of these tools is the fieldmap representation with B-Splines
 (:py:mod:`sdcflows.interfaces.bspline`).
 B-Splines are well-suited to plausibly smooth the fieldmap and provide a compact
@@ -198,7 +208,7 @@ updated and then the fieldmap reconstructed.
 
 Unwarping the distorted data
 ----------------------------
-:py:mod:`sdcflows.apply` contains workflows to project fieldmaps represented by B-Spline
+:py:mod:`sdcflows.workflows.apply` contains workflows to project fieldmaps represented by B-Spline
 basis into the space of the target :abbr:`EPI (echo-planar imaging)` data.
 
 Discovering fieldmaps in a BIDS dataset
@@ -208,11 +218,21 @@ To ease the implementation of higher-level pipelines integrating :abbr:`SDC (sus
 
 Explicit specification with ``B0FieldIdentifier``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. admonition:: BIDS Specification
+
+    See the section `Expressing the MR protocol intent for fieldmaps - Using *B0FieldIdentifier* metadata
+    <https://bids-specification.readthedocs.io/en/latest/04-modality-specific-files/01-magnetic-resonance-imaging-data.html#using-b0fieldidentifier-metadata>`__.
+
 If one or more ``B0FieldIdentifier``\ (s) are set within the input metadata (following BIDS' specifications),
 then corresponding estimators will be built from the available input data.
 
 Implicit specification with ``IntendedFor``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. admonition:: BIDS Specification
+
+    See the section `Expressing the MR protocol intent for fieldmaps - Using *IntendedFor* metadata
+    <https://bids-specification.readthedocs.io/en/latest/04-modality-specific-files/01-magnetic-resonance-imaging-data.html#using-intendedfor-metadata>`__.
+
 In the case no ``B0FieldIdentifier``\ (s) are defined, then *SDCFlows* will try to identify as many fieldmap
 estimators as possible within the dataset following a set of heuristics.
 Then, those estimators may be linked to target :abbr:`EPI (echo-planar imaging)` data by interpreting the
@@ -221,7 +241,7 @@ Then, those estimators may be linked to target :abbr:`EPI (echo-planar imaging)`
 Fieldmap-less by registration to a T1-weighted image
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 If none of the two previous options yielded any workable estimation strategy, and provided that
-the argument ``fmapless`` is set to ``True``, then :py:func:`sdcflows.utils.wrangler.find_estimators`
+the argument ``fmapless`` is set to ``True``, then :py:func:`~sdcflows.utils.wrangler.find_estimators`
 will attempt to find :abbr:`BOLD (blood-oxygen level-dependent)` or :abbr:`DWI (diffusion-weighted imaging)`
 instances within single sessions that are consistent in :abbr:`PE (phase-encoding)` direction and
 *total readout time*, assuming they have been acquired with the same shimming settings.
@@ -231,7 +251,7 @@ If one or more anatomical images are found, and if the search for candidate
 yields results, then corresponding fieldmap-less estimators are set up.
 
 It is possible to force the fieldmap-less estimation by passing ``force_fmapless=True`` to the
-:py:func:`sdcflows.utils.wrangler.find_estimators` utility.
+:py:func:`~sdcflows.utils.wrangler.find_estimators` utility.
 
 References
 ----------