censusdis.maps

Utilities for loading and rendering maps.

This module relies on shapefiles from the US Census, which it downloads as needed and caches locally.

exception censusdis.maps.MapException[source]

Bases: Exception

class censusdis.maps.ShapeReader(shapefile_root: Optional[str] = None, year: int = 2020, auto_fetch: bool = True)[source]

Bases: object

A class for reading shapefiles into GeoPandas GeoDataFrames.

See the demo notebooks for more details. The shapefiles need to already have been downloaded to the local machine. We may add a lazy option in the future that will fetch them if they don’t exist.

Parameters

  • shapefile_root – The location in the filesystem where shapefiles are stored.

  • year – The year we want shapefiles for,

  • auto_fetch – If True then fetch remote shape files as needed.

read_cb_shapefile(shapefile_scope: str, geography: str, resolution: str = '500k', crs=None) → <Mock name='mock.GeoDataFrame' id='140304024888512'>[source]

Read the cartographic boundaries of a given geography.

These are smaller files suited for plotting maps, as compared to those returned by read_shapefile(), which returns higher resolution geometries.

The files are read from the US Census servers and cached locally. They are in most cases the same files you can download manually from https://www.census.gov/geographies/mapping-files/time-series/geo/cartographic-boundary.2020.html or similar URLs for other years.

Individual files the API may download follow a naming convention that has evolved a bit over time. So for example a 2010 census tract cartographic bounds file for New Jersey at 500,000:1 resolution would be found at https://www2.census.gov/geo/tiger/GENZ2010/gz_2010_34_140_00_500k.zip whereas a similar file for 2020 would be at https://www2.census.gov/geo/tiger/GENZ2020/shp/cb_2020_34_tract_500k.zip

This method knows many of the subtle changes that have occurred over the years, so you should mostly not have to worry about them. It is unlikely it knows them all, so please submit an issue at https://github.com/vengroff/censusdis/issues if you find otherwise.

Once read, the files are cached locally so that when we reuse the same files we do not have to go back to the server.

Parameters

  • shapefile_scope – The geography that is covered by the entire shapefile. In some cases, this is a state, e.g. STATE_NJ. For cases where files are available for the entire country, the string “us” is typically used. In some rare cases, like for the Alaska Native Regional Corporations ("anrc") geography, other strings like "02" are used. See the dowload links at https://www.census.gov/geographies/mapping-files/time-series/geo/cartographic-boundary.2020.html if you need to debug issues with a given geography.

  • geography – The geography we want to download bounds for. Supported geometries are “state’, “county”, “cousub” (county subdivision), “tract”, and “bg” (block group)

  • resolution – What resolution shapes should we use. Permitted options are “500k”, “5m”, and “20m” for 1:500,000, 1:5,000,000, and 1:20,000,000 resolution respectively. Availability varies, but for most geographies “500k” is available even if others are not.

  • crs – The crs to make the file to. If None, use the default crs of the shapefile. Setting this is useful if we plan to merge the resulting GeoDataFrame with another so we can make sure they use the same crs.

Returns

  • A gpd.GeoDataFrame containing the boundaries of the requested

  • geometries.

read_shapefile(shapefile_scope: str, geography: str, crs=None)[source]

Read the geometries of geographies.

This method reads maps suitable for use with geometric joins and queries of various types. If you are only interested in plotting maps, the read_cb_shapefile() method may be more suitable.

The files are read from the US Census servers and cached locally. They are in most cases the same files you can download manually from https://www.census.gov/cgi-bin/geo/shapefiles/index.php.

Individual files the API may download follow a naming convention that has evolved a bit over time. So for example a 2010 block group file for New Jersey would be found at https://www2.census.gov/geo/tiger/TIGER2010/BG/2010/tl_2010_34_bg10.zip whereas a similar file for 2020 would be at https://www2.census.gov/geo/tiger/TIGER2020/BG/tl_2020_34_bg.zip.

This method knows many of the subtle changes that have occurred over the years, so you should mostly not have to worry about them. It is unlikely it knows them all, so please submit an issue at https://github.com/vengroff/censusdis/issues if you find otherwise.

Once read, the files are cached locally so that when we reuse the same files we do not have to go back to the server.

Parameters

  • shapefile_scope – The geography that is covered by the entire shapefile. In some cases, this is a state, e.g. STATE_NJ. For cases where files are available for the entire country, the string “us” is typically used. In some rare cases, like for the Alaska Native Regional Corporations ("anrc") geography, other strings like "02" are used. See the dowload links at https://www.census.gov/geographies/mapping-files/time-series/geo/cartographic-boundary.2020.html if you need to debug issues with a given geography.

  • geography – The geography we want to download bounds for. Supported geometries are “state’, “county”, “cousub” (county subdivision), “tract”, and “bg” (block group). Other geometries as defined by the US Census may work, but have not been thoroughly tested.

  • crs – The crs to make the file to. If None, use the default crs of the shapefile. Setting this is useful if we plan to merge the resulting GeoDataFrame with another so we can make sure they use the same crs.

Returns

  • A gpd.GeoDataFrame containing the requested

  • geometries.

property shapefile_root: str

The path at which shapefiles are cached locally.

censusdis.maps.clip_to_states(gdf, gdf_state_bounds)[source]

Clip every geometry in a gdf to the state it belongs to, from the states in the state bounds.

We clip to state bounds so that we don’t plot areas outside the state. Typically, this clips areas that extend out into the water in coastal areas so we don’t get strange artifacts in the water in plots.

The way we tell what state an input geometry belongs to is by looking at the STATEFP column for that geometry’s row in the input.

Parameters

  • gdf – The input geometries.

  • gdf_state_bounds – The state bounds.

Returns

  • The input geometries where each is clipped to the bounds

  • of the state to which it belongs.

censusdis.maps.plot_us(gdf: <Mock name='mock.GeoDataFrame' id='140304024888512'>, *args, do_relocate_ak_hi_pr: bool = True, **kwargs)[source]

Plot a map of the US with AK and HI relocated.

This function will move and scale AK and HI so that they are plotted at the lower left of the other 48 states, just below CA, AZ, and NM.

It also moves the Aleutian islands that are west of -180° longitude so that they are plotted next to the rest of AK. Otherwise, they tend to be plotted at longitudes just less than +180°, which creates visual discontinuities.

Parameters

  • gdf – The geometries to be plotted.

  • do_relocate_ak_hi_pr – If True try to relocate AK, HI, and PR. Otherwise, still wrap the Aleutian islands west of -180° longitude if present.

  • args – Args to pass to the plot.

  • kwargs – Keyword args to pass to the plot.

Return type

ax of the plot.

censusdis.maps.plot_us_boundary(gdf: <Mock name='mock.GeoDataFrame' id='140304024888512'>, *args, do_relocate_ak_hi_pr: bool = True, **kwargs)[source]

Plot a map of boundaries the US with AK and HI relocated.

This function is very much like plot_us() except that it plots only the boundaries of geometries.

Parameters

  • gdf – The geometries to be plotted.

  • args – Args to pass to the plot.

  • do_relocate_ak_hi_pr – If True try to relocate AK, HI, and PR. Otherwise, still wrap the Aleutian islands west of -180° longitude if present.

  • kwargs – Keyword args to pass to the plot.

Return type

ax of the plot.

censusdis.maps.relocate_ak_hi_pr(gdf)[source]

Relocate any geometry that is in Alaska or Hawaii for plotting purposes.

We first try an optimization. If there is a STATEFP column then we relocate rows where that column has a value of STATE_AK, STATE_HI or TERRITORY_PR. If there is not a STATEFP column we check for a STATE column and do the same. If neither column exists then we dig down into the geometries themselves and relocate those that intersect bounding rectangles of the two states.

Parameters

gdf – the geo data frame to relocate.

Return type

a geo data frame with any geometry in AK or HI moved for plotting.