DOC: add example for stats.mstats.compare_median_ms

[sudosoph]

Reference issue

#7168

Description

Added example for stats.mstats.compare_median_ms. Provided example usage for method.

[mdhaber]

Thanks @sudosoph! There are a few CI failures we'll need to fix.

By clicking "Details" at the scipy.scipy (Main Lint) check and clicking some more until you get to the terminal output, we see

./scipy/stats/mstats_extras.py:435:80: E501 line too long (244 > 79 characters)
./scipy/stats/mstats_extras.py:436:80: E501 line too long (138 > 79 characters)

We need to follow PEP8 line length conventions, so please break those up.

scipy.scipy (Main refguide_asv_check) is telling us:

/home/circleci/repo/build/testenv/lib/python3.7/site-packages/scipy/stats/mstats_extras.py:docstring of scipy.stats.mstats_extras.compare_medians_ms:57: WARNING: Unknown target name: "1".

It doesn't know what you meant when you referenced the target [1]_ in the code on line 412, I think.

If you take a look at references in other files or at the numpydoc standards, you'll see two .. need to come before each reference number (e.g. .. [1]) in the References section. You need those dots to define the reference - otherwise Sphinx thinks that [1] is just normal text.

Oops, didn't mean to close! Re-opened though. Please try to fix these and I'll take another look.

[mdhaber]

Previously, the PR referenced "Introduction to Robust Estimation and Hypothesis Testing" and seemed to refer to this part:

but the test shown there:

does not appear to be what is going on in the code. Instead, I added a reference to McKean & Schrader. "A comparison of methods for studentizing the sample median." I'm not sure if it actually suggests this test, but it will at least point the reader in the right direction.

Without a good reference, I decided not to try to add notes about what this function actually does (returns just a p-value, apparently), because although it appears reasonable, I'm not sure how valid the test is. I would open an issue to review this stuff more thoroughly, but I think gh-14651 is leaning toward unifying stats and mstats, at which point we can reconsider these mstats tests that don't have references.

[mdhaber]

Thanks @sudosoph!