Make structures.iter_bins_with_edges public.

docs/source/structures.rst

@@ -48,6 +48,7 @@ Structures
     init_bins
     integral
     iter_bins
+    iter_bins_with_edges
     iter_cells
     make_hist_context
     unify_1_md

lena/structures/__init__.py

@@ -12,6 +12,7 @@
     init_bins,
     integral,
     iter_bins,
+    iter_bins_with_edges,
     iter_cells,
     make_hist_context,
     unify_1_md
@@ -42,6 +43,7 @@
     'init_bins',
     'integral',
     'iter_bins',
+    'iter_bins_with_edges',
     'iter_cells',
     'make_hist_context',
     'unify_1_md',

lena/structures/hist_functions.py

@@ -367,7 +367,7 @@ def hist_to_graph(hist, make_value=None, get_coordinate="left",
     if scale is True:
         scale = hist.scale()
 
-    for value, edges in _iter_bins_with_edges(hist.bins, hist.edges):
+    for value, edges in iter_bins_with_edges(hist.bins, hist.edges):
         coord = get_coord(edges)
 
         # Since we never use contexts here, it will be optimal
@@ -471,24 +471,27 @@ def iter_bins(bins):
                 yield (((ind,) + sub_ind), val)
 
 
-def _iter_bins_with_edges(bins, edges):
-    """Yield *(bin content, bin edges)* pairs.
+def iter_bins_with_edges(bins, edges):
+    """Generate *(bin content, bin edges)* pairs.
 
-    Bin edges is a tuple, such that at index i
-    its element is bin *(lower bound, upper bound)*
-    along i-th the coordinate.
+    Bin edges is a tuple, such that
+    its item at index i is *(lower bound, upper bound)*
+    of the bin at i-th coordinate.
 
     Examples:
 
     >>> from lena.math import mesh
-    >>> list(_iter_bins_with_edges([0, 1, 2], edges=mesh((0, 3), 3)))
+    >>> list(iter_bins_with_edges([0, 1, 2], edges=mesh((0, 3), 3)))
     [(0, ((0, 1.0),)), (1, ((1.0, 2.0),)), (2, ((2.0, 3),))]
     >>>
-    >>> list(_iter_bins_with_edges(
+    >>> # 2-dimensional histogram
+    >>> list(iter_bins_with_edges(
     ...     bins=[[2]], edges=mesh(((0, 1), (0, 1)), (1, 1))
     ... ))
     [(2, ((0, 1), (0, 1)))]
 
+    .. versionadded:: 0.5
+       made public.
     """
     # todo: only a list or also a tuple, an array?
     if not isinstance(edges[0], list):

lena/structures/split_into_bins.py

@@ -9,7 +9,7 @@
 import lena.structures
 import lena.variables
 from .hist_functions import (
-    cell_to_string, get_example_bin, _iter_bins_with_edges
+    cell_to_string, get_example_bin, iter_bins_with_edges
 )
 
 
@@ -104,7 +104,7 @@ def run(self, flow):
                 yield val
                 continue
 
-            for histc, bin_edges in _iter_bins_with_edges(data.bins,
+            for histc, bin_edges in iter_bins_with_edges(data.bins,
                                                           data.edges):
                 hist, bin_context = lena.flow.get_data_context(histc)
                 # we assume that context.variable corresponds to

tests/structures/test_hist_functions.py

@@ -16,10 +16,10 @@
     hist_to_graph,
     integral,
     iter_bins,
+    iter_bins_with_edges,
     iter_cells,
     unify_1_md,
 )
-from lena.structures.hist_functions import _iter_bins_with_edges
 from lena.variables import Variable
 
 
@@ -175,7 +175,7 @@ def test_hist_to_graph():
 
 
 def test_iter_bins_with_edges():
-    ibe = lambda hist: _iter_bins_with_edges(hist.bins, hist.edges)
+    ibe = lambda hist: iter_bins_with_edges(hist.bins, hist.edges)
 
     # one-dimensional histogram works
     hist1 = histogram(mesh((0, 3), 3), bins=[0, 1, 2])

tests/structures/test_split_into_bins.py

@@ -1,5 +1,3 @@
-from __future__ import print_function
-
 import pytest
 import copy
 
@@ -10,22 +8,22 @@
 from lena.structures import cell_to_string, get_example_bin
 from lena.structures import SplitIntoBins, IterateBins, MapBins
 from lena.structures.split_into_bins import _MdSeqMap
-from lena.structures.hist_functions import _iter_bins_with_edges
+from lena.structures import iter_bins_with_edges
 
 from tests.examples.fill_compute import Count, Sum
 
 
 def test_iter_bins_with_edges():
-    ibe = _iter_bins_with_edges
+    ibe = iter_bins_with_edges
 
     # one-dimensional list works
     bins = [0]
     edges = [0, 1]
     assert list(ibe(bins, edges)) == [(0, ((0, 1),))]
     assert list(ibe([0, 1], [0, 1, 2])) ==  [(0, ((0, 1),)), (1, ((1, 2),))]
     ## old interface
-    # assert list(_iter_bins_with_edges(bins, edges)) == [(0, ([0], [1]))]
-    # assert list(_iter_bins_with_edges([0, 1], [0, 1, 2])) == [(0, ([0], [1])), (1, ([1], [2]))]
+    # assert list(iter_bins_with_edges(bins, edges)) == [(0, ([0], [1]))]
+    # assert list(iter_bins_with_edges([0, 1], [0, 1, 2])) == [(0, ([0], [1])), (1, ([1], [2]))]
 
     ## two-dimensional list works
     # one bin
@@ -34,13 +32,13 @@ def test_iter_bins_with_edges():
     # this (bins, edges) pair is legitimate
     ## strange to test it here!
     h = histogram(edges, bins)
-    assert list(_iter_bins_with_edges(bins, edges)) == [(1, ((0, 1), (2, 3)))]
+    assert list(iter_bins_with_edges(bins, edges)) == [(1, ((0, 1), (2, 3)))]
 
     edges = [[0, 1, 2], [3, 4, 5]]
     bins = [[10, 20], [30, 40]]
     # this (bins, edges) pair is legitimate
     h = histogram(edges, bins)
-    assert list(_iter_bins_with_edges(bins, edges)) == [
+    assert list(iter_bins_with_edges(bins, edges)) == [
         (10, ((0, 1), (3, 4))),
         (20, ((0, 1), (4, 5))),
         (30, ((1, 2), (3, 4))),