From b22fcf0fa38f6a1da7ed8e1be6fa3f4209a5c4ab Mon Sep 17 00:00:00 2001
From: smeyer <smeyer@00db46b3-68df-0310-9c12-caf00c1e9a41>
Date: Fri, 29 Sep 2023 14:06:35 +0000
Subject: [PATCH] mention relation to fivenum()

git-svn-id: https://svn.r-project.org/R/trunk@85232 00db46b3-68df-0310-9c12-caf00c1e9a41
---
 src/library/grDevices/man/boxplot.stats.Rd | 21 ++++++++++++++-------
 tests/Examples/grDevices-Ex.Rout.save      | 20 ++++++--------------
 2 files changed, 20 insertions(+), 21 deletions(-)

diff --git a/src/library/grDevices/man/boxplot.stats.Rd b/src/library/grDevices/man/boxplot.stats.Rd
index e8cdba0960e..320165c746b 100644
--- a/src/library/grDevices/man/boxplot.stats.Rd
+++ b/src/library/grDevices/man/boxplot.stats.Rd
@@ -1,6 +1,6 @@
 % File src/library/grDevices/man/boxplot.stats.Rd
 % Part of the R package, https://www.R-project.org
-% Copyright 1995-2018 R Core Team
+% Copyright 1995-2023 R Core Team
 % Distributed under GPL 2 or later
 
 \name{boxplot.stats}
@@ -28,18 +28,21 @@ boxplot.stats(x, coef = 1.5, do.conf = TRUE, do.out = TRUE)
   but may be invoked separately.
 }
 \value{
-  List with named components as follows:
+  A list with named components as follows:
+
   \item{stats}{a vector of length 5, containing the extreme of the
     lower whisker, the lower \sQuote{hinge}, the median, the upper
-    \sQuote{hinge} and the extreme of the upper whisker.}
+    \sQuote{hinge} and the extreme of the upper whisker.
+    For \code{coef = 0}, this vector is identical to
+    \code{\link{fivenum}(x, na.rm = TRUE)}.}
   \item{n}{the number of non-\code{NA} observations in the sample.}
   \item{conf}{the lower and upper extremes of the \sQuote{notch}
     (\code{if(do.conf)}). See the details.}
   \item{out}{the values of any data points which lie beyond the
     extremes of the whiskers (\code{if(do.out)}).}
 
-  Note that \code{$stats} and \code{$conf} are sorted in \emph{in}creasing
-  order, unlike S, and that \code{$n} and \code{$out} include any
+  Note that \code{stats} and \code{conf} are sorted in \emph{in}creasing
+  order, unlike S, and that \code{n} and \code{out} include any
   \code{+- Inf} values.
 }
 \details{
@@ -96,10 +99,14 @@ x <- c(1:100, 1000)
 (b2 <- boxplot.stats(x, do.conf = FALSE, do.out = FALSE))
 stopifnot(b1 $ stats == b2 $ stats) # do.out = FALSE is still robust
 boxplot.stats(x, coef = 3, do.conf = FALSE)
+
 ## no outlier treatment:
-boxplot.stats(x, coef = 0)
+(b3 <- boxplot.stats(x, coef = 0))
+stopifnot(b3$stats == fivenum(x))
 
-boxplot.stats(c(x, NA)) # slight change : n is 101
+## missing values are ignored
+stopifnot(identical(boxplot.stats(c(x, NA)), b1))
+## ... infinite values are not:
 (r <- boxplot.stats(c(x, -1:1/0)))
 stopifnot(r$out == c(1000, -Inf, Inf))
 
diff --git a/tests/Examples/grDevices-Ex.Rout.save b/tests/Examples/grDevices-Ex.Rout.save
index f7b6ce5bcad..296145c834b 100644
--- a/tests/Examples/grDevices-Ex.Rout.save
+++ b/tests/Examples/grDevices-Ex.Rout.save
@@ -459,8 +459,9 @@ NULL
 $out
 [1] 1000
 
+> 
 > ## no outlier treatment:
-> boxplot.stats(x, coef = 0)
+> (b3 <- boxplot.stats(x, coef = 0))
 $stats
 [1]    1   26   51   76 1000
 
@@ -473,20 +474,11 @@ $conf
 $out
 numeric(0)
 
+> stopifnot(b3$stats == fivenum(x))
 > 
-> boxplot.stats(c(x, NA)) # slight change : n is 101
-$stats
-[1]   1  26  51  76 100
-
-$n
-[1] 101
-
-$conf
-[1] 43.13921 58.86079
-
-$out
-[1] 1000
-
+> ## missing values are ignored
+> stopifnot(identical(boxplot.stats(c(x, NA)), b1))
+> ## ... infinite values are not:
 > (r <- boxplot.stats(c(x, -1:1/0)))
 $stats
 [1]   1.0  25.5  51.0  76.5 100.0