Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

minor errors in documentation of scipy Bessel Function #3397

Closed
jdsahr opened this Issue · 14 comments

6 participants

@jdsahr

see http://docs.scipy.org/doc/scipy/reference/special.html

in the Bessel Functions section.

  1. the description of jn() and jv() are identical, however jn() should be "integer order n" while jv() should be "real order v". (c.f. the entries for yn() and yv() )

  2. in the Bessel Functions section, note that the arguments in the function list (typically x1, x2) do not match the arguments in the description (typically n(or v), z)

  3. the optional "out" parameter is not described

@ev-br
Collaborator

PRs are always welcome. The docs for special functions can indeed benefit from some work.

The relevant file here is https://github.com/scipy/scipy/blob/master/scipy/special/add_newdocs.py
If you do give it a shot, notice that the docs for special functions have been very recently improved quite significantly, so make sure you work off the current master branch.

@pv
Owner
pv commented
  1. jn and jv are the same function (try: jn is jv).
  2. This has been fixed.
@rgommers
Owner

To clarify (2), that was fixed in numpy. The scipy binaries are compiled against numpy 1.5.1 and therefore still show this:

jv(x1, x2[, out])

jv(v, z)

Bessel function of the first kind of real order v

Not much we can do about that. The html documentation at http://docs.scipy.org/doc/scipy/reference/generated/scipy.special.jn.html#scipy.special.jn is OK.

Regarding (3): out is a generic parameter for all ufuncs, we're not going to describe it in every single docstring. All fixed, and 1 a duplicate of gh-2564, so closing.

@rgommers rgommers closed this
@WarrenWeckesser
Collaborator

@rgommers wrote:

Regarding (3): out is a generic parameter for all ufuncs, we're not going to describe it in every single docstring.

We probably should describe it in every docstring, IMHO. It's a useful argument, and, well, docstrings should describe their arguments. I don't see why we wouldn't want it documented right where it is needed. (But no, I'm not volunteering to add it to all the docstrings; I'm already falling behind on my existing to-do list.)

@rgommers
Owner

That would be literally repeating the same text hundreds of times. Numpy also doesn't do this. Note that if you do ufuncname? in IPython, the Ufunc class docstring is shown below the docstring and there out is already explained.

@argriffing
Collaborator

If I recall, scipy.special has a few functions that do not follow the usual out= keyword format, so as long as these exceptions persist I'd find the mostly redundant documentation useful.

@rgommers
Owner

There are about 330 objects in special of which 220 are ufuncs. Whether a function is a ufunc or not is indicated in the docs (example: docs.scipy.org/doc/scipy/reference/generated/scipy.special.i1.html). Ufuncs have out, the rest not. This is the same as for numpy. I'd want to follow numpy doc standards in this respect.

@WarrenWeckesser
Collaborator

That would be literally repeating the same text hundreds of times. Numpy also doesn't do this.

Yup. Numpy should be fixed, too. :)

The signal-to-noise ratio is too low. Of course, there is a trade-off between developer convenience and the clarity and specificity of the docstring; I think the current implementation has favored developer convenience too much, resulting in docstrings that are confusing for new users. The ufuncs are designed to act like functions. Why show the generic class docstring, which includes a generic description of unary and binary ufuncs in every function? If I want to use, say, jv, all I want to see is something like:

jv(v, z, out=None)

Bessel function of the first kind of real order v

Parameters
----------
v : ...etc...
z : ...
out : ...

...

Notes
-----
`jv` is a "ufunc".  See `numpy.ufunc` for more information about ufuncs.
@argriffing
Collaborator

I'd also expect the docs to look more like that.

@rgommers
Owner

Eh, that's a property of IPython's ? and of help(), not a choice made by numpy.

@rgommers
Owner

More importantly, out is not that special. Ufuncs now have 8 standard keywords: http://docs.scipy.org/doc/numpy/reference/ufuncs.html#optional-keyword-arguments

It really does not make sense to document all of those.

@pv
Owner
pv commented

That they're ufuncs is sort of an inherited legacy implementation detail, IMHO. It has also the drawback that there can be no default args. As it's just mostly massively autogenerated set of functions since 0.13.0, this can perhaps be changed if there are incentives for it.

@WarrenWeckesser
Collaborator

Eh, that's a property of IPython's ?

Ah, good point. I'd still like to get rid of it, considering how much ipython is recommended and used. It would probably require some pretty fundamental changes in how ufuncs are implemented to do that, though.

Regarding the 8 standard keywords: I don't know--I don't think it would be too bad to include them in the docstrings, especially out and where. On the other hand, I can see how reading through subok, sig and extobj also lowers the SNR for the non-expert who just wants to compute a Bessel function.

@rgommers
Owner

@pv in practice it may not be too bad, but changing them to not be ufuncs is in principle a massive backwards compatibility break. Not sure we can do that in a minor release.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.