\Header{data}{Data Sets}
\alias{print.packageIQR}{data}
\keyword{documentation}{data}
\keyword{datasets}{data}
\begin{Description}\relax
Loads specified data sets, or list the available data sets.
\end{Description}
\begin{Usage}
\begin{verbatim}
data(..., list = character(0), package = .packages(),
     lib.loc = NULL, verbose = getOption("verbose"),
     envir = .GlobalEnv)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{...}] a sequence of names or literal character strings.
\item[\code{list}] a character vector.
\item[\code{package}] a character vector giving the packages to look
in for data sets.  By default, all packages in the search path are
used, then the \file{data} subdirectory (if present) of the current
working directory.
\item[\code{lib.loc}] a character vector of directory names of \R{} libraries,
or \code{NULL}.  The default value of \code{NULL} corresponds to all
libraries currently known.  If the default is used, the loaded
packages are searched before the libraries.
\item[\code{verbose}] a logical.  If \code{TRUE}, additional diagnostics are
printed.
\item[\code{envir}] the \link{environment} where the data should be loaded.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Currently, four formats of data files are supported:

\Enumerate{
\item files ending \file{.R} or \file{.r} are
\code{\Link{source}()}d in, with the \R{} working directory changed
temporarily to the directory containing the respective file.

\item files ending \file{.RData} or \file{.rda} are
\code{\Link{load}()}ed.

\item files ending \file{.tab}, \file{.txt} or \file{.TXT} are read
using \code{\Link{read.table}(..., header = TRUE)}, and hence
result in a data frame.

\item files ending \file{.csv} or \file{.CSV} are read using
\code{\Link{read.table}(..., header = TRUE, sep = ";")},
and also result in a data frame.
}
If more than one matching file name is found, the first on this list
is used.

The data sets to be loaded can be specified as a sequence of names or
character strings, or as the character vector \code{list}, or as both.

For each given data set, the first two types (\file{.R} or \file{.r},
and \file{.RData} or \file{.rda} files) can create several variables
in the load environment, which might all be named differently from the
data set.  The second two (\file{.tab}, \file{.txt}, or \file{.TXT},
and \file{.csv} or \file{.CSV} files) will always result in the
creation of a single variable with the same name as the data set. 

If no data sets are specified, \code{data} lists the available data
sets.  It looks for a new-style data index in the \file{Meta} or, if
this is not found, an old-style \file{00Index} file in the \file{data}
directory of each specified package, and uses these files to prepare a
listing.  If there is a \file{data} area but no index, available data
files for loading are computed and included in the listing, and a
warning is given: such packages are incomplete.  The information about
available data sets is returned in an object of class
\code{"packageIQR"}.  The structure of this class is experimental.  In
earlier versions of R, an empty character vector was returned along
with listing available data sets.

If \code{lib.loc} is not specified, the data sets are searched for
amongst those packages already loaded, followed by the \file{data}
directory (if any) of the current working directory and then packages
in the specified libraries.  If \code{lib.loc} \emph{is} specified,
packages are searched for in the specified libraries, even if they are
already loaded from another library.

To just look in the \file{data} directory of the current working
directory, set \code{package = NULL}.
\end{Details}
\begin{Value}
a character vector of all data sets specified, or information about
all available data sets in an object of class \code{"packageIQR"} if
none were specified.
\end{Value}
\begin{Note}\relax
The data files can be many small files.  On some file systems it is
desirable to save space, and the files in the \file{data} directory of
an installed package can be zipped up as a zip archive
\file{Rdata.zip}.  You will need to provide a single-column file
\file{filelist} of file names in that directory.

One can take advantage of the search order and the fact that a
\file{.R} file will change directory.  If raw data are stored in
\file{mydata.txt} then one can set up \file{mydata.R} to read
\file{mydata.txt} and pre-process it, e.g., using \code{transform}.
For instance one can convert numeric vectors to factors with the
appropriate labels.  Thus, the \file{.R} file can effectively contain
a metadata specification for the plaintext formats.
\end{Note}
\begin{SeeAlso}\relax
\code{\Link{help}} for obtaining documentation on data sets,
\code{\Link{save}} for \emph{creating} the second (\file{.rda}) kind
of data, typically the most efficient one.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
require(utils)
data()                      # list all available data sets
data(package = "base")      # list the data sets in the base package
data(USArrests, "VADeaths") # load the data sets 'USArrests' and 'VADeaths'
help(USArrests)             # give information on data set 'USArrests'
\end{ExampleCode}
\end{Examples}

