Map Geographies

This notebooks demonstrates some of the different geographies for which we can download shapefiles using the censusdis.maps.ShapeReader.read_cb_shapefile API.

These shapefiles are generally very useful for plotting. For even higher resolution shapefiles more suited for tasks like spatially joining data, the censusdis.maps.ShapeReader.read_shapefile API is available.

Imports and configuration

# So we can run from within the censusdis project and find the packages we need.
import os
import sys

sys.path.append(
    os.path.join(os.path.abspath(os.path.join(os.path.curdir, os.path.pardir)))
)

import os

import geopandas as gpd
import matplotlib.pyplot as plt

from typing import Iterable, Optional

from censusdis.states import STATE_NJ, STATE_AK, STATE_HI, ALL_STATES_AND_DC
from censusdis.maps import ShapeReader, plot_us_boundary
import censusdis.maps as cmap

# We are going to provide a path for our shape file
# reader to cache the shapefiles it downloads locally.
# This is optional, and if we don't provide this when
# we construct the reader, a default location will be
# selected for us.
SHAPEFILE_ROOT = os.path.join(os.environ["HOME"], "data", "shapefiles")

# Make sure it is there.
os.makedirs(SHAPEFILE_ROOT, exist_ok=True)

STATE = STATE_NJ
# For small geographies we may want to plot only one county.
COUNTY_ESSEX = "013"
YEAR = 2020

reader = ShapeReader(SHAPEFILE_ROOT, YEAR)

# For plotting the country so we can see where other
# geographies are in reference to states.
gdf_states = reader.read_cb_shapefile("us", "state")
gdf_states = gpd.GeoDataFrame(gdf_states[gdf_states.STATEFP.isin(ALL_STATES_AND_DC)])

def plot(gdf, geo: str, in_geo: str):
    ax = gdf.boundary.plot(linewidth=0.5)

    ax.set_title(f"{YEAR} {geo} in {in_geo}")

    ax.axis("off")


def plot_usa(
    gdf,
    geo: str,
    in_geo: str = "the United States",
    *,
    plot_states: bool = True,
    state_filter: Optional[Iterable[str]] = None,
):
    if "STATEFP" in gdf.columns:
        gdf = gdf[gdf.STATEFP.isin(ALL_STATES_AND_DC)]

    ax = plot_us_boundary(gdf, linewidth=0.5)

    if plot_states:
        if state_filter is not None:
            gdf_plot_states = gdf_states[gdf_states.STATEFP.isin(state_filter)]
        else:
            gdf_plot_states = gdf_states

        ax = plot_us_boundary(gdf_plot_states, ax=ax, edgecolor="black", linewidth=0.5)

    ax.set_title(f"{YEAR} {geo} in {in_geo}")

    ax.axis("off")

Geographies within the State Level

These are smaller geographies for which we shapefiles are provided on a state-by-state basis. When we query them, we have to specify the state we are interested in.

Block Groups (geography="bg")

gdf = reader.read_cb_shapefile(STATE, "bg")

plot(gdf[gdf.COUNTYFP == COUNTY_ESSEX], "Block Groups", "Essex County, NJ")

Census Tracts (geography="tract")

gdf = reader.read_cb_shapefile(STATE, "tract")

plot(gdf[gdf.COUNTYFP == COUNTY_ESSEX], "Census Tracts", "Essex County, NJ")

County Subdivisions (geography="cousub")

gdf = reader.read_cb_shapefile(STATE, "cousub")

plot(gdf[gdf.COUNTYFP == COUNTY_ESSEX], "County Subdivisions", "Essex County, NJ")

plot_usa(gdf, "County Subdivisions", "New Jersey", state_filter=[STATE_NJ])

Places (geography="place")

gdf = reader.read_cb_shapefile(STATE, "place")

plot_usa(gdf, "Places", "New Jersey", state_filter=[STATE_NJ])

State and Sub-State Geographies Queried at the National Level

Each of these geographies is entirely enclosed in a single state, but there are few enough of them that they are published in a single shapefile for the whole country. For these, we specify "us" instead of a state as the first argument to our query.

Counties (geography="county")

gdf = reader.read_cb_shapefile("us", "county")

plot_usa(
    gdf[gdf.STATEFP == STATE_NJ], "Counties", "New Jersey", state_filter=[STATE_NJ]
)

plot_usa(gdf, "Counties")

States (geography="state")

gdf = reader.read_cb_shapefile("us", "state")

plot_usa(gdf, "States", plot_states=False)

Top-Level Geographies not Contained in Any State

These geographies are queried at the national level. They do not belong to any particular state and don’t have any column like STATEFP that associates them with a state.

Metropolitan Statistical Areas / Micropolitan Statistical Areas (geography="cbsa")

gdf = reader.read_cb_shapefile("us", "cbsa")

plot_usa(gdf, "Metropolitan Statistical Areas / Micropolitan Statistical Areas\n")

Combined Statistical Areas (geography="csa")

gdf = reader.read_cb_shapefile("us", "csa")

plot_usa(gdf, "Combined Statistical Areas")

Metropolitan Divisions (geography="metdiv")

gdf = reader.read_cb_shapefile("us", "metdiv")

plot_usa(gdf, "Metropolitan Divisions")

Divisions (geography="division")

gdf = reader.read_cb_shapefile("us", "division")

plot_usa(gdf, "Divisions", plot_states=False)

Regions (geography="region")

gdf = reader.read_cb_shapefile("us", "region")

plot_usa(gdf, "Regions", plot_states=False)

American Indian / Alaska Native / Native Hawaiian Areas (geography="aiannh")

gdf = reader.read_cb_shapefile("us", "aiannh")

plot_usa(gdf, "American Indian / Alaska Native / Native Hawaiian Areas")

American Indian Tribal Subdivisions (geography="aitsn")

gdf = reader.read_cb_shapefile("us", "aitsn")

plot_usa(gdf, "American Indian Tribal Subdivisions")

Alaska Native Regional Corporations ((geography="anrc")

# An atypical naming convention is used here for the first
# arg.
gdf = reader.read_cb_shapefile("02", "anrc")

plot_usa(gdf, "Alaska Native Regional Corporations", state_filter=[STATE_AK])

Tribal Census Tracts (geography="ttract")

gdf = reader.read_cb_shapefile("us", "ttract")

plot_usa(gdf, "Tribal Census Tracts")

Tribal Block Groups (geography="tbg")

gdf = reader.read_cb_shapefile("us", "tbg")

plot_usa(gdf, "Tribal Block Groups")