minor errors in documentation of scipy Bessel Function #3397

Closed
jdsahr opened this Issue Feb 26, 2014 · 14 comments

Comments

Projects
None yet
6 participants
@jdsahr

jdsahr commented Feb 26, 2014

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

This comment has been minimized.

Show comment
Hide comment
@ev-br

ev-br Feb 27, 2014

Member

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.

Member

ev-br commented Feb 27, 2014

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

This comment has been minimized.

Show comment
Hide comment
@pv

pv Feb 27, 2014

Member
  1. jn and jv are the same function (try: jn is jv).
  2. This has been fixed.
Member

pv commented Feb 27, 2014

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

This comment has been minimized.

Show comment
Hide comment
@rgommers

rgommers May 26, 2014

Member

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.

Member

rgommers commented May 26, 2014

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 May 26, 2014

@WarrenWeckesser

This comment has been minimized.

Show comment
Hide comment
@WarrenWeckesser

WarrenWeckesser May 26, 2014

Member

@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.)

Member

WarrenWeckesser commented May 26, 2014

@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

This comment has been minimized.

Show comment
Hide comment
@rgommers

rgommers May 26, 2014

Member

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.

Member

rgommers commented May 26, 2014

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

This comment has been minimized.

Show comment
Hide comment
@argriffing

argriffing May 26, 2014

Contributor

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.

Contributor

argriffing commented May 26, 2014

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

This comment has been minimized.

Show comment
Hide comment
@rgommers

rgommers May 26, 2014

Member

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.

Member

rgommers commented May 26, 2014

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

This comment has been minimized.

Show comment
Hide comment
@WarrenWeckesser

WarrenWeckesser May 26, 2014

Member

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.
Member

WarrenWeckesser commented May 26, 2014

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

This comment has been minimized.

Show comment
Hide comment
@argriffing

argriffing May 26, 2014

Contributor

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

Contributor

argriffing commented May 26, 2014

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

@rgommers

This comment has been minimized.

Show comment
Hide comment
@rgommers

rgommers May 26, 2014

Member

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

Member

rgommers commented May 26, 2014

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

@rgommers

This comment has been minimized.

Show comment
Hide comment
@rgommers

rgommers May 26, 2014

Member

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.

Member

rgommers commented May 26, 2014

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

This comment has been minimized.

Show comment
Hide comment
@pv

pv May 26, 2014

Member

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.

Member

pv commented May 26, 2014

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

This comment has been minimized.

Show comment
Hide comment
@WarrenWeckesser

WarrenWeckesser May 26, 2014

Member

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.

Member

WarrenWeckesser commented May 26, 2014

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

This comment has been minimized.

Show comment
Hide comment
@rgommers

rgommers May 26, 2014

Member

@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.

Member

rgommers commented May 26, 2014

@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