Skip to content

docstring on gradient, confusing #6847

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
arsenovic opened this issue Dec 17, 2015 · 1 comment · Fixed by #7618
Closed

docstring on gradient, confusing #6847

arsenovic opened this issue Dec 17, 2015 · 1 comment · Fixed by #7618
Labels
component: documentation component: numpy.lib

Comments

@arsenovic
Copy link

i may be misunderstanding the docstring on this function. the gradient function, describes an argument varargs to be the sample distance in each direction, but then in the docstring example it shows

>>> x = np.array([0, 1, 2, 3, 4])
>>> dx = np.gradient(x)
>>> y = x**2
>>> np.gradient(y, dx, edge_order=2)
array([-0.,  2.,  4.,  6.,  8.])

which seems like dx is the sample distance between each sample. so this example seems to indicate that varargs is more accurately described by dx1, dx2,...dxN, not dx,dy,dz,....

the ealier interpretation appears to align more closely with some test case results as well.
@faucon
Copy link

faucon commented Jan 12, 2016

I agree that this example works but does not correspond to the possibilities described earlier in the docstring.

That the example works at all is anyways a coincidence, as it only works properly for evenly spaced arrays x, where dx consists of a the same number repeated over and over again.

I would propose to remove this example from the docstring as it is really misleading of what gradient is capable to do.

@ahaldane ahaldane mentioned this issue May 11, 2016
Closed
ahaldane added a commit to ahaldane/numpy that referenced this issue May 11, 2016
@ahaldane
BUG: distance arg of np.gradient must be scalar, fix docstring
a9465db 
Fixups to docstring, and disallow non-scalars as the distance args to
np.gradient.

Fixes numpy#7548, fixes numpy#6847
@ahaldane ahaldane mentioned this issue May 11, 2016
Merged
@apbard apbard mentioned this issue Jan 4, 2017
Merged
apbard added a commit to apbard/numpy that referenced this issue Feb 22, 2017
@apbard
ENH: gradient support for unevenly spaced data
9520de9 
This somehow reverts numpy#7618 and solves numpy#6847, numpy#7548 by implementing
support for unevenly spaced data. Now the behaviour is similar to
that of Matlab/Octave function. As argument it can take:
1. A single scalar to specify a sample distance for all dimensions.
2. N scalars to specify a constant sample distance for each dimension.
   i.e. `dx`, `dy`, `dz`, ...
3. N arrays to specify the coordinates of the values along each
   dimension of F. The length of the array must match the size of
   the corresponding dimension
4. Any combination of N scalars/arrays with the meaning of 2. and 3.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
component: documentation component: numpy.lib
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

BUG: distance arg of np.gradient must be scalar, fix docstring ahaldane/numpy
3 participants
@rgommers @faucon @arsenovic