improve docs

base/statistics.jl

@@ -510,14 +510,23 @@ median{T}(v::AbstractArray{T}, region) = mapslices(median!, v, region)
 
 # for now, use the R/S definition of quantile; may want variants later
 # see ?quantile in R -- this is type 7
-# TODO: need faster implementation (use select!?)
-#
-"""
+doc"""
     quantile!([q, ] v, p; sorted=false)
 
-Compute the quantile(s) of a vector `v` at the probabilities `p`, with optional output into array `q` (if not provided, a new output array is created). The keyword argument `sorted` indicates whether `v` can be assumed to be sorted; if `false` (the default), then the elements of `v` may be partially sorted.
+Compute the quantile(s) of a vector `v` at the probabilities `p`, with optional output into
+array `q` (if not provided, a new output array is created). The keyword argument `sorted`
+indicates whether `v` can be assumed to be sorted; if `false` (the default), then the
+elements of `v` may be partially sorted.
+
+The elements of `p` should be on the interval [0,1], and `v` should not have any `NaN`
+values.
+
+Quantiles are computed via linear interpolation between the points $((k-1)/(n-1), v[k])$,
+for $k=1,\ldots,n$ where $n$ is the length of $v$. This corresponds to Definition 7 of
+Hyndman and Fan (1996), and is the same as the R default.
 
-The elements of `p` should be on the interval [0,1], and `v` should not have any `NaN` values.
+* Hyndman, R.J and Fan, Y. (1996) "Sample Quantiles in Statistical Packages",
+  *The American Statistician*, Vol. 50, No. 4, pp. 361-365
 """
 function quantile!(q::AbstractArray, v::AbstractVector, p::AbstractArray;
                    sorted::Bool=false)
@@ -583,12 +592,20 @@ end
 end
 
 
-"""
+doc"""
     quantile(v, p; sorted=false)
 
-Compute the quantile(s) of a vector `v` at a specified probability or vector `p`. The keyword argument `sorted` indicates whether `v` can be assumed to be sorted
+Compute the quantile(s) of a vector `v` at a specified probability or vector `p`. The
+keyword argument `sorted` indicates whether `v` can be assumed to be sorted.
 
 The `p` should be on the interval [0,1], and `v` should not have any `NaN` values.
+
+Quantiles are computed via linear interpolation between the points $((k-1)/(n-1), v[k])$,
+for $k=1,\ldots,n$ where $n$ is the length of $v$. This corresponds to Definition 7 of
+Hyndman and Fan (1996), and is the same as the R default.
+
+* Hyndman, R.J and Fan, Y. (1996) "Sample Quantiles in Statistical Packages",
+  *The American Statistician*, Vol. 50, No. 4, pp. 361-365
 """
 quantile(v::AbstractVector, p; sorted::Bool=false) =
     quantile!(sorted ? v : copy!(similar(v),v), p; sorted=sorted)

doc/stdlib/math.rst

@@ -1777,23 +1777,29 @@ Statistics
 
    Compute the midpoints of the bins with edges ``e``\ . The result is a vector/range of length ``length(e) - 1``\ . Note: Julia does not ignore ``NaN`` values in the computation.
 
-.. function:: quantile(v, ps)
+.. function:: quantile(v, p; sorted=false)
 
    .. Docstring generated from Julia source
 
-   Compute the quantiles of a vector ``v`` at a specified set of probability values ``ps``\ . Note: Julia does not ignore ``NaN`` values in the computation.
+   Compute the quantile(s) of a vector ``v`` at a specified probability or vector ``p``\ . The keyword argument ``sorted`` indicates whether ``v`` can be assumed to be sorted.
 
-.. function:: quantile(v, p)
+   The ``p`` should be on the interval [0,1], and ``v`` should not have any ``NaN`` values.
 
-   .. Docstring generated from Julia source
+   Quantiles are computed via linear interpolation between the points :math:`((k-1)/(n-1), v[k])`\ , for :math:`k=1,\ldots,n` where :math:`n` is the length of :math:`v`\ . This corresponds to Definition 7 of Hyndman and Fan (1996), and is the same as the R default.
 
-   Compute the quantile of a vector ``v`` at the probability ``p``\ . Note: Julia does not ignore ``NaN`` values in the computation.
+   * Hyndman, R.J and Fan, Y. (1996) "Sample Quantiles in Statistical Packages",   *The American Statistician*, Vol. 50, No. 4, pp. 361-365
 
-.. function:: quantile!(v, p)
+.. function:: quantile!([q, ] v, p; sorted=false)
 
    .. Docstring generated from Julia source
 
-   Like ``quantile``\ , but overwrites the input vector.
+   Compute the quantile(s) of a vector ``v`` at the probabilities ``p``\ , with optional output into array ``q`` (if not provided, a new output array is created). The keyword argument ``sorted`` indicates whether ``v`` can be assumed to be sorted; if ``false`` (the default), then the elements of ``v`` may be partially sorted.
+
+   The elements of ``p`` should be on the interval [0,1], and ``v`` should not have any ``NaN`` values.
+
+   Quantiles are computed via linear interpolation between the points :math:`((k-1)/(n-1), v[k])`\ , for :math:`k=1,\ldots,n` where :math:`n` is the length of :math:`v`\ . This corresponds to Definition 7 of Hyndman and Fan (1996), and is the same as the R default.
+
+   * Hyndman, R.J and Fan, Y. (1996) "Sample Quantiles in Statistical Packages",   *The American Statistician*, Vol. 50, No. 4, pp. 361-365
 
 .. function:: cov(x[, corrected=true])