read.acs {acs}R Documentation

Reads a comma-delimited file from the American Community Survey and creates an acs object with estimates, standard errors, and associated metadata.

Description

When passed a comma-delimited file from the U.S. Census American Community Survey (typically downloaded via the FactFinder website and unzipped), read.acs returns an acs object with estimates, standard errors, and associated metadata.

Most users will prefer to start with acs.fetch to import data; read.acs is maintained as a "legacy" function, primarily for use in situations where data is not available via the Census API.

Usage

read.acs(filename, endyear = "auto", span = "auto", col.names= "auto",
acs.units = "auto", geocols = "auto", skip = "auto")

Arguments

filename

the name of the .csv, .zip, or .txt file to be input

endyear

an integer (or "auto") indicating the latest year of the data in the survey (e.g., for data from the 2005-2009 5-year ACS data, endyear would be 2009)

span

an integer (should be 1, 3, or 5), or "auto" to have read.acs guess the span from the filename (e.g., for data from the 2005-2009 5-year ACS data, span would be 5)

col.names

a vector of column names to be used as acs.colnames for the object; defaults to "auto", which will result in auto-generated names from the headers lines of the input file

acs.units

a vector of factors indicating what sort of data is contained within each column of data ("count","dollars","proportion", "ratio", "other")

geocols

a vector of integers indicating which columns contain the geographic header information; defaults to "auto", which is the same as 3:1, which seems to be the standard for FactFinder-2 downloads

skip

an integer indicating how many rows to skip before processing the csv file; defaults to "auto", which will try to guess the proper value

Details

After executing a query on the U.S. Census American FactFinder site (http://factfinder2.census.gov), users can download their results as a zip file containing data in comma-delimited file format (for example, "ACS_10_5YR_B19013_with_ann.csv"). read.acs simplifies the creation of new acs objects from these files. The function uses some rudimentary algorithms to guess intelligently about values for metadata (such as endyear and geography), based on current file-format used by the Census "AmericanFactFinder 2" download site.

The specified filename can be an actual .csv file, or can be the name of a .zip file downloaded from the FactFinder site. If the latter, read.acs will extract the necessary data and leave the compressed zipfile in place.

As a default, read.acs assumes the first three columns will contain geographic header information, which seems to be the standard for the new Census American Factfinder download site. Users can also set different values for the geocols= to specify other columns for this geographic information. The function will use the first of these columns for geographic rownames to label estimates. (By default, then, this would be the third column of the actual file, since geocols=3:1. For files downloaded via the Census "legacy" version of FactFinder prior to 2012, users will probably want to specify geocols=4:1.

As for column names, by default read.acs will scan the file to determine how many of the initial rows contain "header" information, and will generate new acs.colnames by concatenating information found in these rows. Note that this can result in very long variable names, and users may want to modify the contents of acs.colnames after creation.

Alternatively, users can inspect downloaded csv files prior to import and specify the skip= option explicitly, as with read.csv and other read.XXX functions (i.e., the value of skip is equal to the number of rows prior to the last header row). Regardless of whether skip= is set or "auto", however, the column names will be created using all of the rows at the top of the file, even the "skipped" ones.

Finally, these new acs.colnames are used to guess intelligently about values for acs.units, but currently all this includes is a check for the word "dollars" in the names; if this is not found, the columns are assumed to be "counts".

When no other values are provided, read.acs will attempt to determine endyear and span from the filename.

Value

Returns a new acs-class object with estimates, standard errors (derived from the census 90% margins of error), and metadata associated with the survey,

Author(s)

Ezra Haber Glenn eglenn@mit.edu


[Package acs version 2.1.4 Index]