Aki Vehtari and I suggested a revision to some of the man pages
involving NA/is.nan/is.na about a year ago, but it never seems to have
gotten any traction.
https://bugs.r-project.org/show_bug.cgi?id=18691
Discussion here:
https://fediscience.org/@aveht...@bayes.club/112043521852737720
The patch file is attached (also available at bugzilla, if it doesn't
get through to the list). I find the patch format a little hard to read,
so I'm reproducing just the *new* text below.
Any ideas or suggestions would be welcome.
cheers
Ben Bolker
----
src/library/base/man/NA.Rd:
The generic function \code{is.na} indicates which elements are missing
(\code{NA}) or \sQuote{Not a Number} (\code{link{NaN}}).
in examples from this page:
is.na(c(1, NA, NA_real_, NaN)) #> FALSE TRUE TRUE TRUE
is.na(paste(c(1, NA, NA_real_, NaN))) #> FALSE FALSE FALSE FALSE
# When NaN should not be considered as missing value
is.na(c(1, NA, NA_real_, NaN)) & !is.nan(c(1, NA, NA_real_, NaN))
(POSSIBLE EDITS: more explanatory comments, especially explaining
that paste() is converting NA values to "NA" strings ...)
---
From src/library/base/man/is.finite.Rd:
whereas \code{NaN} means \sQuote{Not a Number}. \code{Inf} and
\code{NaN} are class of \code{numeric} and type of \code{double},
and can be used in real and imaginary parts of complex values, but not
as values in integer vectors.
(POSSIBLE EDITS: "class of", "type of" -> "of class"/"of type" or
"have class"/"have type" ?)
in "See Also":
\code{\link{NA}}, \sQuote{\emph{Not Available}}, which is usually used
to denote a missing value. The default mode of \code{NA} is
\code{logical}, unlike \code{NaN}, which is always of mode
\code{double}.
---
From src/library/base/man/numeric.Rd
\code{is.numeric} is a more general test of an object being
interpretable as numbers. These include special numeric objects
\code{\link{Inf}}, \code{\link{NaN}}, \code{\link{NA_integer_}},
and \code{\link{NA_real_}}.
Index: src/library/base/man/NA.Rd
===================================================================
--- src/library/base/man/NA.Rd (revision 86216)
+++ src/library/base/man/NA.Rd (working copy)
@@ -25,7 +25,8 @@
other atomic vector types which support missing values: all of these
are \link{reserved} words in the \R language.
- The generic function \code{is.na} indicates which elements are missing.
+ The generic function \code{is.na} indicates which elements are missing
+ (\code{NA}) or \sQuote{Not a Number} (\code{link{NaN}}).
The generic function \code{is.na<-} sets elements to \code{NA}.
@@ -122,9 +123,12 @@
on how methods can be tuned to deal with missing values.
}
\examples{
-is.na(c(1, NA)) #> FALSE TRUE
-is.na(paste(c(1, NA))) #> FALSE FALSE
+is.na(c(1, NA, NA_real_, NaN)) #> FALSE TRUE TRUE TRUE
+is.na(paste(c(1, NA, NA_real_, NaN))) #> FALSE FALSE FALSE FALSE
+# When NaN should not be considered as missing value
+is.na(c(1, NA, NA_real_, NaN)) & !is.nan(c(1, NA, NA_real_, NaN))
+
(xx <- c(0:4))
is.na(xx) <- c(2, 4)
xx #> 0 NA 2 NA 4
Index: src/library/base/man/is.finite.Rd
===================================================================
--- src/library/base/man/is.finite.Rd (revision 86216)
+++ src/library/base/man/is.finite.Rd (working copy)
@@ -18,9 +18,10 @@
and not missing) or infinite.
\code{Inf} and \code{-Inf} are positive and negative infinity
- whereas \code{NaN} means \sQuote{Not a Number}. (These apply to numeric
- values and real and imaginary parts of complex values but not to
- values of integer vectors.) \code{Inf} and \code{NaN} (as well as
+ whereas \code{NaN} means \sQuote{Not a Number}. \code{Inf} and
+ \code{NaN} are class of \code{numeric} and type of \code{double},
+ and can be used in real and imaginary parts of complex values, but not
+ as values in integer vectors. \code{Inf} and \code{NaN} (as well as
\code{\link{NA}}) are
\link{reserved} words in the \R language.
}
@@ -85,11 +86,12 @@
\code{dimnames} and \code{names} attributes are preserved.
}
\seealso{
- \code{\link{NA}}, \sQuote{\emph{Not Available}} which is not a number
- as well, however usually used for missing values and applies to many
- modes, not just numeric and complex.
-
- \code{\link{Arithmetic}}, \code{\link{double}}.
+ \code{\link{NA}}, \sQuote{\emph{Not Available}}, which is usually used
+ to denote a missing value. The default mode of \code{NA} is
+ \code{logical}, unlike \code{NaN}, which is always of mode
+ \code{double}.
+
+ \code{\link{Arithmetic}}, \code{\link{double}}, \code{\link{is.na}}.
}
\references{
The IEC 60559 standard, also known as the
@@ -117,7 +119,7 @@
}
\examples{
pi / 0 ## = Inf a non-zero number divided by zero creates infinity
-0 / 0 ## = NaN
+0 / 0 ## = NaN as defined in IEC 60559 standard
1/0 + 1/0 # Inf
1/0 - 1/0 # NaN
Index: src/library/base/man/numeric.Rd
===================================================================
--- src/library/base/man/numeric.Rd (revision 86216)
+++ src/library/base/man/numeric.Rd (working copy)
@@ -13,7 +13,10 @@
\description{
Creates or coerces objects of type \code{"numeric"}.
\code{is.numeric} is a more general test of an object being
- interpretable as numbers.
+ interpretable as numbers. These include special numeric objects
+ \code{\link{Inf}}, \code{\link{NaN}}, \code{\link{NA_integer_}},
+ and \code{\link{NA_real_}}.
+
}
\usage{
numeric(length = 0)
@@ -88,7 +91,8 @@
coerces to the class.
}
\seealso{
- \code{\link{double}}, \code{\link{integer}}, \code{\link{storage.mode}}.
+ \code{\link{double}}, \code{\link{integer}}, \code{\link{storage.mode}},
+ \code{\link{Inf}}, \code{\link{NaN}}.
}
\references{
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
