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]