unexpected behavior for numpy.real_if_close()

I am working my way through the scipy tutorial, and I encountered a behavior of the function numpy.real_if_close that I don’t quite understand From the documentation of real_if_close, real, and imag the parameters of the three functions are described the same way, therefore I am a little lost in their different behavior with respect to the same object.

Reproducing code example:

b = np.array([1+1j, 2+1j, 3+1j, 4+5e-15j])
print(b)
>>>[1.+1.e+00j 2.+1.e+00j 3.+1.e+00j 4.+5.e-15j]

print(np.real(b))
>>>[1. 2. 3. 4.]
print(b.real)
>>>[1. 2. 3. 4.]

print(np.imag(b))
>>>[0. 0. 0. 5.]
print(b.imag)
>>>[0. 0. 0. 5.]

print(np.finfo(float).eps)
>>>2.220446049250313e-16

print(b) # <-- to make sure I didn't change b
>>>[1.+1.e+00j 2.+1.e+00j 3.+1.e+00j 4.+5.e-15j]

print(np.real_if_close(b, tol=1000)) # <-- does not perform the approx 4+5e-14j ~= 4
>>>[1.+1.e+00j 2.+1.e+00j 3.+1.e+00j 4.+5.e-15j]
print(b.real_if_close(tol=1000)) # <-- raises an AttributeError
>>>AttributeError: 'numpy.ndarray' object has no attribute 'real_if_close'

print(np.real_if_close([2.1 + 4e-14j], tol=1000)) # <-- example from the tutorial
>>>[2.1]

Numpy/Python version information:

1.17.4 3.7.6 (default, Jan 8 2020, 20:23:39) [MSC v.1916 64 bit (AMD64)]

[ghost]

Sure! I’ll try to update the documentation, also with my pitfall example, so that there might be less confusion for the time being.

[seberg]

The function only casts if all of the numbers are almost real. I am wondering if we should deprecate it, at least in documentation. I seem to remember others being confused about it before, and I feel it is useful, but not sure it is useful enough (and tricky from a type safety perspective, so more a user/convenience than a library function). I.e. it would be nicer to write something:

if all_complex_almost_real(arr):
    arr = arr.real

Writing such a function yourself should be fairly easy (with whatever “close” semantics you want, another issue since it only supports absolute, not relative semantics).