get_areas_near_coordinates: Make a tibble of census areas closest to a user-specified...

In sociome: Operationalizing Social Determinants of Health Data for Researchers

Make a tibble of census areas closest to a user-specified center

Description

Returns a tibble containing the census areas whose centers of population are closest to some user-specified center. To specify the center, the user can manually enter longitude/latitude coordinates or use the helper function lon_lat_from_area() to automatically grab the longitude/latitude coordinates of the center of population of an area. The cutoff point for how many areas will be return depends on the function used.

Usage

areas_in_radius(
  geography = c("state", "county", "tract", "block group"),
  center = lon_lat_from_area(state = "DC"),
  radius = 5,
  units = "miles",
  measure_from = "center of population",
  year = 2020,
  distance_fun = geosphere::distVincentyEllipsoid,
  batch_size = 50L
)

closest_n_areas(
  geography = c("state", "county", "tract", "block group"),
  center = lon_lat_from_area(state = "DC"),
  n = 50,
  measure_from = "center of population",
  year = 2020,
  distance_fun = geosphere::distVincentyEllipsoid,
  units = NULL,
  batch_size = 50L
)

closest_population(
  geography = c("state", "county", "tract", "block group"),
  center = lon_lat_from_area(state = "DC"),
  population = 1e+06,
  measure_from = "center of population",
  year = 2020,
  distance_fun = geosphere::distVincentyEllipsoid,
  units = NULL,
  batch_size = 50L
)

Arguments

geography	The type of census areas that the resulting table will contain. One of c("state", "county", "tract", "block group").
center	The longitude/latitude coordinates of the center of the circle. A double vector of length 2 whose elements are finite numbers. Passed to the y argument of geosphere::distm(). The first element is the longitude coordinate (positive for west, negative for east). The second element is the latitude coordinate (positive for north, negative for south). The convenience function lon_lat_from_area() can be used to obtain the longitude/latitude coordinates of the center of population of a user-specified census area. Defaults to the center of population of the District of Columbia according to the 2020 decennial census.
radius	A single, non-negative number specifying the radius of the circle. Defaults to 5.
units	A single string specifying the units of the resulting distance column. If NULL, the units package does not need to be installed, and units will be meters. Otherwise, this will be passed to the value argument of units::set_units(mode = "standard"). For areas_in_radius(), this also used for the units of radius.
measure_from	Currently can only be "center of population", the default.
year	Must be 2020, 2010, or 2000. Defaults to 2020.
distance_fun	Passed to the fun argument of geosphere::distm(). Defaults to geosphere::distVincentyEllipsoid, which results in the most accurate measurement but is also the slowest.
batch_size	The number of distances calculated in each iterative call to geosphere::distm(). When the request is satisfied, these functions stop calculating distances in order to prevent potentially hundreds of thousands of unnecessary calculations. Defaults to 50.
n	A single positive integer specifying how many of the areas closest to center should be gathered. Defaults to 50.
population	A single positive integer specifying the target total population of the areas returned. See Details.

Details

areas_in_radius() returns all areas whose centers of population are within the user-specified radius around center.

closest_n_areas() returns the top n areas whose centers of population are closest areas to center.

Conceptually, closest_population() sequentially gathers the next closest area to center until the total population of the areas meets or exceeds population.

Distances are determined with geosphere::distm().

Requires the packages USpopcenters and geosphere to be installed. Requires the units to be installed unless units = NULL.

Centers of population are based on the decennial census data. Only states, counties, tracts, and block groups are currently supported. See the documentation of the USpopcenters package and https://www.census.gov/geographies/reference-files/time-series/geo/centers-population.html for more information.

Value

A tibble with each of the columns found in the corresponding USpopcenters table, with two columns appended:

geoid - all FIPS code columns combined with paste0().

distance - the number of units the area's LONGITUDE/LATITUDE center of population is away from the coordinates given in center.

See Also

lon_lat_from_area()

Examples

# All states whose centers of population are within 300 kilometers of the
# center of population of New York County, New York (i.e, Manhattan):
areas_in_radius(
  geography = "state",
  center = lon_lat_from_area(state = "NY", county = "New York"),
  radius = 300,
  units = "km"
)

# The four census tracts whose centers of population are closest to the
# Four Corners (distance column is in meters due to setting units = NULL):
closest_n_areas("tract", center = c(-109.0452, 36.9991), n = 4, units = NULL)

# The counties closest to center of population of Kauai County, Hawaii whose
# total population reaches 3 million people:
closest_population(
  geography = "county",
  center = lon_lat_from_area("15007"),
  population = 3e6,
  units = "barleycorns"
)

sociome documentation built on April 26, 2023, 1:13 a.m.