acs-class {acs}

Class "acs"

Description

The acs class provides a convenient wrapper for demographic data from the U.S. Census, especially the American Community Survey. Estimates and standard errors are kept together, along with geographic information and metadata necessary to manipulate and analyze data in this form.

Objects from the Class

acs objects can be created by calls of the form new("acs", ...), or through helper functions provided by the package (currently read.acs and acs.fetch), or from the output of subsetting or other calls on existing acs objects. Once created, acs objects can be manipulated through new methods to deal appropriately with common analytical tasks such as combining subgroups or geographies, mathematical operations on estimates, and computing (and plotting) confidence intervals.

Slots

endyear:

Object of class "integer" indicating the last year included in the dataset (e.g., 2012 for data from the 2008–2012 ACS)

span:

Object of class "integer" representing the number of years the dataset spans (e.g., 3 for data from the 2011–2013 ACS); for decennial census datasets (SF1 and SF3), span = 0.

geography:

Object of class "data.frame" containing columns extracted from the data's geographic header: typically includes geographic place names, census summary level values, and unique numeric identifiers, but can contain any geographic names or labels desired. When acs objects are created or modified, the first geography column will be used to label estimates and standard errors.

acs.colnames:

Object of class "character" giving the variable names for each column

modified:

Object of class "logical" to indicate whether the object has been modified since construction

acs.units:

Object of class "factor" designating the type of units in each column (e.g., count or percentage or dollars); only used minimally, to check appropriateness of some operations; mostly reserved for future functionality

currency.year:

Object of class "integer" indicating the year that all currency values have been adjusted to (by default the same as endyear, but able to be modified by the user for comparisons with other years; see currency.convert.)

estimate:

Object of class "matrix" holding the reported ACS estimates

standard.error:

Object of class "matrix" holding the calculated values of the standard errors for each estimate, derived from the reported 90% confidence intervals

Methods

acs.colnames

signature(object = "acs"): Standard accessor function; returns character vector

acs.units

signature(object = "acs"): Standard accessor function; returns factor vector

currency.year

signature(object = "acs"): Standard accessor function; returns integer

endyear

signature(object = "acs"): Standard accessor function; returns integer

estimate

signature(object = "acs"): Standard accessor function; returns matrix

geography

signature(object = "acs"): Standard accessor function; returns data.frame

modified

signature(object = "acs"): Standard accessor function; return logical

span

signature(object = "acs"): Standard accessor function; returns integer

standard.error

signature(object = "acs"): Standard accessor function; returns matrix

sum

signature(object = "acs"): Aggregates (adds) all estimates in the object, and adds the corresponding standard errors in a statistically appropriate way; returns new acs object

summary

signature(object = "acs"): Prints standard summary data on both estimates and standard errors

confint

signature(object = "acs"): Prints estimates with confidence intervals

[

signature(x = "acs"): subsetting works for acs objects using standard [i,j] square bracket notation, similar to two-dimensional matrices; returns a new acs object with estimates, standard errors, and associated metadata for "i" rows (geographies) and "j" columns (variable columns); essentially, subsetting for this class is structured to mirror standard operations on matrix objects

[<-

signature(x = "acs"): new values may be replaced/assigned to an existing acs object using standard [i,j] bracket notation. The assignment can accept a number of different forms: a valid acs object (including a subsetted one), a list of two matrices (ideally named "estimate" and "error" or "standard.error"), or a numeric object which may be coerced into a matrix (to be used as estimates, with zero-values assigned to corresponding standard errors).

In addition to these methods, new methods for basic arithmetic functions (+, -, *, /) have been provided to deal appropriately with combining estimates and standard errors.

Author(s)

Ezra Haber Glenn [e-mail]

Examples

showClass("acs")
# load some data from the ACS
data(kansas09)
str(kansas09)

# access slots
endyear(kansas09)
span(kansas09)
estimate(kansas09)[1:5,1:5]
standard.error(kansas09[1:5,1:5])


# subset
kansas09[1:4,6:9]

# more complicated subsets
kansas09[c("Linn County, Kansas", "Wilson County, Kansas") ,
   grep(pattern="21.years", x=acs.colnames(kansas09))]

# addition on estimates and errors
kansas09[1:4,25]+kansas09[1:4,49]

# can even multiply and divide
# males per female, by county
kansas09[1:4,2]/kansas09[1:4,26]

# (males<5 plus females<5) * 12
(kansas09[7,3]+kansas09[7,27]) * 12

# some replacement: males<5 as a percentage of all males
kansas09[,3]=kansas09[,3]/kansas09[,2]