fix #871 : implemented the allclose() method

alixdamman · alixdamman · commit 390b85e40f86 · 2021-03-01T10:14:32.000+01:00
diff --git a/doc/source/api.rst b/doc/source/api.rst
@@ -414,6 +414,7 @@ Testing/Searching
    :toctree: _generated/
 
    Array.equals
+   Array.allclose
    Array.eq
    Array.isin
    Array.nonzero
diff --git a/doc/source/changes/version_0_33.rst.inc b/doc/source/changes/version_0_33.rst.inc
@@ -61,6 +61,8 @@ Miscellaneous improvements
 
 * implemented :py:obj:`isscalar()` function (closes :issue:`872`).
 
+* implemented the :py:obj:`Array.allclose()` method (closes :issue:`871`).
+
 Fixes
 ^^^^^
 
diff --git a/larray/core/array.py b/larray/core/array.py
@@ -34,6 +34,8 @@
 import functools
 import warnings
 
+from typing import Any
+
 import numpy as np
 import pandas as pd
 
@@ -5673,7 +5675,7 @@ def equals(self, other, rtol=0, atol=0, nans_equal=False, check_axes=False):
 
         See Also
         --------
-        Array.eq
+        Array.eq, Array.allclose
 
         Notes
         -----
@@ -5775,6 +5777,79 @@ def equals(self, other, rtol=0, atol=0, nans_equal=False, check_axes=False):
         except ValueError:
             return False
 
+    def allclose(self, other: Any, rtol: float = 1e-05, atol: float = 1e-08, nans_equal: bool = True,
+                 check_axes: bool = False) -> bool:
+        """
+        Compares self with another array and returns True if they are element-wise equal within a tolerance.
+
+        The tolerance values are positive, typically very small numbers.
+        The relative difference (rtol * abs(other)) and the absolute difference atol are added together to compare
+        against the absolute difference between self and other.
+
+        NaN values are treated as equal if they are in the same place and if `nans_equal=True`.
+
+        Parameters
+        ----------
+        other : Array-like
+            Input array. asarray() is used on a non-Array input.
+        rtol : float or int, optional
+            The relative tolerance parameter (see Notes). Defaults to 1e-05.
+        atol : float or int, optional
+            The absolute tolerance parameter (see Notes). Defaults to 1e-08.
+        nans_equal : boolean, optional
+            Whether or not to consider NaN values at the same positions in the two arrays as equal.
+            By default, an array containing NaN values is never equal to another array, even if that other array
+            also contains NaN values at the same positions. The reason is that a NaN value is different from
+            *anything*, including itself. Defaults to True.
+        check_axes : boolean, optional
+            Whether or not to check that the set of axes and their order is the same on both sides. Defaults to False.
+            If False, two arrays with compatible axes (and the same data) will compare equal, even if some axis is
+            missing on either side or if the axes are in a different order.
+
+        Returns
+        -------
+        bool
+            Returns True if the two arrays are equal within the given tolerance; False otherwise.
+
+        See Also
+        --------
+        Array.equals
+
+        Notes
+        -----
+        If the following equation is element-wise True, then `allclose` returns True.
+
+            absolute(array1 - array2) <= (atol + rtol * absolute(array2))
+
+        The above equation is not symmetric in array1 and array2, so that array1.allclose(array2) might be different
+        from array2.allclose(array1) in some rare cases.
+
+        Examples
+        --------
+        >>> arr1 = Array([1e10, 1e-7], "a=a0,a1")
+        >>> arr2 = Array([1.00001e10, 1e-8], "a=a0,a1")
+        >>> arr1.allclose(arr2)
+        False
+
+        >>> arr1 = Array([1e10, 1e-8], "a=a0,a1")
+        >>> arr2 = Array([1.00001e10, 1e-9], "a=a0,a1")
+        >>> arr1.allclose(arr2)
+        True
+
+        >>> arr1 = Array([1e10, 1e-8], "a=a0,a1")
+        >>> arr2 = Array([1.0001e10, 1e-9], "a=a0,a1")
+        >>> arr1.allclose(arr2)
+        False
+
+        >>> arr1 = Array([1.0, nan], "a=a0,a1")
+        >>> arr2 = Array([1.0, nan], "a=a0,a1")
+        >>> arr1.allclose(arr2)
+        True
+        >>> arr1.allclose(arr2, nans_equal=False)
+        False
+        """
+        return self.equals(other=other, rtol=rtol, atol=atol, nans_equal=nans_equal, check_axes=check_axes)
+
     @deprecate_kwarg('nan_equals', 'nans_equal')
     def eq(self, other, rtol=0, atol=0, nans_equal=False):
         """
@@ -5803,7 +5878,7 @@ def eq(self, other, rtol=0, atol=0, nans_equal=False):
 
         See Also
         --------
-        Array.equals
+        Array.equals, Array.isclose
 
         Notes
         -----
