DOC: Docs point to incorrect reduce for ma.alltrue and ma.sometrue
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 32.8k
- Forks
- 12.8k
- Avg merge
- 1d 7h
- Merged PRs (30d)
- 197
Description
Issue with current documentation:
When you run help(np.ma.alltrue) or help(np.ma.sometrue), you get
Help on method reduce in module numpy.ma.core:
reduce(target, axis=0, dtype=None) method of numpy.ma.core._MaskedBinaryOperation instance
Reduce `target` along the given `axis`.
When you run help on any of the other 50+ ufuncs in the ma module, you get an appropriate doc message. For example help(np.ma.logical_and) yields (the first few lines):
Help on _MaskedBinaryOperation in module numpy.ma.core:
logical_and = <numpy.ma.core._MaskedBinaryOperation object>
logical_and(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature])
Compute the truth value of x1 AND x2 element-wise.
... it continues....
The issue seems to be the .reduce that appears on just these two functions (see below).
https://github.com/numpy/numpy/blob/98e86d52ed79eb8810960bdcfac11271fc6c5434/numpy/ma/core.py#L1282-L1286
One consequence is that the attributes are different, with ma.alltrue and ma.sometrue being recognized as routines (while none of the others are).
>>>[getattr(np.ma,'logical_and'),getattr(np.ma,'alltrue')]
[<numpy.ma.core._MaskedBinaryOperation at 0x7e0545aa66d0>,
<bound method _MaskedBinaryOperation.reduce of <numpy.ma.core._MaskedBinaryOperation object at 0x7e0545aa6750>>]
>>>[inspect.isroutine(np.ma.logical_and),inspect.isroutine(np.ma.alltrue)]
[False, True]
I'm hoping to get a script put into the CI build (thanks to @ngoldbaum 's suggestion) that checks to make sure new routines are always appropriately tagged in a .rst file so they get documented on the web.
Idea or request for content:
I have a couple questions:
- How can we handle the ending
.reduceat the of the definitions ofma.alltrueandma.sometruein a way that properly tags both the same as the rest of the ufuncs? Is that possible (or even wanted). - Do we want any of these ufuncs showing up in the web documentation as routines of the
mamodule? They all appear already withhelp(), but don't appear online.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with numpy/ma/core.py at the referenced definitions around lines 1282-1286, then compare the help output for ma.alltrue and ma.sometrue with other masked ufuncs such as ma.logical_and. Review the relevant .rst documentation entries and the proposed CI check in issue #21351; done means the two functions have the intended help and web-documentation classification.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100