DOC: Mention we can return unitinitialized values #11086
Conversation
doc/source/reference/ufuncs.rst
Outdated
There was a problem hiding this comment.
Perhaps "an uninitialized return array is created."
doc/source/reference/ufuncs.rst
Outdated
There was a problem hiding this comment.
Maybe "The output array is then filled with the results of the ufunc in the places that where is true, by default everywhere if where is not specified. Note that outputs not explicitly filled are left with their uninitialized values."
doc/source/reference/ufuncs.rst
Outdated
There was a problem hiding this comment.
How about if 'out' is None (the default), rather than mentioning "missing"?
|
once the PR is approved, I can squash the commits |
|
Looks good to me. @kevincmann - do you think this would indeed have helped you? |
doc/source/reference/ufuncs.rst
Outdated
There was a problem hiding this comment.
Possibly "places that the broadcasted 'where' is True, which by default is everywhere."?
At the very least, I'd rather talk in terms of where=True (the default), rather than "not specified"
There was a problem hiding this comment.
So perhaps:
The output array is then filled with the results of the ufunc in the places that the broadcast 'where' is True. If 'where' is the scalar True (the default), then this corresponds to the entire output being filled.
doc/source/reference/ufuncs.rst
Outdated
There was a problem hiding this comment.
Both here and above, I'd omit the "(...)" and use commas, e.g., ", the default, ".
There was a problem hiding this comment.
I am new to github, so if I am missing something please correct me, but I believe the documentation for what the function returns should also be qualified with additional information.
The current documentation states that the function returns the negative of the input x:
Returns :
y : ndarray or scalar
Returned array or scalar: y = -x.
Referring to my own usage as requested, I would not have thought that I should read documentation that had no immediate relevance to what I was trying to accomplish, namely the documentation for out.
I would have seen what the function returns and I would have looked where to apply that conditionally on the input, so I would have read and understood the returns and where portion.
I would not have presumed that the lack of out (being an optional parameter) would fundamentally alter what the function returns, just as I would not presume (even now) that casting, order, dtype, etc. or the lack thereof would cause the function to become both non-deterministic and return values uncorrelated to the input.
Does that make sense? I might have done something like this as a first-time user:
>>> import numpy as np
>>> x = np.array([-1, 1, -1, 1])
>>> np.negative(x) # checking the basic functionality
array([ 1, -1, 1, -1])
>>> t = np.array([True, False, True, False])
>>> np.negative(x, where=t)
array([ 1, 139927355638704, 1, 139927355550720])
At this point I would be at a loss to explain how such a large number is returned in place of a -1, and since I have not used the out parameter at any point, I would not have expected that to have had any bearing on the behavior and would not expect adding an out parameter to correct the behavior.
There was a problem hiding this comment.
On digging deeper, it seems the recoomendation (scroll down to 4. Parameters), it seems parenthesis is the way to go
There was a problem hiding this comment.
I would not have thought that I should read documentation that had no immediate relevance to what I was trying to accomplish
That documentation is linked to under kwargs at least.
|
Just a nit, otherwise looks good to me. |
|
Just to be sure this doesn't get hidden: @kevincmann makes a good point about the place where we mention this... #11086 (comment) |
|
Yep, sounds like we should update the ufunc docstring template too, since it already mentions both |
|
I expanded the text more, and also transferred some of the text to the template. |
numpy/add_newdocs.py
Outdated
| must have a shape that the inputs broadcast to. A tuple of arrays | ||
| (possible only as a keyword argument) must have length equal to the | ||
| number of outputs; use `None` for outputs to be allocated by the ufunc. | ||
| number of outputs; use `None` for uninitilaized outputs to be |
numpy/add_newdocs.py
Outdated
| `r` will have the shape that the arrays in `x` broadcast to; if `out` is | ||
| provided, `r` will be equal to `out`. If the function has more than one | ||
| provided, it will be returned. If not, `r` will be allocated and | ||
| may cotain uninitialized values. If the function has more than one |
[ci skip]
numpy/add_newdocs.py
Outdated
| Values of True indicate to calculate the ufunc at that position, values | ||
| of False indicate to leave the value in the output alone. | ||
| of False indicate to leave the value in the output alone. Note that if | ||
| an uninitialized return array is created, values of False will leave |
There was a problem hiding this comment.
perhaps "is created via out=None, the default, "
|
Thanks Matti. |
Fixes #11072 by documenting when we will return uninitialized values, according to the text agreed upon in the issue