DOC: Update percentile/quantile docs

Mainly fixes the method list slightly, tones down the warning a
bit and fixes the link to the paper (I did not realize that the
link failed to work due only because the reference was missing
from nanquantile/nanpercentile).

1 files changed, 42 insertions, 30 deletions

diff --git a/numpy/lib/nanfunctions.py b/numpy/lib/nanfunctions.py
index 39e168944..d7ea1ca65 100644
--- a/numpy/lib/nanfunctions.py
+++ b/numpy/lib/nanfunctions.py
@@ -1273,21 +1273,21 @@ def nanpercentile(
     method : str, optional
         This parameter specifies the method to use for estimating the
         percentile.  There are many different methods, some unique to NumPy.
-        See the notes for explanation.  The options aligning with the R types
-        and the H&F paper are:
-
-        * (H&F 1): 'inverted_cdf'
-        * (H&F 2): 'averaged_inverted_cdf'
-        * (H&F 3): 'closest_observation'
-        * (H&F 4): 'interpolated_inverted_cdf'
-        * (H&F 5): 'hazen'
-        * (H&F 6): 'weibull'
-        * (H&F 7): 'linear'  (default)
-        * (H&F 8): 'median_unbiased'
-        * (H&F 9): 'normal_unbiased'
-
-        Mainly for compatibility reasons, NumPy also supports the following
-        options which appear to be unique to NumPy:
+        See the notes for explanation.  The options sorted by their R type
+        as summarized in the H&F paper [1]_ are:
+
+        1. 'inverted_cdf'
+        2. 'averaged_inverted_cdf'
+        3. 'closest_observation'
+        4. 'interpolated_inverted_cdf'
+        5. 'hazen'
+        6. 'weibull'
+        7. 'linear'  (default)
+        8. 'median_unbiased'
+        9. 'normal_unbiased'
+
+        The first three methods are discontiuous.  NumPy further defines the
+        following discontinuous variations of the default 'linear' (7.) option:
 
         * 'lower'
         * 'higher',
@@ -1365,6 +1365,12 @@ def nanpercentile(
     array([7., 2.])
     >>> assert not np.all(a==b)
 
+    References
+    ----------
+    .. [1] R. J. Hyndman and Y. Fan,
+       "Sample quantiles in statistical packages,"
+       The American Statistician, 50(4), pp. 361-365, 1996
+
     """
     if interpolation is not None:
         method = function_base._check_interpolation_as_method(
@@ -1427,21 +1433,21 @@ def nanquantile(
     method : str, optional
         This parameter specifies the method to use for estimating the
         quantile.  There are many different methods, some unique to NumPy.
-        See the notes for explanation.  The options aligning with the R types
-        and the H&F paper are:
-
-        * (H&F 1): 'inverted_cdf'
-        * (H&F 2): 'averaged_inverted_cdf'
-        * (H&F 3): 'closest_observation'
-        * (H&F 4): 'interpolated_inverted_cdf'
-        * (H&F 5): 'hazen'
-        * (H&F 6): 'weibull'
-        * (H&F 7): 'linear'  (default)
-        * (H&F 8): 'median_unbiased'
-        * (H&F 9): 'normal_unbiased'
-
-        Mainly for compatibility reasons, NumPy also supports the following
-        options which appear to be unique to NumPy:
+        See the notes for explanation.  The options sorted by their R type
+        as summarized in the H&F paper [1]_ are:
+
+        1. 'inverted_cdf'
+        2. 'averaged_inverted_cdf'
+        3. 'closest_observation'
+        4. 'interpolated_inverted_cdf'
+        5. 'hazen'
+        6. 'weibull'
+        7. 'linear'  (default)
+        8. 'median_unbiased'
+        9. 'normal_unbiased'
+
+        The first three methods are discontiuous.  NumPy further defines the
+        following discontinuous variations of the default 'linear' (7.) option:
 
         * 'lower'
         * 'higher',
@@ -1518,6 +1524,12 @@ def nanquantile(
     array([7., 2.])
     >>> assert not np.all(a==b)
 
+    References
+    ----------
+    .. [1] R. J. Hyndman and Y. Fan,
+       "Sample quantiles in statistical packages,"
+       The American Statistician, 50(4), pp. 361-365, 1996
+
     """
     if interpolation is not None:
         method = function_base._check_interpolation_as_method(