Merge pull request scipy#9423 from ludcila/issues/9381

DOC: Clearly state how 2x2 input arrays are handled in stats.linregress

scipy/stats/_stats_mstats_common.py

@@ -19,21 +19,23 @@ def linregress(x, y=None):
     Parameters
     ----------
     x, y : array_like
-        Two sets of measurements.  Both arrays should have the same length.
-        If only x is given (and y=None), then it must be a two-dimensional
+        Two sets of measurements.  Both arrays should have the same length.  If
+        only `x` is given (and ``y=None``), then it must be a two-dimensional
         array where one dimension has length 2.  The two sets of measurements
-        are then found by splitting the array along the length-2 dimension.
+        are then found by splitting the array along the length-2 dimension.  In
+        the case where ``y=None`` and `x` is a 2x2 array, ``linregress(x)`` is
+        equivalent to ``linregress(x[0], x[1])``.
 
     Returns
     -------
     slope : float
-        slope of the regression line
+        Slope of the regression line.
     intercept : float
-        intercept of the regression line
+        Intercept of the regression line.
     rvalue : float
-        correlation coefficient
+        Correlation coefficient.
     pvalue : float
-        two-sided p-value for a hypothesis test whose null hypothesis is
+        Two-sided p-value for a hypothesis test whose null hypothesis is
         that the slope is zero, using Wald Test with t-distribution of
         the test statistic.
     stderr : float
@@ -46,6 +48,11 @@ def linregress(x, y=None):
     :func:`scipy.optimize.leastsq` : Minimize the sum of
      squares of a set of equations.
 
+    Notes
+    -----
+    Missing values are considered pair-wise: if a value is missing in `x`,
+    the corresponding value in `y` is masked.
+
     Examples
     --------
     >>> import matplotlib.pyplot as plt
@@ -63,10 +70,10 @@ def linregress(x, y=None):
     >>> print("slope: %f    intercept: %f" % (slope, intercept))
     slope: 1.944864    intercept: 0.268578
 
-    To get coefficient of determination (r_squared):
+    To get coefficient of determination (R-squared):
 
-    >>> print("r-squared: %f" % r_value**2)
-    r-squared: 0.735498
+    >>> print("R-squared: %f" % r_value**2)
+    R-squared: 0.735498
 
     Plot the data along with the fitted line:
 
@@ -75,6 +82,13 @@ def linregress(x, y=None):
     >>> plt.legend()
     >>> plt.show()
 
+    Example for the case where only x is provided as a 2x2 array:
+
+    >>> x = np.array([[0, 1], [0, 2]])
+    >>> r = stats.linregress(x)
+    >>> r.slope, r.intercept
+    (2.0, 0.0)
+
     """
     TINY = 1.0e-20
     if y is None:  # x is a (2, N) or (N, 2) shaped array_like

scipy/stats/mstats_basic.py

@@ -56,15 +56,6 @@
         )
 
 
-genmissingvaldoc = """
-
-    Notes
-    -----
-    Missing values are considered pair-wise: if a value is missing in x,
-    the corresponding value in y is masked.
-    """
-
-
 def _chk_asarray(a, axis):
     # Always returns a masked array, raveled for axis=None
     a = ma.asanyarray(a)
@@ -837,10 +828,6 @@ def linregress(x, y=None):
     return LinregressResult(slope, intercept, r, prob, sterrest)
 
 
-if stats_linregress.__doc__:
-    linregress.__doc__ = stats_linregress.__doc__ + genmissingvaldoc
-
-
 def theilslopes(y, x=None, alpha=0.95):
     r"""
     Computes the Theil-Sen estimator for a set of points (x, y).