{"action":"opened","issue":{"url":"https://api.github.com/repos/numpy/numpy/issues/5900","labels_url":"https://api.github.com/repos/numpy/numpy/issues/5900/labels{/name}","comments_url":"https://api.github.com/repos/numpy/numpy/issues/5900/comments","events_url":"https://api.github.com/repos/numpy/numpy/issues/5900/events","html_url":"https://github.com/numpy/numpy/issues/5900","id":78804803,"number":5900,"title":"numpy.diff docstring does not match operation for nth-order differences","user":{"login":"mcgibbon","id":12307589,"avatar_url":"https://avatars.githubusercontent.com/u/12307589?v=3","gravatar_id":"","url":"https://api.github.com/users/mcgibbon","html_url":"https://github.com/mcgibbon","followers_url":"https://api.github.com/users/mcgibbon/followers","following_url":"https://api.github.com/users/mcgibbon/following{/other_user}","gists_url":"https://api.github.com/users/mcgibbon/gists{/gist_id}","starred_url":"https://api.github.com/users/mcgibbon/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mcgibbon/subscriptions","organizations_url":"https://api.github.com/users/mcgibbon/orgs","repos_url":"https://api.github.com/users/mcgibbon/repos","events_url":"https://api.github.com/users/mcgibbon/events{/privacy}","received_events_url":"https://api.github.com/users/mcgibbon/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":0,"created_at":"2015-05-21T03:23:29Z","updated_at":"2015-05-21T03:23:29Z","closed_at":null,"body":"An [nth-order difference](http://en.wikipedia.org/wiki/Finite_difference#Higher-order_differences) refers to a difference scheme which converges to the continuous difference as the nth power of the discrete mesh size used. For n greater than 1, what numpy.diff calculates is not the nth-order finite difference, but rather a first-order forward approximation to the nth difference of the series.\r\n\r\n<code>import numpy as np\r\na = np.array([3,2,1,0])\r\nnp.diff(a, n=2)\r\nOut[65]: array([0, 0])</code>\r\n\r\nExpected:\r\n<code>Out[65]: array([1,1])</code>\r\n\r\nI don't suggest changing the code to match the docstring, rather, the docstring should probably be changed. It currently reads:\r\n\r\nCalculate the n-th order discrete difference along given axis.\r\n\r\nThe first order difference is given by out[n] = a[n+1] - a[n] along the given axis, higher order differences are calculated by using diff recursively.\r\n\r\nParameters:\t\r\na : array_like\r\nInput array\r\nn : int, optional\r\nThe number of times values are differenced.\r\naxis : int, optional\r\nThe axis along which the difference is taken, default is the last axis.\r\nReturns:\t\r\ndiff : ndarray\r\nThe n order differences. The shape of the output is the same as a except along axis where the dimension is smaller by n.\r\n\r\nIt should probably read:\r\n\r\nCalculate the n-th discrete difference along given axis.\r\n\r\nThe first difference is given by out[n] = a[n+1] - a[n] along the given axis, higher differences are calculated by using diff recursively.\r\n\r\nParameters:\t\r\na : array_like\r\nInput array\r\nn : int, optional\r\nThe number of times values are differenced.\r\naxis : int, optional\r\nThe axis along which the difference is taken, default is the last axis.\r\nReturns:\t\r\ndiff : ndarray\r\nThe n-th differences. The shape of the output is the same as a except along axis where the dimension is smaller by n.\r\n\r\nBy removing all instances of the word \"order\", the docstring would no longer misleadingly use \"nth-order\", which traditionally refers to the rate of convergence of a differencing scheme, and not which difference is being calculated."}}