numpy / numpy/numpy

DOC: Docs point to incorrect reduce for ma.alltrue and ma.sometrue

Open
#26,577 8 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

04 - Documentation component: numpy.ma
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 .reduce at the of the definitions of ma.alltrue and ma.sometrue in 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 ma module? They all appear already with help(), but don't appear online.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.