\Header{na.fail}{Handle Missing Values in Objects}
\alias{na.exclude}{na.fail}
\methalias{na.exclude.data.frame}{na.fail}
\methalias{na.exclude.default}{na.fail}
\methalias{na.fail.default}{na.fail}
\alias{na.omit}{na.fail}
\methalias{na.omit.data.frame}{na.fail}
\methalias{na.omit.default}{na.fail}
\alias{na.pass}{na.fail}
\keyword{NA}{na.fail}
\begin{Description}\relax
These generic functions are useful for dealing with \code{\Link{NA}}s
in e.g., data frames.
\code{na.fail} returns the object if it does not contain any
missing values, and signals an error otherwise.
\code{na.omit} returns the object with incomplete cases removed.
\code{na.pass} returns the object unchanged.
\end{Description}
\begin{Usage}
\begin{verbatim}
na.fail(object, ...)
na.omit(object, ...)
na.exclude(object, ...)
na.pass(object, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{object}] an \R{} object, typically a data frame
\item[\code{...}] further arguments special methods could require.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
At present these will handle vectors, matrices and data frames
comprising vectors and matrices (only).

If \code{na.omit} removes cases, the row numbers of the cases form the
\code{"na.action"} attribute of the result, of class \code{"omit"}.

\code{na.exclude} differs from \code{na.omit} only in the class of the
\code{"na.action"} attribute of the result, which is
\code{"exclude"}.  This gives different behaviour in functions making
use of \code{\Link{naresid}} and \code{\Link{napredict}}: when
\code{na.exclude} is used the residuals and predictions are padded to
the correct length by inserting \code{NA}s for cases omitted by
\code{na.exclude}.
\end{Details}
\begin{References}\relax
Chambers, J. M. and Hastie, T. J. (1992)
\emph{Statistical Models in S.}
Wadsworth \& Brooks/Cole.
\end{References}
\begin{SeeAlso}\relax
\code{\Link{na.action}};
\code{\Link{options}} with argument \code{na.action} for setting
\dQuote{NA actions};
and \code{\Link{lm}} and \code{\Link{glm}} for functions using these.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
DF <- data.frame(x = c(1, 2, 3), y = c(0, 10, NA))
na.omit(DF)
m <- as.matrix(DF)
na.omit(m)
stopifnot(all(na.omit(1:3) == 1:3))  # does not affect objects with no NA's
try(na.fail(DF))#> Error: missing values in ...

options("na.action")
\end{ExampleCode}
\end{Examples}

