acs version 1.3: test-drive it now

Posted by Ezra Glenn on March 06, 2016

After far too long, we are nearing completion of version 1.3 of the acs package. As a special benefit to our loyal readers on CityState and members of the the acs.R mailing list,1 we are making available a special sneak-peak, pre-release version for you to try out. The biggest improvement is full support for all ACS, SF1, and SF3 data currently available via the Census API, including ACS data from 2005-2014 and Decennial data from 1990, 2000, and 2010. (See below for more info.)

1 Downloading and installing

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

> install.packages("", 
  clean=T, repos=NULL)

If you prefer to download it first, you can do so here. After downloading, you can install via the command line:

$ R CMD INSTALL acs_1.3.tar.gz --clean

or via an R session:

> install.packages(pkgs="acs_1.3.tar.gz", clean=T, repos=NULL)

2 Notes and updates

A few notes about this new package:

  • API Keys: by default, when R updates a package, it overwrites the old package files. Unfortunately, that is where archived api.keys get saved by api.key.install(). As part of the version 1.3 package installation, “configure” and “cleanup” scripts can be run which try to migrate the key to a new location. If this fails, the install script will suggest that users run api.key.migrate() after installation, which might resolve the issue. At worst, if both methods fail, a user can simply re-run api.key.install() with the original key and be good to go.
  • endyear now required: under the old package, acs.fetch and acs.lookup would default to endyear=2011 when no endyear was provided. This seemed smart at the time – 2011 was the most recent data available – but it is becoming increasingly absurd. One solution would have been to change the default to be whatever data is most recent, but that would have the unintended result of making the same script run differently from one year to the next: bad mojo. So the new preferred “version 1.3 solution” is to require users to explicitly indicate the endyear that they want to fetch each time. Note that this may require some changes to existing scripts.
  • ACS Data Updates: the package now provides on-board support for all endyears and spans currently available through the API, including:
    • American Community Survey 5-Year Data (2005-2009 through 2010-2014)
    • American Community Survey 3 Year Data (2013, 2012)
    • American Community Survey 1 Year Data (2014, 2013, 2012, 2011)

    See for more info, including guidance about which geographies are provided for each dataset.

  • Decennial Census Data: for the first time ever, the package now also includes the ability to download Decennial Data from the SF1 and SF3, using the same acs.fetch() function used for ACS data.
    • SF1/Short-Form (1990, 2000, 2010)
    • SF3/Long-Form (1990, 2000)2

    When fetched via acs.fetch(), this data is downloaded and converted to acs-class objects. (Note: standard errors for Decennial data will always be zero, which is technically not correct for SF3 survey data, but no margins of error are reported by the API.) See for more info.

    Also note that census support for the 1990 data is a bit inconsistent – the variable lookup tables were not in the same format as others, and far less descriptive information has been provided about table and variable names. This can make it tricky to find and fetch data, but if you know what you want, you can probably find it; looking in the files in package’s extdata directory might help give you a sense of what the variable codes and table numbers look like.

  • Other improvements/updates/changes:
    • CPI tables: the CPI tables used for currency.year() and currency.convert() have been updated to include data up through 2015.
    • acs.fetching with saved acs.lookup results: the results of acs.lookup can still be saved and passed to acs.fetch via the “variable=” option,3 with a slight change: under v. 1.2, the passed acs.lookup results would overrule any explicit endyear or span; with v. 1.3, the opposite is true (the endyear and span in the acs.lookup results are ignored by acs.fetch). This may seem insignificant, but it will eventually be important, when users want to fetch data from years that are more recent than the version of the package, and need to use old lookup results to do so.
    • divide.acs fixes: the package includes a more robust divide.acs() function, which handles zero denominators better and takes full advantage of the potential for reduced standard errors when dividing proportions.

Other than these points, everything should run the same as the acs package you’ve come to know and love, and all your old scripts and data objects should still be fine. (Again, with the one big exception that you’ll need to add “endyear=XXXX” to any calls to acs.fetch and acs.lookup.)

Have fun, feel free to mess around and use as you might normally, thanks for any problems you find or additional improvements you suggest, and by all means let me know if you spot anything amiss.

>  big.thanks=function( {
    for(i in 1:1000) {


1read: “in order to help test-drive this thing before releasing on CRAN…”

2SF3 was discontinued after 2000 and replaced with the ACS.

3did you even know this was possible…???

Comments are closed.