geo.make: Create a new geo.set object for use with the acs package.
In acs: Download, Manipulate, and Present American Community Survey and Decennial Data from the US Census

Description Usage Arguments Details Value Author(s) References See Also Examples

The geo.make function is used to create new user-specified geographies for use with the acs.fetch function of the acs package. At the most basic level, a user specifies some combination of existing census levels (state, county, county subdivision, place, tract, block group, msa, csa, puma, and more – see arguments), and the function returns a new geo.set object holding this information.

When specifying state, county, county subdivision, place, american indian area, and/or any of the state school district arguments, geo.make will accept either FIPS codes or common geographic names, and will try to match on partial strings; there is also limited support for regular expressions, but by default the searches are case sensitive and matches are expected at the start of names. (For example, geo.make(state="WA", county="Kits") should find Kitsap County, and the more adventurous yakima=geo.make(state="Washi", county=".*kima") should work to create the a geo.set for Yakima county.)

Other geographies (including tract, block.group, csa, msa, region, division, urban.area, necta, puma, zip.code. and/or congressional.district) can only be specified by FIPS codes (or "*" for all).

Tracts should be specified as six digit numbers, although initial zeroes may be removed; note that trailing zeroes are often removed in common usage, so a tract that may be referred to as "tract 243" is technically FIPS code 24300; likewise "tract 3872.01" is FIPS code 387201 for the purposes of geo.make.

geo.make(us, region, division, state, county, county.subdivision,
  place, tract, block.group, msa, csa, necta, urban.area,
  congressional.district, state.legislative.district.upper,
  state.legislative.district.lower, puma, zip.code,
  american.indian.area, school.district.elementary,
  school.district.secondary, school.district.unified,
  combine = F, combine.term = "aggregate", check = FALSE, key = "auto")

`us`	either the number 1, the character "*", or TRUE, indicating whether the geo.set should contain data for the entire U.S.; if selected, no other geography options may be specified; setting us corresponds to using census summary level 010.
`region`	a numeric code (or wildcard "*" for all) corresponding to the desired FIPS region (e.g., region=1 for Census Northeast Region); if selected, no other geography options may be specified; setting region corresponds to using census summary level 020.
`division`	a numeric code (or wildcard "*" for all) corresponding to the desired FIPS division (e.g., division=4 for Census West North Central Division); if selected, no other geography options may be specified; setting division corresponds to using census summary level 030.
`american.indian.area`	either the numeric code (or wildcard "*" for all) corresponding to the desired FIPS American Indian Area/Alaska Native Area/Hawaiian Home Land, or a character string to match in the names of these Census areas; if selected, no other geography options may be specified; setting american.indian.area corresponds to using census summary level 250.
`state`	either the two-digit numeric FIPS code for the state, the two-letter postal abbreviation, or a character string to match in the state name (or wildcard "*" for all); setting state without other options corresponds to using census summary level 040, but it may be used in conjunction with other summary levels below.
`county`	either the numeric FIPS code (or wildcard "*" for all) for the county or a character string to match in the county name; setting state and county without other options corresponds to using census summary level 050, but they may be used in conjunction with other summary levels below.
`county.subdivision`	either the numeric FIPS code (or wildcard "*" for all) for the county subdivision or a character string to match in the county subdivision name; setting state, county, and county.subdivision without other options corresponds to using census summary level 060.
`place`	either the numeric FIPS code (or wildcard "*" for all) for the place or a character string to match in the place name; setting state and place without other options corresponds to using census summary level 160.
`tract`	a six digit numeric FIPS code (or wildcard "*" for all) for the census tract, including trailing zeroes; remove decimal points; leading zeroes may be omitted; see description; tract may be used with state and county to create geo.sets for census summary levels 140, and with state, county, and block.group for summary level 150.
`block.group`	the numeric FIPS code (or wildcard "*" for all) for the block.group; block.group may be used with state, county, and tract to create geo.sets for census summary levels 150.
`msa`	a numeric code (or wildcard "*" for all) corresponding to the desired FIPS metropolitan statistical area/micropolitan statistical area (e.g., msa=10100 for Aberdeen, SD micropolitan statistical area); setting msa without other options corresponds to using census summary level 310, but it may be used in conjunction with state for summary level 320.
`csa`	a numeric code (or wildcard "*" for all) corresponding to the desired FIPS combined statistical area (e.g., csa=104 for Census Albany-Schenectady-Amsterdam, NY CSA); setting csa without other options corresponds to using census summary level 330, but it may be used in conjunction with state for summary level 340.
`necta`	a numeric code (or wildcard "*" for all) corresponding to the desired FIPS New England City and Town Area (e.g., necta=77650 for Rutland, VT Micropolitan NECTA); if selected, no other geography options may be specified; setting necta corresponds to using census summary level 350.
`urban.area`	a numeric code (or wildcard "*" for all) corresponding to the desired FIPS urban area (e.g., urban.area=3169 for Aromas, CA Urban Cluster); if selected, no other geography options may be specified; setting urban.area corresponds to using census summary level 400.
`congressional.district`	a numeric code (or wildcard "*" for all) corresponding to the desired FIPS congressional district (e.g., state="ME" and congressional.district=1 for Maine's first congressional district); setting state and congressional.district without other options corresponds to using census summary level 500, but they may be used in conjunction with county for summary level 510.
`state.legislative.district.upper`	a numeric or character code (or wildcard "*" for all) corresponding to the desired FIPS state legislative district (upper chamber); these codes vary from state to state, and are sometimes numbers (1, 2, 3, etc. in Massachusetts) and sometimes letters ("A", "B", "C", etc. in Alaska); setting state and state.legislative.district.upper without other options corresponds to using census summary level 610.
`state.legislative.district.lower`	a numeric or character code (or wildcard "*" for all) corresponding to the desired FIPS state legislative district (lower chamber); these codes vary from state to state, and are sometimes numbers (1, 2, 3, etc. in Massachusetts) and sometimes letters ("A", "B", "C", etc. in Alaska); setting state and state.legislative.district.lower without other options corresponds to using census summary level 620.
`puma`	a numeric code (or wildcard "*" for all) corresponding to the desired FIPS public use microdata area (e.g., state=10 and puma=103 for PUMA 103 in Delaware); setting state and puma without other options corresponds to using census summary level 795.
`zip.code`	a numeric code (or wildcard "*" for all) corresponding to the desired zip code tabulation area (e.g., zip.code=91303 for zip code 91303); if selected, no other geography options may be specified; setting zip.code corresponds to using census summary level 860.
`school.district.elementary`	a numeric code (or wildcard "*" for all) corresponding to the desired FIPS state school district (elementary), or a character string to search for in the names of these districts; setting state and school.district.elementary without other options corresponds to using census summary level 950.
`school.district.secondary`	a numeric code (or wildcard "*" for all) corresponding to the desired FIPS state school district (secondary), or a character string to search for in the names of these districts; setting state and school.district.secondary without other options corresponds to using census summary level 960.
`school.district.unified`	a numeric code (or wildcard "*" for all) corresponding to the desired FIPS state school district (unified), or a character string to search for in the names of these districts; setting state and school.district.unified without other options corresponds to using census summary level 970.
`combine`	a logical flag to indicate whether the component geographies of the geo.set are to be combined when data is downloaded; see details.
`combine.term`	a character string to provide a label for aggregate geography, if data is combined
`check`	logical flag indicating whether to run a check for valid geographies with Census API; defaults to FALSE; when TRUE, a current API key must be provided or installed
`key`	when check=T and no API key has been previously installed through `api.key.install`, a string key may be provided here

In addition to creating individual combinations of census geographies, users can pass vector arguments (with recycling) to geo.make to create sets of geographies. Important: each set of arguments must match with exactly one known Census geography: if, for example, the names of two places (or counties, or whatever) would both match, the geo.make function will return an error. (To the development team, this seemed preferable to simply including both matches, since all sorts of place names might match a string, and it is doubtful a user really wants them all.) The one exception to this "single match" rule is that for the smallest level of geography specified, a user can enter "*" to indicate that all geographies at that level should be selected.

When creating new geographies, note, too, that not all combinations are valid. In particular the package attempts to follow paths through the Census summary levels (such as summary level 140: "state-county-tract" or summary level 160: "state-place"). So when specifying, for example, state, county, and place, the county will be ignored.

Note: when a geo.set with "combine=T" is passed to acs.fetch, downloaded data will be aggregated in the resulting acs abject. Some users may therefore wish to specify "one.zero=T" as an additional argument to acs.fetch; see sum-methods.

The following table may be helpful in figuring out which options to set for which Census summary levels. For more information on which datasets and endyear/span combinations are available for each summary level, see http://www.census.gov/data/developers/data-sets.html (click each dataset and search for "Examples and Supported Geography").

SUMMARY LEVEL	ARGUMENTS REQUIRED
010	us
020	region
030	division
040	state
050	state, county
060	state, county, county.subdivision
140	state, county, tract
150	state, county, tract, block.group
160	state, place
250	american.indian.area
310	msa
320	state, msa
330	csa
340	state, csa
350	necta
400	urban.area
500	state, congressional.district
510	state, congressional.district, county
610	state, state.legislative.district.upper
620	state, state.legislative.district.lower
795	state, puma
860	zip.code
950	state, school.district.elementary
960	state, school.district.secondary
970	state, school.district.unified

All other arguments/combinations will either be ignored or result in a failure.

Returns a geo.set class object.

Ezra Haber Glenn eglenn@mit.edu

"acs.R: An R Package for Neighborhood-Level Data from the U.S. Census." Ezra Haber Glenn, Department of Urban Studies and Planning, Massachusetts Institute of Technology. Presented at the Computers in Urban Planning and Urban Management Conference, July 6, 2011. http://papers.ssrn.com/sol3/papers.cfm?abstract_id=2171390.
Census API Supported Geography: http://www.census.gov/data/developers/data-sets.html

geo.set-class

# some single-state geo.sets
washington=geo.make(state=53)
alabama=geo.make(state="Alab")

# a county match
yakima=geo.make(state="WA", county="Yakima")
yakima

# a multiple-county geo.set
psrc=geo.make(state="WA", county=c(33,35,53,61))
psrc

# combine geo.sets
north.mercer.island=geo.make(state=53, county=33, tract=c(24300,24400))
optional.tract=geo.make(state=53, county=33, tract=24500)
# add in one more tract to create new, larger geo
north.mercer.island.plus=north.mercer.island + optional.tract

# using wildcards

# all unified school districts in Kansas
geo.make(state="KS", school.district.unified="*")

# all state house districts in Alaska
geo.make(state="AK", state.legislative.district.lower="*")

# all tracts in Kings County, NY
geo.make(state="NY", county="King", tract="*")