diff options
| author | xoviat <xoviat@users.noreply.github.com> | 2017-12-26 12:29:52 -0600 |
|---|---|---|
| committer | Charles Harris <charlesr.harris@gmail.com> | 2017-12-26 11:29:52 -0700 |
| commit | 2d761b6ac092b93cb011db524e9f230957e5ff0f (patch) | |
| tree | 1c6c0c582f1fed28c009bb195e43d2b7e426c535 /numpy/core/numeric.py | |
| parent | a4c995577505ed4c5480f3229537eeabd728f598 (diff) | |
| download | numpy-2d761b6ac092b93cb011db524e9f230957e5ff0f.tar.gz | |
DOC: add warning to isclose function (#10214)
* DOC: add warning to isclose function
The default absolute tolerance for isclose can result in misleading results
when the numbers being compared are much less than one.
See gh-10161 for discussion.
* DOC: compare numpy.isclose to math.isclose function.
* DOC: somewhat clarify the warning for the isclose function
* DOC: clarify notes for isclose function
* DOC: clarify that atol should be reduced for small numbers
* DOC: update based on feedback
* DOC: update based on feedback
[skip-ci]
Diffstat (limited to 'numpy/core/numeric.py')
| -rw-r--r-- | numpy/core/numeric.py | 23 |
1 files changed, 20 insertions, 3 deletions
diff --git a/numpy/core/numeric.py b/numpy/core/numeric.py index 431467a5a..123bff2ec 100644 --- a/numpy/core/numeric.py +++ b/numpy/core/numeric.py @@ -2276,6 +2276,9 @@ def isclose(a, b, rtol=1.e-5, atol=1.e-8, equal_nan=False): relative difference (`rtol` * abs(`b`)) and the absolute difference `atol` are added together to compare against the absolute difference between `a` and `b`. + + .. warning:: The default `atol` is not appropriate for comparing numbers + that are much smaller than one (see Notes). Parameters ---------- @@ -2309,9 +2312,15 @@ def isclose(a, b, rtol=1.e-5, atol=1.e-8, equal_nan=False): absolute(`a` - `b`) <= (`atol` + `rtol` * absolute(`b`)) - The above equation is not symmetric in `a` and `b`, so that - `isclose(a, b)` might be different from `isclose(b, a)` in - some rare cases. + Unlike the built-in `math.isclose`, the above equation is not symmetric + in `a` and `b` -- it assumes `b` is the reference value -- so that + `isclose(a, b)` might be different from `isclose(b, a)`. Furthermore, + the default value of atol is not zero, and is used to determine what + small values should be considered close to zero. The default value is + appropriate for expected values of order unity: if the expected values + are significantly smaller than one, it can result in false positives. + `atol` should be carefully selected for the use case at hand. A zero value + for `atol` will result in `False` if either `a` or `b` is zero. Examples -------- @@ -2325,6 +2334,14 @@ def isclose(a, b, rtol=1.e-5, atol=1.e-8, equal_nan=False): array([True, False]) >>> np.isclose([1.0, np.nan], [1.0, np.nan], equal_nan=True) array([True, True]) + >>> np.isclose([1e-8, 1e-7], [0.0, 0.0]) + array([ True, False], dtype=bool) + >>> np.isclose([1e-100, 1e-7], [0.0, 0.0], atol=0.0) + array([False, False], dtype=bool) + >>> np.isclose([1e-10, 1e-10], [1e-20, 0.0]) + array([ True, True], dtype=bool) + >>> np.isclose([1e-10, 1e-10], [1e-20, 0.999999e-10], atol=0.0) + array([False, True], dtype=bool) """ def within_tol(x, y, atol, rtol): with errstate(invalid='ignore'): |