Rename flow.TransformBins to IterateBins. Add a keyword argument *sel…

…ect* to choose selected bins.

docs/source/flow.rst

@@ -53,9 +53,9 @@ Flow
 .. currentmodule:: lena.flow.split_into_bins
 .. autosummary::
 
+    IterateBins
     MapBins
     SplitIntoBins
-    TransformBins
     cell_to_string
     get_example_bin
 

lena/flow/__init__.py

@@ -10,7 +10,9 @@
 from .progress import Progress
 from .selectors import Not, Selector
 from .split_into_bins import (
-    SplitIntoBins, MapBins, TransformBins,
+    IterateBins,
+    MapBins,
+    SplitIntoBins,
     get_example_bin,
 )
 from .zip import Zip
@@ -44,7 +46,7 @@
     'RunIf',
     # split into bins
     'SplitIntoBins',
+    'IterateBins',
     'MapBins',
-    'TransformBins',
     'get_example_bin',
 ]

lena/flow/split_into_bins.py

@@ -121,10 +121,10 @@ def get_example_bin(struct):
         return bins
 
 
-class TransformBins(object):
-    """Transform bins into a flattened sequence."""
+class IterateBins(object):
+    """Iterate bins of histograms."""
 
-    def __init__(self, create_edges_str=None):
+    def __init__(self, create_edges_str=None, select=None):
         """*create_edges_str* is a callable, 
         which creates a string from bin's edges
         and coordinate names
@@ -133,8 +133,12 @@ def __init__(self, create_edges_str=None):
         where *var_context* is Variable context containing
         variable names (it can be a single
         :class:`.Variable` or :class:`.Combine`).
-        
-        By default, it is :func:`cell_to_string`.
+        By default it is :func:`.cell_to_string`.
+
+        *select* is a callable used to test bin contents.
+        By default, only those histograms are iterated where
+        bins contain histograms. Use *select* to choose other classes.
+        See :class:`.Selector` for examples.
 
         If *create_edges_str* is not callable,
         :exc:`.LenaTypeError` is raised.
@@ -148,19 +152,34 @@ def __init__(self, create_edges_str=None):
                 "{} provided".format(create_edges_str)
             )
         self._create_edges_str = create_edges_str
+        if select is None:
+            # bins contain histograms
+            self._select = lena.flow.Selector(lena.structures.histogram)
+        else:
+            self._select = lena.flow.Selector(select)
 
     def run(self, flow):
+        """Yield histogram bins one by one.
+
+        For each :class:`.histogram`, if its bins pass the
+        *selector*, they are iterated.
+        "edges" (with bin edges) and "edges_str" (their representation)
+        are added to *context.bin*.
+
+        Not histograms pass unchanged.
+        """
         for value in flow:
             data, context = lena.flow.get_data_context(value)
+            # select histograms
             if not isinstance(data, lena.structures.histogram):
                 yield value
                 continue
-            # data is a histogram
-            # check bins
+            # bins contain histograms
             data00 = lena.flow.get_data(get_example_bin(data))
-            if not isinstance(data00, lena.structures.histogram):
+            if not self._select(data00):
                 yield value
                 continue
+
             # bin is a histogram
             ## context is not shared, but yielded,
             ## so deep copy is not needed
@@ -347,7 +366,7 @@ def __init__(self, seq, arg_var, edges):
             To plot them, one can extract vector components with e.g.
             :class:`.MapBins`.
             If bin contents are histograms,
-            they can be yielded one by one with :class:`.TransformBins`.
+            they can be yielded one by one with :class:`.IterateBins`.
 
         **Attributes**: bins, edges.
 

tests/flow/test_split_into_bins.py

@@ -8,7 +8,7 @@
 from lena.core import Split, FillCompute, Sequence
 from lena.variables import Variable
 from lena.structures import histogram
-from lena.flow import SplitIntoBins, TransformBins, MapBins
+from lena.flow import SplitIntoBins, IterateBins, MapBins
 from lena.flow.split_into_bins import _iter_bins_with_edges
 
 from tests.examples.fill_compute import Count, Sum
@@ -68,14 +68,14 @@ def test_get_example_bin():
 def test_transform_bins():
     ## test init
     with pytest.raises(lena.core.LenaTypeError):
-        TransformBins(create_edges_str=1)
+        IterateBins(create_edges_str=1)
 
     ## test run
     # not histograms pass unchanged
     # histogram bins must be histograms
     hist = histogram([1, 2], [1])
     data = [1, (2, {}), lena.structures.Graph(), hist]
-    t = TransformBins()
+    t = IterateBins()
     assert list(t.run(data)) == data
 
     data_unchanged = [(histogram([0, 1], [hist]), {
@@ -99,7 +99,7 @@ def test_transform_bins():
         }
     }
     # create_edges_str works
-    t1 = TransformBins(create_edges_str=sib.cell_to_string)
+    t1 = IterateBins(create_edges_str=sib.cell_to_string)
     data = copy.deepcopy(data_unchanged)
     results1 = list(t1.run(data))
     assert results1 == results