docs(pepolar): revise docstrings - close #18 [skip ci]

sdcflows/workflows/pepolar.py

@@ -53,26 +53,49 @@ def init_pepolar_unwarp_wf(omp_nthreads=1, matched_pe=False,
         wf = init_pepolar_unwarp_wf()
 
 
-    Inputs
+    **Parameters**:
 
-        in_reference
-            the baseline reference image (will define the reference PE direction)
-        in_reference_brain
-            the reference image skullstripped
+        matched_pe : bool
+            Whether the input ``fmaps_epi`` will contain images with matched
+            PE blips or not. Please use :func:`sdcflows.workflows.pepolar.check_pes`
+            to determine whether they exist or not.
+        name : str
+            Name for this workflow
+        omp_nthreads : int
+            Parallelize internal tasks across the number of CPUs given by this option.
+
+    **Inputs**:
+
+        fmaps_epi : list of tuple(pathlike, str)
+            The list of EPI images that will be used in PE-Polar correction, and
+            their corresponding ``PhaseEncodingDirection`` metadata.
+            The workflow will use the ``bold_pe_dir`` input to separate out those
+            EPI acquisitions with opposed PE blips and those with matched PE blips
+            (the latter could be none, and ``in_reference_brain`` would then be
+            used). The workflow raises a ``ValueError`` when no images with
+            opposed PE blips are found.
+        bold_pe_dir : str
+            The baseline PE direction.
+        in_reference : pathlike
+            The baseline reference image (must correspond to ``bold_pe_dir``).
+        in_reference_brain : pathlike
+            The reference image above, but skullstripped.
         in_mask : pathlike
-            (not used) a brain mask corresponding to ``in_reference``
+            Not used, present only for consistency across fieldmap estimation
+            workflows.
 
-    Outputs
 
-        out_reference
-            the ``in_reference`` after unwarping
-        out_reference_brain
-            the ``in_reference`` after unwarping and skullstripping
-        out_warp
-            the corresponding :abbr:`DFM (displacements field map)` compatible with
-            ANTs
-        out_mask
-            mask of the unwarped input file
+    **Outputs**:
+
+        out_reference : pathlike
+            The ``in_reference`` after unwarping
+        out_reference_brain : pathlike
+            The ``in_reference`` after unwarping and skullstripping
+        out_warp : pathlike
+            The corresponding :abbr:`DFM (displacements field map)` compatible with
+            ANTs.
+        out_mask : pathlike
+            Mask of the unwarped input file
 
     """
     workflow = Workflow(name=name)
@@ -161,6 +184,17 @@ def init_prepare_epi_wf(omp_nthreads, matched_pe=False,
         wf = init_prepare_epi_wf(omp_nthreads=8)
 
 
+    **Parameters**:
+
+        matched_pe : bool
+            Whether the input ``fmaps_epi`` will contain images with matched
+            PE blips or not. Please use :func:`sdcflows.workflows.pepolar.check_pes`
+            to determine whether they exist or not.
+        name : str
+            Name for this workflow
+        omp_nthreads : int
+            Parallelize internal tasks across the number of CPUs given by this option.
+
     **Inputs**:
 
         epi_pe : str
@@ -281,7 +315,8 @@ def _fix_hdr(in_file, newpath=None):
     return out_file
 
 
-def _check_pes(epi_fmaps, pe_dir):
+def check_pes(epi_fmaps, pe_dir):
+    """Check whether there are images with matched PE."""
     opposed_pe = False
     matched_pe = False
 

sdcflows/workflows/tests/test_pepolar.py

@@ -5,7 +5,7 @@
 from nipype.pipeline import engine as pe
 
 from ..pepolar import (
-    _check_pes, _split_epi_lists, init_prepare_epi_wf, init_pepolar_unwarp_wf
+    check_pes, _split_epi_lists, init_prepare_epi_wf, init_pepolar_unwarp_wf
 )
 
 
@@ -53,7 +53,7 @@ def test_prepare_epi_wf0(bids_layouts, tmpdir):
                          desc=None, extension=['.nii.gz', '.nii'])
 
     with pytest.raises(ValueError):
-        _check_pes([
+        check_pes([
             (im.path, im.get_metadata()['PhaseEncodingDirection'])
             for im in epidata], bold.get_metadata()['PhaseEncodingDirection'])
 
@@ -70,8 +70,8 @@ def test_prepare_epi_wf1(bids_layouts, tmpdir):
                          extension=['.nii.gz', '.nii'])[0]
     epidata = layout.get(suffix='epi', desc=None, extension=['.nii.gz', '.nii'])
 
-    matched_pe = _check_pes([(im.path, im.get_metadata()['PhaseEncodingDirection'])
-                             for im in epidata], bold.get_metadata()['PhaseEncodingDirection'])
+    matched_pe = check_pes([(im.path, im.get_metadata()['PhaseEncodingDirection'])
+                            for im in epidata], bold.get_metadata()['PhaseEncodingDirection'])
 
     assert matched_pe is True
 
@@ -95,8 +95,8 @@ def test_prepare_epi_wf2(bids_layouts, tmpdir):
     epidata = layout.get(suffix='epi', dir='RL', direction='RL',
                          desc=None, extension=['.nii.gz', '.nii'])
 
-    matched_pe = _check_pes([(im.path, im.get_metadata()['PhaseEncodingDirection'])
-                             for im in epidata], bold.get_metadata()['PhaseEncodingDirection'])
+    matched_pe = check_pes([(im.path, im.get_metadata()['PhaseEncodingDirection'])
+                            for im in epidata], bold.get_metadata()['PhaseEncodingDirection'])
 
     assert matched_pe is False
 
@@ -126,8 +126,8 @@ def test_pepolar_wf1(bids_layouts, output_path, dataset):
 
     epidata = layout.get(suffix='epi', desc=None, extension=['.nii.gz', '.nii'])
 
-    matched_pe = _check_pes([(im.path, im.get_metadata()['PhaseEncodingDirection'])
-                             for im in epidata], bold.get_metadata()['PhaseEncodingDirection'])
+    matched_pe = check_pes([(im.path, im.get_metadata()['PhaseEncodingDirection'])
+                            for im in epidata], bold.get_metadata()['PhaseEncodingDirection'])
 
     wf = init_pepolar_unwarp_wf(omp_nthreads=cpu_count(), matched_pe=matched_pe)
     wf.inputs.inputnode.fmaps_epi = [(im.path, im.get_metadata()['PhaseEncodingDirection'])