fix #669 : made by() method of Group and Axis classes return a list of named groups

Author: alixdamman

doc/source/changes/version_0_30.rst.inc

@@ -134,11 +134,25 @@ Miscellaneous improvements
     >>> people.matching(pattern='[AB]*')
     people['Bruce Wayne', 'Bruce Willis', 'Arthur Dent']
 
-
 * added option ``exact`` to ``join`` argument of :py:obj:`Axis.align()` and :py:obj:`LArray.align()` methods.
   Instead of aligning, passing ``join='exact'`` to the ``align`` method will raise an error when axes are not equal.
   Closes :issue:`338`.
 
+* made :py:obj:`Axis.by()` and :py:obj:`Group.by()` return a list of named groups instead of anonymous groups.
+  By default, group names are defined as ``<start>:<end>``. This can be changed via the new ``template`` argument:
+
+    >>> age = Axis('age=0..6')
+    >>> age
+    Axis([0, 1, 2, 3, 4, 5, 6], 'age')
+    >>> age.by(3)
+    (age.i[0:3] >> '0:2', age.i[3:6] >> '3:5', age.i[6:7] >> '6')
+    >>> age.by(3, step=2)
+    (age.i[0:3] >> '0:2', age.i[2:5] >> '2:4', age.i[4:7] >> '4:6', age.i[6:7] >> '6')
+    >>> age.by(3, template='{start}-{end}')
+    (age.i[0:3] >> '0-2', age.i[3:6] >> '3-5', age.i[6:7] >> '6')
+
+  Closes :issue:`669`.
+
 
 Fixes
 -----

larray/core/axis.py

@@ -196,7 +196,7 @@ def labels(self, labels):
         self._labels = labels
         self._iswildcard = iswildcard
 
-    def by(self, length, step=None):
+    def by(self, length, step=None, template=None):
         """Split axis into several groups of specified length.
 
         Parameters
@@ -205,6 +205,10 @@ def by(self, length, step=None):
             length of groups
         step : int, optional
             step between groups. Defaults to length.
+        template : str, optional
+            template describing how group names are generated. It is a string containing specific arguments
+            written inside brackets {}. Available arguments are {start} and {end} representing the first and last label
+            of each group. By default, template is defined as '{start}:{end}'.
 
         Notes
         -----
@@ -216,15 +220,17 @@ def by(self, length, step=None):
 
         Examples
         --------
-        >>> age = Axis(range(10), 'age')
+        >>> age = Axis('age=0..6')
+        >>> age
+        Axis([0, 1, 2, 3, 4, 5, 6], 'age')
         >>> age.by(3)
-        (age.i[0:3], age.i[3:6], age.i[6:9], age.i[9:10])
-        >>> age.by(3, 4)
-        (age.i[0:3], age.i[4:7], age.i[8:10])
-        >>> age.by(5, 3)
-        (age.i[0:5], age.i[3:8], age.i[6:10], age.i[9:10])
+        (age.i[0:3] >> '0:2', age.i[3:6] >> '3:5', age.i[6:7] >> '6')
+        >>> age.by(3, step=2)
+        (age.i[0:3] >> '0:2', age.i[2:5] >> '2:4', age.i[4:7] >> '4:6', age.i[6:7] >> '6')
+        >>> age.by(3, template='{start}-{end}')
+        (age.i[0:3] >> '0-2', age.i[3:6] >> '3-5', age.i[6:7] >> '6')
         """
-        return self[:].by(length, step)
+        return self[:].by(length, step, template)
 
     def extend(self, labels):
         """

larray/core/group.py

@@ -891,7 +891,7 @@ def with_axis(self, axis):
         """
         return self.__class__(self.key, self.name, axis)
 
-    def by(self, length, step=None):
+    def by(self, length, step=None, template=None):
         """Split group into several groups of specified length.
 
         Parameters
@@ -900,6 +900,10 @@ def by(self, length, step=None):
             length of new groups
         step : int, optional
             step between groups. Defaults to length.
+        template : str, optional
+            template describing how group names are generated. It is a string containing specific arguments
+            written inside brackets {}. Available arguments are {start} and {end} representing the first and last label
+            of each group. By default, template is defined as '{start}:{end}'.
 
         Notes
         -----
@@ -912,22 +916,26 @@ def by(self, length, step=None):
         Examples
         --------
         >>> from larray import Axis, X
-        >>> age = Axis(range(10), 'age')
-        >>> age[[1, 2, 3, 4, 5]].by(2)
-        (age[1, 2], age[3, 4], age[5])
-        >>> age[1:5].by(2)
-        (age.i[1:3], age.i[3:5], age.i[5:6])
-        >>> age[1:5].by(2, 4)
-        (age.i[1:3], age.i[5:6])
-        >>> age[1:5].by(3, 2)
-        (age.i[1:4], age.i[3:6], age.i[5:6])
-        >>> X.age[[0, 1, 2, 3, 4]].by(2)
-        (X.age[0, 1], X.age[2, 3], X.age[4])
+        >>> age = Axis('age=0..100')
+        >>> young_children = age[0:6]
+        >>> young_children.by(3)
+        (age.i[0:3] >> '0:2', age.i[3:6] >> '3:5', age.i[6:7] >> '6')
+        >>> young_children.by(3, step=2)
+        (age.i[0:3] >> '0:2', age.i[2:5] >> '2:4', age.i[4:7] >> '4:6', age.i[6:7] >> '6')
+        >>> young_children.by(3, template='{start}-{end}')
+        (age.i[0:3] >> '0-2', age.i[3:6] >> '3-5', age.i[6:7] >> '6')
         """
+        def make_group(start, length, name_template):
+            g = self[start:start + length]
+            labels = g.eval()
+            g.name = name_template.format(start=labels[0], end=labels[-1]) if len(labels) > 1 else str(labels[0])
+            return g
+
         if step is None:
             step = length
-        return tuple(self[start:start + length]
-                     for start in range(0, len(self), step))
+        if template is None:
+            template = '{start}:{end}'
+        return tuple(make_group(start, length, template) for start in range(0, len(self), step))
 
     # TODO: __getitem__ should work by label and .i[] should work by position. I guess it would be more consistent this
     # way even if the usefulness of subsetting a group with labels is dubious (but it is sometimes practical to treat