geo.make: Create a new geo.set object for use with the acs package.

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

View source: R/geo-make.R

Description

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.

Usage

1
2
3
4
5
6
7
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 = FALSE, combine.term = "aggregate", check = FALSE, key = api.key.load())

Arguments

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=TRUE and no API key has been previously installed through api.key.install, a string key may be provided here

Details

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=TRUE" is passed to acs.fetch, downloaded data will be aggregated in the resulting acs abject. Some users may therefore wish to specify "one.zero=TRUE" 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.

Value

Returns a geo.set class object.

Author(s)

Ezra Haber Glenn [email protected]

References

  1. "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.

  2. Census API Supported Geography: http://www.census.gov/data/developers/data-sets.html

See Also

geo.set-class

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# 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="*")

nealrichardson/acs documentation built on May 23, 2019, 1:30 p.m.