fix #338 : implemented option 'exact' in align()

Author: alixdamman

doc/source/changes/version_0_30.rst.inc

@@ -135,6 +135,11 @@ Miscellaneous improvements
     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`.
+
+
 Fixes
 -----
 

larray/core/array.py

@@ -1481,13 +1481,14 @@ def align(self, other, join='outer', fill_value=nan, axes=None):
         Parameters
         ----------
         other : LArray-like
-        join : {'outer', 'inner', 'left', 'right'}, optional
+        join : {'outer', 'inner', 'left', 'right', 'exact'}, optional
             Join method. For each axis common to both arrays:
               - outer: will use a label if it is in either arrays axis (ordered like the first array).
                        This is the default as it results in no information loss.
-              - inner: will use a label if it is in both arrays axis (ordered like the first array)
-              - left: will use the first array axis labels
+              - inner: will use a label if it is in both arrays axis (ordered like the first array).
+              - left: will use the first array axis labels.
               - right: will use the other array axis labels.
+              - exact: instead of aligning, raise an error when axes to be aligned are not equal.
         fill_value : scalar or LArray, optional
             Value used to fill cells corresponding to label combinations which are not common to both arrays.
             Defaults to NaN.
@@ -1638,12 +1639,23 @@ def align(self, other, join='outer', fill_value=nan, axes=None):
          a0   0.0  -1.0  nan
          a1  -2.0  -3.0  nan
          a2  -4.0  -5.0  nan
+
+        Test if two arrays are aligned
+
+        >>> arr1.align(arr2, join='exact')   # doctest: +NORMALIZE_WHITESPACE
+        Traceback (most recent call last):
+        ...
+        ValueError: Both arrays are not aligned because align method with join='exact'
+        expected Axis(['a0', 'a1'], 'a') to be equal to Axis(['a0', 'a1', 'a2'], 'a')
         """
         other = aslarray(other)
         # reindex does not currently support anonymous axes
         if any(name is None for name in self.axes.names) or any(name is None for name in other.axes.names):
             raise ValueError("arrays with anonymous axes are currently not supported by LArray.align")
-        left_axes, right_axes = self.axes.align(other.axes, join=join, axes=axes)
+        try:
+            left_axes, right_axes = self.axes.align(other.axes, join=join, axes=axes)
+        except ValueError as e:
+            raise ValueError("Both arrays are not aligned because {}".format(e))
         return self.reindex(left_axes, fill_value=fill_value), other.reindex(right_axes, fill_value=fill_value)
 
     @deprecate_kwarg('reverse', 'ascending', {True: False, False: True})

larray/core/axis.py

@@ -1201,7 +1201,7 @@ def align(self, other, join='outer'):
         Parameters
         ----------
         other : Axis or label sequence
-        join : {'outer', 'inner', 'left', 'right'}, optional
+        join : {'outer', 'inner', 'left', 'right', 'exact'}, optional
             Defaults to 'outer'.
 
         Returns
@@ -1225,8 +1225,13 @@ def align(self, other, join='outer'):
         Axis(['a0', 'a1', 'a2'], 'a')
         >>> axis1.align(axis2, join='right')
         Axis(['a1', 'a2', 'a3'], 'a')
+        >>> axis1.align(axis2, join='exact')   # doctest: +NORMALIZE_WHITESPACE
+        Traceback (most recent call last):
+        ...
+        ValueError: align method with join='exact' expected
+        Axis(['a0', 'a1', 'a2'], 'a') to be equal to Axis(['a1', 'a2', 'a3'], 'a')
         """
-        assert join in {'outer', 'inner', 'left', 'right'}
+        assert join in {'outer', 'inner', 'left', 'right', 'exact'}
         if join == 'outer':
             return self.union(other)
         elif join == 'inner':
@@ -1237,6 +1242,12 @@ def align(self, other, join='outer'):
             if not isinstance(other, Axis):
                 other = Axis(other)
             return other
+        elif join == 'exact':
+            if not self.equals(other):
+                raise ValueError("align method with join='exact' "
+                                 "expected {!r} to be equal to {!r}".format(self, other))
+            else:
+                return self
 
     def to_hdf(self, filepath, key=None):
         """
@@ -2976,7 +2987,7 @@ def align(self, other, join='outer', axes=None):
         Parameters
         ----------
         other : AxisCollection
-        join : {'outer', 'inner', 'left', 'right'}, optional
+        join : {'outer', 'inner', 'left', 'right', 'exact'}, optional
             Defaults to 'outer'.
         axes : AxisReference or sequence of them, optional
             Axes to align. Need to be valid in both arrays. Defaults to None (all common axes). This must be specified
@@ -3047,8 +3058,8 @@ def align(self, other, join='outer', axes=None):
             Axis(['c0'], None)
         ])
         """
-        if join not in {'outer', 'inner', 'left', 'right'}:
-            raise ValueError("join should be one of 'outer', 'inner', 'left' or 'right'")
+        if join not in {'outer', 'inner', 'left', 'right', 'exact'}:
+            raise ValueError("join should be one of 'outer', 'inner', 'left', 'right' or 'exact'")
         other = other if isinstance(other, AxisCollection) else AxisCollection(other)
 
         # if axes not specified