\HeaderA{read.dta}{Read Stata Binary Files}{read.dta}
\keyword{file}{read.dta}
\begin{Description}\relax
Reads a file in Stata version 5--10 binary format into a data frame.
\end{Description}
\begin{Usage}
\begin{verbatim}
read.dta(file, convert.dates = TRUE, convert.factors = TRUE,
         missing.type = FALSE,
         convert.underscore = FALSE, warn.missing.labels = TRUE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{file}] a filename as a character string.
\item[\code{convert.dates}] Convert Stata dates to \code{Date} class?
\item[\code{convert.factors}] Use Stata value labels to create factors?
(version 6.0 or later).
\item[\code{missing.type}] For version 8 or later, store information about
different types of missing data?
\item[\code{convert.underscore}] Convert \code{"\_"} in Stata variable names
to \code{"."} in R names?
\item[\code{warn.missing.labels}] Warn if a variable is specified with value
labels and those value labels are not present in the file.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The variables in the Stata data set become the columns of the data
frame.  Missing values are correctly handled.  The data label,
variable labels, and timestamp are stored as attributes of the data
frame.  Nothing is done with variable characteristics.

By default Stata dates (\%d and \%td formats) are converted to \R's
\code{Date} class and variables with Stata value labels are
converted to factors.  Ordinarily, \code{read.dta} will not convert
a variable to a factor unless a label is present for every level.  Use
\code{convert.factors = NA} to override this.  In any case the value
label and format information is stored as attributes on the returned
data frame.

Stata 8.0 introduced a system of 27 different missing data values.  If
\code{missing.type} is \code{TRUE} a separate list is created with the
same variable names as the loaded data.  For string variables the list
value is \code{NULL}.  For other variables the value is \code{NA}
where the observation is not missing and 0--26 when the observation is
missing.  This is attached as the \code{"missing"} attribute of the
returned value.
\end{Details}
\begin{Value}
a data frame with attributes.  These will include \code{"datalabel"},
\code{"time.stamp"}, \code{"formats"}, \code{"types"},
\code{"val.labels"}, \code{"var.labels"} and \code{"version"} and may
include \code{"label.table"}.  Possible versions are \code{5, 6, 7},
\code{-7} (Stata 7SE, \sQuote{format-111}), \code{8} (Stata 8 and 9,
\sQuote{format-113}) and \code{10} (Stata 10, \sQuote{format-114}).

The value labels in attribute \code{"val.labels"} name a table for
each variable, or are an empty string.  The tables are elements of the
named list attribute \code{"label.table"}: each is an integer vector with
names,
\end{Value}
\begin{Author}\relax
Thomas Lumley
\end{Author}
\begin{References}\relax
Stata Users Manual (versions 5 \& 6), Programming manual (version 7),
or online help (version 8, 9, 10) describe the format of the files.
Or at \url{http://www.stata.com/help.cgi?dta} and
\url{http://www.stata.com/help.cgi?dta_113}
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{write.dta}{write.dta}},
\code{\LinkA{attributes}{attributes}}
\code{\LinkA{Date}{Date}}
\code{\LinkA{factor}{factor}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
data(swiss)
write.dta(swiss,swissfile <- tempfile())
read.dta(swissfile)
\end{ExampleCode}
\end{Examples}

