DOC: Explicitly mention a function's aliases in the documentation

[Darylgolden]

I was trying to find the round function in the documentation, but could not find it, making me falsely believe that it was deprecated. It was only after more research that I found that it was defined as an alias. I think this should be explicitly mentioned in the documentation (and for all other functions which have aliases too) to reduce confusion.

[phetdam]

Yes, depending on the version of NumPy np.round points to np.round_ or np.around. Commonly np.round_ also points to np.around. The current docs don't document np.round but the docs for np.round_ note that np.around is equivalent.

I am not sure about this, but the aliased NumPy functions may be the way they are for historical reasons, i.e. to not break code written using older versions of NumPy. Newer code should probably use the new functions directly.

[Darylgolden]

Even the np.around documentation uses np.round. This is rather confusing and I'm not sure what the "best practice" is.

[phetdam]

Not exactly. I jumped through the code of the current main and np.round_ calls np.around while np.around dispatches to ndarray.round. I'd say this is probably because ndarray.round, a method_descriptor, provides/calls into a C implementation and all these top-level functions just wrap it. Not sure why all the aliasing exists however; maybe one of the core members knows. I checked some docs for NumPy 1.6 and these functions still existed then so my supposition of "historical reasons" is out the window.

I guess that "best practice" would be to use whatever is more natural then, so using np.round vs. np.around shouldn't be a point of stress, but on second thought there is a situational aspect to it. Let's consider the differences between np.round_/np.around and ndarray.round. The former functions have the out argument that allows us to write the result into an existing ndarray, which is useful when you don't want to create a new ndarray for whatever reason. E.g.

ar = np.array([1, 2, 2.32, 1.111])
ar = np.round(ar, out=ar)

This performs the rounding in-place on ar. However, ar.round() will allocate a new ndarray with the same results.

[aparnabushan]

I am working on this issue as part of pycon india conference.