DOC: Improve description of axis parameter for np.median

[szwiep]

This PR includes an updated docstring for numpy.median which clarifies the functionality of the extended axis feature, introduced in 1.9.0.

Specifically, the description of the docstring is changed and an example is added. These help to clarify if a sequence of axes is passed, that the array is flattened along the given axes and then the median is computed over the resulting flattened axis. Without this change, the functionality of passing multiple axes could be misunderstood as computing medians sequentially over the given axes (without flattening), see #25174.

Resolves #25174

[ngoldbaum]

These examples in the docstrings should be runnable. Using b here when it hasn't been defined above doesn't make sense. I would also not use overwrite_input, since that confuses things.

In principle doctests should catch issues like b not being defined in the docstring yet, but I'm not sure we run doctests on the full numpy codebase...

Instead, I think it makes more sense to just rewrite all of these examples to use a small 3D array, so this example where you take the median successively over two dimensions makes sense. Something like:

>>> import numpy as np
>>> a = np.arange(27)
>>> a.shape = (3, 3, 3)
>>> a
array([[[ 0,  1,  2],
        [ 3,  4,  5],
        [ 6,  7,  8]],

       [[ 9, 10, 11],
        [12, 13, 14],
        [15, 16, 17]],

       [[18, 19, 20],
        [21, 22, 23],
        [24, 25, 26]]])
>>> np.median(a)
np.float64(13.0)
>>> np.median(a, axis=0)
array([[ 9., 10., 11.],
       [12., 13., 14.],
       [15., 16., 17.]])
>>> np.median(a, axis=(0, 1))
array([12., 13., 14.])

And then if you didn't feel like editing the rest of this, you could redefine a to its original value below this example.

Just a thought, though! There are probably other ways to edit this that would make sense.

Also it would be nice if you could make sure this docstring is actually fully runnable and updated, since it looks like it hasn't been updated for the fallout from NEP 50 (ping @seberg - there's probably a lot of other docstrings that need to be updated right?).

[ngoldbaum]

Err, not NEP 50, I guess just the new reprs for scalars?

[seberg]

Yeah, that is on my not-done list. I had always hoped to use scientific-python/pytest-doctestplus#227 although that is a bit tedious until we better support doctestplus.

OTOH, a few failures (and misses) shouldn't matter too much.

At this time, I think just don't worry about whether or not you write np.float64(1.0) or 1.0, keeping things consistent may be better...

[mdhaber]

I went ahead and made the example runnable and removed overwrite_input. I think the lightly modified example illustrates that np.median(a, axis=(0, 1)) flattens both axes to a single axis before performing the calculation, just like np.median(a) does (for a 2d array), so the result is the same (3.5). This is distinct from the alternative, which would be to take the median of the medians from the lines above (4.5). Although a 2D example cannot distinguish the behavior of axis=None from axis=a_tuple, I think it strikes a compromise between completeness and complexity that's appropriate for an individual function's docstring. Since this seems to resolve the issue by the same author, I'll go ahead and merge. If needed, we can make further improvements to the documentation of all functions with this behavior in a separate PR, if that sounds good?

[szwiep]

Thank you for fixing up the docstring and for the comments. If there ends up being interest in making further improvements to all functions that use the axis parameter, I'd be happy to contribute.

[mdhaber]

If there ends up being interest in making further improvements to all functions

Sure. If you're interested, I'd suggest surveying what is currently documented about the axis parameter, summarizing the findings in an issue, and (if necessary) proposing a few ideas for improvement in that issue. Because documentation issues usually come up within the context of a particular function, and because more general documentation is a bit harder to write than function-specific documentation, the scope of issues and PRs is often restricted to a particular function. However, in the long run, it might be more efficient solve the general problem (if there is one).