NA.Rd 4.07 KB
Newer Older
Radford Neal's avatar
Radford Neal committed
1 2
% File src/library/base/man/NA.Rd
% Part of the R package, http://www.R-project.org
3
% Copyright 1995-2011 R Core Team
4
% Modifications for pqR Copyright (c) 2018 Radford M. Neal.
Radford Neal's avatar
Radford Neal committed
5 6 7 8 9 10 11 12 13 14 15 16
% Distributed under GPL 2 or later

\name{NA}
\alias{NA}
\alias{NA_integer_}
\alias{NA_real_}
\alias{NA_complex_}
\alias{NA_character_}
\alias{is.na}
\alias{is.na.data.frame}
\alias{is.na<-}
\alias{is.na<-.default}
17
\alias{anyNA}
Radford Neal's avatar
Radford Neal committed
18
\title{\sQuote{Not Available} / Missing Values}
Radford Neal's avatar
Radford Neal committed
19 20
\description{
  \code{NA} is a logical constant of length 1 which contains a missing
Radford Neal's avatar
Radford Neal committed
21
  value indicator.  \code{NA} can be coerced to any other vector
Radford Neal's avatar
Radford Neal committed
22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
  type except raw.  There are also constants \code{NA_integer_},
  \code{NA_real_}, \code{NA_complex_} and \code{NA_character_} of the
  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<-} sets elements to \code{NA}.
}
\usage{
NA
is.na(x)
\method{is.na}{data.frame}(x)

is.na(x) <- value
37 38

anyNA(x)
Radford Neal's avatar
Radford Neal committed
39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59
}
\arguments{
  \item{x}{an \R object to be tested: the default method handles atomic
    vectors, lists and pairlists.}
  \item{value}{a suitable index vector for use with \code{x}.}
}
%% Next par on character NAs taken from R-lang.texi:
\details{
  The \code{NA} of character type is distinct from the
  string \code{"NA"}.  Programmers who need to specify an explicit
  string \code{NA} should use \code{NA_character_} rather than
  \code{"NA"}, or set elements to \code{NA} using \code{is.na<-}.

  \code{is.na(x)} works elementwise when \code{x} is a
  \code{\link{list}}.  It is generic: you can write methods to handle
  specific classes of objects, see \link{InternalMethods}.  A complex
  value is regarded as \code{NA} if either its real or imaginary part is
  \code{NA} or \code{NaN}.

  Function \code{is.na<-} may provide a safer way to set missingness.
  It behaves differently for factors, for example.
Radford Neal's avatar
Radford Neal committed
60 61 62 63
  
  Computations using \code{NA} will normally result in \code{NA}: a
  possible exception is where \code{\link{NaN}} is also involved, in
  which case either might result.
64 65 66 67 68 69 70 71 72

  The \code{anyNA} function is provided for compatibility with the
  function of this name introduced in R-3.1.0.  It is defined simply as 
  \code{function (x) any(is.na(x))}.  This function is fast as a result of 
  general pqR optimizations, as are similar constructs such as
  \code{all(is.na(x))} and \code{any(x<0)} - these all terminate early
  when the result is apparent from early elements of \code{x}.  There
  is no reason to use \code{anyNA} except in code that may
  also be run with R Core versions of R.
Radford Neal's avatar
Radford Neal committed
73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95
}
\value{
  The default method for \code{is.na} applied to an atomic vector
  returns a logical vector of the same length as its argument \code{x},
  containing \code{TRUE} for those elements marked \code{NA} or, for
  numeric or complex vectors, \code{\link{NaN}} (!) and \code{FALSE}
  otherwise.  \code{dim}, \code{dimnames} and \code{names} attributes
  are preserved.

  The default method also works for lists and pairlists: the result for an
  element is false unless that element is a length-one atomic vector and
  the single element of that vector is regarded as \code{NA} or \code{NaN}.

  The method \code{is.na.data.frame} returns a logical matrix with the
  same dimensions as the data frame, and with dimnames taken from the
  row and column names of the data frame.
}
\references{
  Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
  \emph{The New S Language}.
  Wadsworth & Brooks/Cole.

  Chambers, J. M. (1998)
Radford Neal's avatar
Radford Neal committed
96
  \emph{Programming with Data.  A Guide to the S Language}.
Radford Neal's avatar
Radford Neal committed
97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116
  Springer.
}
\seealso{
  \code{\link{NaN}}, \code{\link{is.nan}}, etc.,
  and the utility function \code{\link{complete.cases}}.

  \code{\link{na.action}}, \code{\link{na.omit}}, \code{\link{na.fail}}
  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

(xx <- c(0:4))
is.na(xx) <- c(2, 4)
xx                     #> 0 NA  2 NA  4
}
\keyword{NA}
\keyword{logic}
\keyword{manip}