Utilities

This guide will provide a tutorial for using the sole utility class available in the utils module: USA.

USA¶

The USA class within utils is intended to help users (a) quickly isolate subsets of states they want to include in their maps, and (b) enrich their data with additional characteristics (such as state abbreviations, regional/divisional groupings, and the like)

Set-Up¶

# Packages used by this tutorial
import geopandas # manipulating geographic data
import numpy # creating arrays
import pygris # easily acquiring shapefiles from the US Census
import matplotlib.pyplot # visualization

# Importing the main package
from matplotlib_map_utils.utils import USA

# Downloading the state-level dataset from pygris
states = pygris.states(cb=True, year=2022, cache=False).to_crs(3857)

# Creating a usa object
usa = USA() # this will load the data from ./utils/usa.json

The USA class contains a list of all states and territories for the USA in a list of dictionary objects. The included states and territories are based upon this Wikipedia page listing all the available FIPS codes.

Each state and territory has the following attributes available for it:

Example:

# Looking at a single example
usa.jurisdictions[0]

Returns:

{'fips': '01',
 'name': 'Alabama',
 'abbr': 'AL',
 'valid': True,
 'state': True,
 'contiguous': True,
 'territory': False,
 'region': 'South',
 'division': 'East South Central',
 'omb': 'Region IV',
 'bea': 'Southeast',
 'alias': None}

Filtering¶

All entries are available through entry points such as usa.jurisdictions (all valid entries), usa.states (all states), and usa.territories (all territories), for users to iterate over the list-of-dicts as desired. However, a convenience filter() function is also provided for the USA class, which allows users to easily apply layered filters.

The arguments for filter() mirror the properties available for each state/territory, except for alias (see below), and they can accept either single values or lists-of-values.

The final argument of filter() is to_return, which tells the function what value you want to return:

• fips (default), name, or abbr will return just that field for each returned entry.

• object or dict will return the full list-of-dicts that passes the filter

Some notes:

• Filters are applied "top-to-bottom" in the order they are shown-above, and act as "and" filters

• If only a single entry is going to be returned, it will be removed from the list and returned as a single value

• The name filter compares against both the name and alias fields

usa.filter(abbr="CA", to_return="name")

# Note that it is not returned as a list
'California'

# Filtering based on a list of FIPS codes
usa.filter(fips=["01","02","10","11"], to_return="name")

['Alabama', 'Alaska', 'Delaware', 'Washington, D.C.']

# Filtering for Pacific contiguous states
# Each option is applied as an "AND"
usa.filter(division="Pacific", contiguous=True, to_return="abbr")

['CA', 'OR', 'WA']

# If no entries are returned, a warning will show
usa.filter(territory=True, state=True)

UserWarning: No matching entities found. Please refer to the documentation and double-check your filters.

# Getting all valid states
valid = usa.filter_valid(True, to_return="object")
# Filtering that for all contiguous states
contiguous = usa.filter_contiguous(True, valid, "object")
# Filtering that for all Southern states
south = usa.filter_region("South", contiguous, "name")
south

    ['Alabama',
    'Arkansas',
    'Delaware',
    'Washington, D.C.',
    'Florida',
    'Georgia',
    'Kentucky',
    'Louisiana',
    'Maryland',
    'Mississippi',
    'North Carolina',
    'Oklahoma',
    'South Carolina',
    'Tennessee',
    'Texas',
    'Virginia',
    'West Virginia']

Pandas¶

The original impetus for this utility class was to help filter/enrich DataFrames and GeoDataFrames with additional data for each state/territory, which can be quite useful for plotting.

For example, let's say you had an incomplete GeoDataFrame, that just contained the FIPS Code (STATEFP):

gdf = states[["STATEFP","geometry"]].copy()
gdf.head()

If we want to add the name of each state corresponding to the FIPS code, we can call .apply() on a single column, which is pretty straightforward:

gdf["NAME"] = gdf["STATEFP"].apply(lambda x: usa.filter_fips(x, to_return="name"))
gdf.head()

If you want to return a non-standard column, you can set to_return to object and then access the values of the returned dictionary as required:

# When using .apply() on an entire DF, need to state the axis of transformation (0 for rows, 1 for columns)
gdf["BEA_REGION"] = gdf.apply(lambda x: usa.filter_fips(x["STATEFP"], to_return="object")["bea"], axis=1)
gdf.head()