| geo.make {acs} | R Documentation |
Create a new geo.set object for use with the acs package.
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
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")
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=T and no API key has been previously installed
through |
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=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.
Value
Returns a geo.set class object.
Author(s)
Ezra Haber Glenn eglenn@mit.edu
References
"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
See Also
Examples
# 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="*")