acs

Provides a general toolkit for downloading, managing, analyzing, and presenting data from the U.S. Census, including SF1 (Decennial short-form), SF3 (Decennial long-form), and the American Community Survey (ACS). Confidence intervals provided with ACS data are converted to standard errors to be bundled with estimates in complex acs objects. Package provides new methods to conduct standard operations on acs objects and present/plot data in statistically appropriate ways.

Maintainer

Ezra Haber Glenn eglenn@mit.edu

Current version

The current version of the package is 2.1.4, released in February, 2019. This extremely minor update corrects a problem related to the api urls used by the Census.

No other aspects of the package were changed with this release.

Previous versions

Version 2.1.3 was released in March, 2018 to correct a problem related to acs.lookup for acs tables for 2016. This fix is more of a “workaround” than a true fix: starting with the 2016 release, the Census Bureau changed the format for the XML variable lookup tables and calls to acs.lookup (and acs.fetch) were failing; the quick solution was to simply use the 2015 lookup tables for these requests, which should be safe in most situations, since table numbers and variable codes generally do not change from year to year. (In some situations this assumption is not true: see https://www.census.gov/programs-surveys/acs/technical-documentation/table-and-geography-changes/2016/5-year.html for details.)

Prior to this, previous versions (2.1.3, released in March 2018; 2.1.2, released in September 2017; 2.1.0 and 2.1.1, both released in July 2017) were minor updates to replace the package’s dependency on RCurl (specifically, RCurl::urlGet and RCurl::url_exists) with similar httr functions and address some https/TLS incompatability issues between RCurl and users with Windows environments, all necessary to accommodate changes in the Census API format, including a shift to https transfer. Other changes included removing plyr from a “dependency” and simply importing the required “rbind.fill” function, and updating cbind/rbind options to be consistent with S3 methods.

In March, 2016, acs version 2.0 was released, considered a substantial update over the previous version 1.2 due to (1) a major expansion in the number of datasets available and (2) a modification to the acs.fetch and acs.lookup options, which now require a user to explicitly specify “endyear=” for all calls.

As of this version, the package provides full support for all ACS, SF1, and SF3 data currently available via the Census API, including ACS data from 2005-2015 and Decennial data from 1990, 2000, and 2010.

You can track development of the acs package at http://eglenn.scripts.mit.edu/citystate/.

Installation/Upgrading

Installation

To install the updated version, simply fire up an R session and type:

install.packages("acs", clean=T)

The package maintainer recommends two additional (optional) steps to improve performance:

Installing or migrating an api key

To use the package to download data via the American Community Survey application program interface (API), users need to request an API key from the Census. See http://www.census.gov/developers/tos/key_request.html.

The package includes a function, api.key.install, to allow users to save their key in the package data directory, where it can be found and used automatically for future sessions:

> # do this once, you never need to do it again
> api.key.install(key="592bc14cnotarealkey686552b17fda3c89dd389")

If a user has previously installed a key, it may be lost during the update process. If the “clean” option has been set as part of the update, the package configure scripts will attempt to migrate the key to a new location. Failing this, the install script will suggest that users run api.key.migrate() after installation, which might resolve the issue.

> api.key.migrate()

At worst, if both migration methods fail, you can simply re-run api.key.install() with your original key and be good to go.

Installing census lookup tables

To obtain variable codes and other metadata needed to access the Census API, both “acs.fetch” and “acs.lookup” must consult various XML lookup files, which are provided by the Census with each data release. As of version 2.0 these files are accessed online at run-time for each query (a change made to keep the package-size small to conform with CRAN policies). As an alternative to package-time installation of lookup tables, users may run “acs.tables.install()” after installation to download and archive all current tables (approximately 10MB, as of version 2.0 release).

> acs.tables.install()

Use of this function is completely optional and the package should work fine without it (assuming the computer is online and is able to access the lookup tables), but running it once will result in faster searches and quicker downloads for all subsequent sessions. (The results are saved and archived, so once a user has run the function, it is unnecessary to run again, unless the acs package is re-installed or updated.)

Upgrading

If you’ve previously installed the package, you can upgrade with:

update.packages("acs", clean=T)

Remember to re-run acs.tables.install() after upgrading (see above).

Use

The package includes a number of functions with advanced options, to allow users to work with data from the Census in any number of different ways. That said, the general workflow is fairly simple:

To learn more, consult the following:

Changes since previous version

Additional notes, details, issues