REF: Generalize bvals and uptake value iterators into a single iterator

Generalize bvals and uptake value iterators into a single iterator that
is able to traverse the values in ascending or descending order
depending on whether it is provided a list of b-values (DWI) or uptake
values (PET).

Follow-up to commit a1310e6.

Author: jhlegarreta

src/nifreeze/utils/iterators.py

@@ -206,64 +206,54 @@ def _value_iterator(values: list, ascending: bool, round_decimals: int = 2) -> I
     return (index[1] for index in indexed_vals)
 
 
-def bvalue_iterator(*_, **kwargs) -> Iterator[int]:
-    """
-    Traverse the volumes in a DWI dataset by increasing b-value.
+def monotonic_value_iterator(*_, **kwargs) -> Iterator[int]:
+    candidates = [{key: kwargs[key]} for key in (BVALS_KWARG, UPTAKE_KWARG) if key in kwargs]
+    if not candidates:
+        raise TypeError(KWARG_ERROR_MSG.format(kwarg=f"{BVALS_KWARG} or {UPTAKE_KWARG}"))
 
-    Parameters
-    ----------
-    bvals : :obj:`list`
-        List of b-values corresponding to all orientations of the dataset.
-        Please note that ``bvals`` is a keyword argument and MUST be provided
-        to generate the volume sequence.
-
-    Yields
-    ------
-    :obj:`int`
-        The next index.
+    feature = next(iter(candidates[0]))
+    ascending = feature == BVALS_KWARG
+    values = kwargs.pop(feature)
 
-    Examples
-    --------
-    >>> list(bvalue_iterator(bvals=[0.0, 0.0, 1000.0, 1000.0, 700.0, 700.0, 2000.0, 2000.0, 0.0]))
-    [0, 1, 8, 4, 5, 2, 3, 6, 7]
+    return _value_iterator(values, ascending=ascending, **kwargs)
 
-    """
-    bvals = kwargs.pop(BVALS_KWARG, None)
-    if bvals is None:
-        raise TypeError(KWARG_ERROR_MSG.format(kwarg=BVALS_KWARG))
-    return _value_iterator(bvals, ascending=True, **kwargs)
 
+monotonic_value_iterator.__doc__ = f"""
+Traverse the volumes by increasing b-value in a DWI dataset or by decreasing
+uptake value in a PET dataset.
 
-def uptake_iterator(*_, **kwargs) -> Iterator[int]:
-    """
-    Traverse the volumes in a PET dataset by decreasing uptake value.
+This function requires ``bvals`` or ``uptake`` be a keyword argument to generate
+the volume sequence. The b-values are assumed to all orientations in a DWI
+dataset, and uptake uptake values correspond to all volumes in a PET dataset.
 
-    This function assumes that each uptake value corresponds to a single volume,
-    and that this value summarizes the uptake of the volume in a meaningful way,
-    e.g. a mean value across the entire volume.
+It is assumed that each uptake value corresponds to a single volume, and that
+this value summarizes the uptake of the volume in a meaningful way, e.g. a mean
+value across the entire volume.
 
-    Parameters
-    ----------
-    uptake : :obj:`list`
-        List of uptake values corresponding to all volumes of the dataset.
-        Please note that ``uptake`` is a keyword argument and MUST be provided
-        to generate the volume sequence.
+Other Parameters
+----------------
+{SIZE_KEYS_DOC}
 
-    Yields
-    ------
-    :obj:`int`
-        The next index.
+Notes
+-----
+Only one of the above keyword arguments may be provided at a time. If ``size``
+is given, all other size-related keyword arguments will be ignored. If ``size``
+is not provided, the function will attempt to infer the number of volumes from
+the length or value of the provided keyword argument. If more than one such
+keyword is provided, a :exc:`ValueError` will be raised.
 
-    Examples
-    --------
-    >>> list(uptake_iterator(uptake=[-1.23, 1.06, 1.02, 1.38, -1.46, -1.12, -1.19, 1.24, 1.05]))
-    [3, 7, 1, 8, 2, 5, 6, 0, 4]
+Yields
+------
+:obj:`int`
+    The next index.
 
-    """
-    uptake = kwargs.pop(UPTAKE_KWARG, None)
-    if uptake is None:
-        raise TypeError(KWARG_ERROR_MSG.format(kwarg=UPTAKE_KWARG))
-    return _value_iterator(uptake, ascending=False, **kwargs)
+Examples
+--------
+>>> list(monotonic_value_iterator(bvals=[0.0, 0.0, 1000.0, 1000.0, 700.0, 700.0, 2000.0, 2000.0, 0.0]))
+[0, 1, 8, 4, 5, 2, 3, 6, 7]
+>>> list(monotonic_value_iterator(uptake=[-1.23, 1.06, 1.02, 1.38, -1.46, -1.12, -1.19, 1.24, 1.05]))
+[3, 7, 1, 8, 2, 5, 6, 0, 4]
+"""
 
 
 def centralsym_iterator(**kwargs) -> Iterator[int]:

test/test_iterators.py

@@ -31,11 +31,10 @@
     KWARG_ERROR_MSG,
     UPTAKE_KWARG,
     _value_iterator,
-    bvalue_iterator,
     centralsym_iterator,
     linear_iterator,
+    monotonic_value_iterator,
     random_iterator,
-    uptake_iterator,
 )
 
 
@@ -144,43 +143,34 @@ def test_centralsym_iterator(kwargs, expected):
     assert list(centralsym_iterator(**kwargs)) == expected
 
 
-def test_bvalue_iterator_error():
-    with pytest.raises(TypeError, match=KWARG_ERROR_MSG.format(kwarg=BVALS_KWARG)):
-        list(bvalue_iterator())
+def test_monotonic_value_iterator_error():
+    with pytest.raises(
+        TypeError, match=KWARG_ERROR_MSG.format(kwarg=f"{BVALS_KWARG} or {UPTAKE_KWARG}")
+    ):
+        list(monotonic_value_iterator())
 
-
-@pytest.mark.parametrize(
-    "bvals, expected",
-    [
-        ([0, 700, 1200], [0, 1, 2]),
-        ([0, 0, 1000, 700], [0, 1, 3, 2]),
-        ([0, 1000, 1500, 700, 2000], [0, 3, 1, 2, 4]),
-    ],
-)
-def test_bvalue_iterator(bvals, expected):
-    obtained = list(bvalue_iterator(bvals=bvals))
-    assert set(obtained) == set(range(len(bvals)))
-    # Should be ordered by increasing bvalue
-    sorted_bvals = [bvals[i] for i in obtained]
-    assert sorted_bvals == sorted(bvals)
-
-
-def test_uptake_iterator_error():
-    with pytest.raises(TypeError, match=KWARG_ERROR_MSG.format(kwarg=UPTAKE_KWARG)):
-        list(uptake_iterator())
+    with pytest.raises(
+        TypeError, match=KWARG_ERROR_MSG.format(kwarg=f"{BVALS_KWARG} or {UPTAKE_KWARG}")
+    ):
+        list(monotonic_value_iterator())
 
 
 @pytest.mark.parametrize(
-    "uptake, expected",
+    "feature, values, expected",
     [
-        ([0.3, 0.2, 0.1], [0, 1, 2]),
-        ([0.2, 0.1, 0.3], [2, 1, 0]),
-        ([-1.02, 1.16, -0.56, 0.43], [1, 3, 2, 0]),
+        ("bvals", [0, 700, 1200], [0, 1, 2]),
+        ("bvals", [0, 0, 1000, 700], [0, 1, 3, 2]),
+        ("bvals", [0, 1000, 1500, 700, 2000], [0, 3, 1, 2, 4]),
+        ("uptake", [0.3, 0.2, 0.1], [0, 1, 2]),
+        ("uptake", [0.2, 0.1, 0.3], [2, 1, 0]),
+        ("uptake", [-1.02, 1.16, -0.56, 0.43], [1, 3, 2, 0]),
     ],
 )
-def test_uptake_iterator_valid(uptake, expected):
-    obtained = list(uptake_iterator(uptake=uptake))
-    assert set(obtained) == set(range(len(uptake)))
-    # Should be ordered by decreasing uptake
-    sorted_uptake = [uptake[i] for i in obtained]
-    assert sorted_uptake == sorted(uptake, reverse=True)
+def test_monotonic_value_iterator(feature, values, expected):
+    obtained = list(monotonic_value_iterator(**{feature: values}))
+    assert set(obtained) == set(range(len(values)))
+    # If b-values, should be ordered by increasing value; if uptake values,
+    # should be ordered by decreasing uptake
+    sorted_vals = [values[i] for i in obtained]
+    reverse = True if feature == "uptake" else False
+    assert sorted_vals == sorted(values, reverse=reverse)