DOC: stats.linregress: split stats/mstats documentation

[mdhaber]

Reference issue

NA

What does this implement/fix?

The documentation of scipy.stats.linregress incorrectly suggests that masked arrays are supported:

Missing values are considered pair-wise: if a value is missing in x, the corresponding value in y is masked.

Masks are silently ignored by this function, so this PR removes the statement. This PR also corrects a typo about the first argument being a 2x2 array; it meant 2xN array, where N is the number of observations.

Also, the documentation of scipy.stats.mstats.linregress currently looks like:

suggesting that the docstring was supposed to be replaced automatically. I'm not aware of any machinery to do that, so I copied the scipy.stats.linregress documentation over and changed the example to use stats.mstats.linregress instead of stats.linregress.

Additional information

I decided against adding a mask to the example in the mstats version. For one thing, the mstats version of the function offers little value since it simply calls the stats version after compressing the arrays, so it is not worth much time to maintain it. Also, if nobody noticed that the documentation was missing entirely, it is unlikely that anyone would appreciate an improved example.

If we want scipy.stats.linregress to be translated to array-API, I think we should deprecate the y=None behavior and make y a required argument. It's not strictly required, but I think it would be confusing to preserve this behavior when there can be arrays of arbitrary dimensionality. Please indicate whether you agree, and I'll make the change in a separate PR.

[melissawm]

Changes look good to me, thanks @mdhaber

For reference, this is what we do in NumPy to reuse the docstrings: https://github.com/numpy/numpy/blob/f8392ce66e411c70bb97858412da02ab6e369a30/numpy/ma/core.py#L5139

[mdhaber]

Thanks @melissawm. Right, I've modified docs like that before, but there are some small differences, so we don't want to have exact copies. In this case, I don't the complexity of modifying one version of the docs (e.g. with the help of docscrape) is justified.

[melissawm]

That sounds good, thanks!

[melissawm]

Thank you, @mdhaber !