1\name{csv.get}
2\alias{csv.get}
3\title{Read Comma-Separated Text Data Files}
4\description{
5  Read comma-separated text data files, allowing optional translation
6  to lower case for variable names after making them valid S names.
7  There is a facility for reading long variable labels as one of the
8  rows.  If labels are not specified and a final variable name is not
9  the same as that in the header, the original variable name is saved as
10  a variable label.
11}
12\usage{
13csv.get(file, lowernames=FALSE, datevars=NULL, datetimevars=NULL,
14        dateformat='\%F',
15        fixdates=c('none','year'), comment.char="", autodates=TRUE,
16        allow=NULL, charfactor=FALSE,
17        sep=',', skip=0, vnames=NULL, labels=NULL, \dots)
18}
19\arguments{
20  \item{file}{the file name for import.}
21  \item{lowernames}{set this to \code{TRUE} to change variable names to
22    lower case.}
23  \item{datevars}{character vector of names (after \code{lowernames} is
24    applied) of variables to consider as a factor or character vector
25    containing dates in a format matching \code{dateformat}.  The
26    default is \code{"\%F"} which uses the yyyy-mm-dd format.}
27  \item{datetimevars}{character vector of names (after \code{lowernames}
28	is applied) of variables to consider to be date-time variables, with
29	date formats as described under \code{datevars} followed by a space
30	followed by time in hh:mm:ss format.  \code{chron} is used to store
31	such variables.  If all times in the variable
32	are 00:00:00 the variable will be converted to an ordinary date variable.}
33  \item{dateformat}{for \code{cleanup.import} is the input format (see
34    \code{\link{strptime}})}
35  \item{fixdates}{for any of the variables listed in \code{datevars}
36    that have a \code{dateformat} that \code{cleanup.import} understands,
37    specifying \code{fixdates} allows corrections of certain formatting
38    inconsistencies before the fields are attempted to be converted to
39    dates (the default is to assume that the \code{dateformat} is followed
40    for all observation for \code{datevars}).  Currently
41    \code{fixdates='year'} is implemented, which will cause 2-digit or
42    4-digit years to be shifted to the alternate number of digits when
43    \code{dateform} is the default \code{"\%F"} or is \code{"\%y-\%m-\%d"},
44    \code{"\%m/\%d/\%y"}, or \code{"\%m/\%d/\%Y"}.  Two-digits years are
45	padded with \code{20} on the left.  Set \code{dateformat} to the
46	desired format, not the exceptional format.}
47  \item{comment.char}{a character vector of length one containing a
48    single character or an empty string.  Use '""' to turn off the
49    interpretation of comments altogether.}
50  \item{autodates}{Set to true to allow function to guess at which
51    variables are dates}
52  \item{allow}{a vector of characters allowed by \R that should not be
53    converted to periods in variable names.  By default, underscores in
54    variable names are converted to periods as with \R before version
55    1.9.}
56  \item{charfactor}{set to \code{TRUE} to change character variables to
57	factors if they have fewer than n/2 unique values.  Blanks and null
58	strings are converted to \code{NA}s.}
59  \item{sep}{field separator, defaults to comma}
60  \item{skip}{number of records to skip before data start.  Required if
61	\code{vnames} or \code{labels} is given.}
62  \item{vnames}{number of row containing variable names, default is one}
63  \item{labels}{number of row containing variable labels, default is no labels}
64  \item{\dots}{arguments to pass to \code{read.csv} other than
65	\code{skip} and \code{sep}.}
66}
67\details{
68  \code{csv.get} reads comma-separated text data files, allowing optional
69  translation to lower case for variable names after making them valid S
70  names.  Original possibly non-legal names are taken to be variable
71  labels if \code{labels} is not specified.  Character or factor
72  variables containing dates can be converted to date variables.
73  \code{cleanup.import} is invoked to finish the job.
74}
75\value{a new data frame.}
76\author{Frank Harrell, Vanderbilt University}
77\seealso{
78  \code{\link{sas.get}}, \code{\link{data.frame}},
79  \code{\link{cleanup.import}}, \code{\link{read.csv}},
80  \code{\link{strptime}}, \code{\link{POSIXct}}, \code{\link{Date}}
81}
82\examples{
83\dontrun{
84dat <- csv.get('myfile.csv')
85
86# Read a csv file with junk in the first row, variable names in the
87# second, long variable labels in the third, and junk in the 4th row
88dat <- csv.get('myfile.csv', vnames=2, labels=3, skip=4)
89}
90}
91\keyword{manip}
92\keyword{IO}
93\keyword{file}
94