Repository: scipy/scipy

Issue:
cumtrapz non-zero initial  argument test
<<Please describe the issue in detail here, and for bug reports fill in the fields below.>>

Dear all,

Could you please test non-zero `initial` argument of `scipy.integrate.cumtrapz()`?
To me it seems only meaningful if `initial=0`.

Hope this helps,

KW

### Reproducing code example:
```
<<A short code example that reproduces the problem. It should be self-contained, i.e., possible to run as-is via 'python myproblem.py'>>
```
```
import numpy as np
import scipy.integrate as si
import matplotlib.pyplot as plt

x = np.deg2rad(np.arange(0, 360+0.05, 0.1))
y = np.sin(x)
z = si.cumtrapz(y, (x), initial=-1.0)
plt.clf()
plt.plot(x, y, label='$y(x)$')
plt.plot(x, z, label='$\int y \, dx$')
plt.legend(loc=0)
plt.show()
```
### Error message:
```
<<Full error message, if any (starting from line Traceback: ...)>>

```
$\int y \, dx$ graph suddenly jumps from initial value

### Scipy/Numpy/Python version information:
```
<<Output from 'import sys, scipy, numpy; print(scipy.__version__, numpy.__version__, sys.version_info)'>>

0.18.1 1.11.1 sys.version_info(major=3, minor=5, micro=2, releaselevel='final', serial=0)
```




Discussion:
Thanks for the report @kangwonlee. You're right that in your case ``initial=0`` makes sense, but the description in the docstring explains that. So not really a bug. 

The reason for providing ``initial`` is to be able to return an array of the same length as the input, rather than one less (which is annoying for plotting etc.). The authors could have chosen to use the ``initial=0`` behavior as the default and leave out the keyword completely though.
Since not a bug and we can't change the behavior anymore due to backwards compatibility, I'm closing this issue.
@rgommers Thanks for your comments.  

* I could find the [docstring](https://docs.scipy.org/doc/scipy/reference/generated/scipy.integrate.cumtrapz.html) of the `cumtrapz()` function:
> If given, uses this value as the first value in the returned result. Typically this value should be 0. Default is None, which means no value at x[0] is returned and res has one element less than y along the axis of integration.
* Do you think the following description could be more clear or specific?
> If given, insert this value at the beginning of the returned result. Typically this value should be 0. Default is None, which means no value at x[0] is returned and res has one element less than y along the axis of integration.
* Or, do you think it would be a good idea to try to introduce another default argument such as `base` or would it just add more complexity?

Thanks again & Good day,

KW

I think the change to the docstring you propose looks good, and it's probably not a great idea to add another keyword.

Resolving patch:
diff --git a/scipy/integrate/quadrature.py b/scipy/integrate/quadrature.py
--- a/scipy/integrate/quadrature.py
+++ b/scipy/integrate/quadrature.py
@@ -222,7 +222,7 @@ def cumtrapz(y, x=None, dx=1.0, axis=-1, initial=None):
     axis : int, optional
         Specifies the axis to cumulate.  Default is -1 (last axis).
     initial : scalar, optional
-        If given, uses this value as the first value in the returned result.
+        If given, insert this value at the beginning of the returned result.
         Typically this value should be 0.  Default is None, which means no
         value at ``x[0]`` is returned and `res` has one element less than `y`
         along the axis of integration.


Test patch: