Choropleth maps (state and county levels)

plot_utils.choropleth_map_county(data_per_county, fig=None, ax=None, figsize=(10, 7), dpi=100, vmin=None, vmax=None, unit='', cmap='OrRd', map_title='USA county map', fontsize=14, cmap_midpoint=None, shapefile_dir=None)

Generate a choropleth map of the US (including Alaska and Hawaii), on a county level.

According to Wikipedia, a choropleth map is a thematic map in which areas are shaded or patterned in proportion to the measurement of the statistical variable being displayed on the map, such as population density or per-capita income.

Parameters:

• data_per_county (dict or pandas.Series or pandas.DataFrame) –

  Numerical data of each county, to be plotted onto the map. Acceptable data types include:

  • pandas Series: Index should be valid county identifiers (i.e.,

    5-digit county FIPS codes)

  • pandas DataFrame: The dataframe can have only one column (with

    the index being valid county identifiers), two columns (with one of the column named ‘state’, ‘State’, or ‘FIPS_code’, and containing county identifiers).

  • dictionary: with keys being valid county identifiers, and values

    being the numerical values to be visualized

• fig (matplotlib.figure.Figure or None) – Figure object. If None, a new figure will be created.

• ax (matplotlib.axes._subplots.AxesSubplot or None) – Axes object. If None, a new axes will be created.

• figsize ((float, float)) – Figure size in inches, as a tuple of two numbers. The figure size of fig (if not None) will override this parameter.

• dpi (float) – Figure resolution. The dpi of fig (if not None) will override this parameter.

• vmin (float) – Minimum value to be shown on the map. If vmin is larger than the actual minimum value in the data, some of the data values will be “clipped”. This is useful if there are extreme values in the data and you do not want those values to complete skew the color distribution.

• vmax (float) – Maximum value to be shown on the map. Similar to vmin.

• map_title (str) – Title of the map, to be shown on the top of the map.

• unit (str) – Unit of the numerical (for example, “population per km^2”), to be shown on the right side of the color bar.

• cmap (str or <matplotlib.colors.Colormap>) – Color map name. Suggested names: ‘hot_r’, ‘summer_r’, and ‘RdYlBu’ for plotting deviation maps.

• fontsize (scalar) – Font size of all the texts on the map.

• cmap_midpoint (float) – A numerical value that specifies the “deviation point”. For example, if your data ranges from -200 to 1000, and you want negative values to appear blue-ish, and positive values to appear red-ish, then you can set cmap_midpoint to 0.0. If None, then the “deviation point” will be the median value of the data values.

• shapefile_dir (str) –

  Directory where shape files are stored. Shape files (state level and county level) should be organized as follows:

  shapefile_dir/usa_states/st99_d00.(…) shapefile_dir/usa_counties/cb_2016_us_county_500k.(…)

  If None, the shapefile directory within this library will be used.

Returns:

• fig (matplotlib.figure.Figure) – The figure object being created or being passed into this function.

• ax (matplotlib.axes._subplots.AxesSubplot) – The axes object being created or being passed into this function.

References

This function is based partly on an example in the Basemap repository (https://github.com/matplotlib/basemap/blob/master/examples/fillstates.py) as well as a modification on Stack Overflow (https://stackoverflow.com/questions/39742305).

plot_utils.choropleth_map_state(data_per_state, fig=None, ax=None, figsize=(10, 7), dpi=100, vmin=None, vmax=None, map_title='USA map', unit='', cmap='OrRd', fontsize=14, cmap_midpoint=None, shapefile_dir=None)

Generate a choropleth map of the US (including Alaska and Hawaii), on a state level.

According to Wikipedia, a choropleth map is a thematic map in which areas are shaded or patterned in proportion to the measurement of the statistical variable being displayed on the map, such as population density or per-capita income.

Parameters:

• data_per_state (dict or pandas.Series or pandas.DataFrame) –

  Numerical data of each state, to be plotted onto the map. Acceptable data types include:

  • pandas Series: Index should be valid state identifiers (i.e.,

    state full name, abbreviation, or FIPS code)

  • pandas DataFrame: The dataframe can have only one column (with

    the index being valid state identifiers), two columns (with one of the column named ‘state’, ‘State’, or ‘FIPS_code’, and containing state identifiers).

  • dictionary: with keys being valid state identifiers, and values

    being the numerical values to be visualized

• fig (matplotlib.figure.Figure or None) – Figure object. If None, a new figure will be created.

• ax (matplotlib.axes._subplots.AxesSubplot or None) – Axes object. If None, a new axes will be created.

• figsize ((float, float)) – Figure size in inches, as a tuple of two numbers. The figure size of fig (if not None) will override this parameter.

• dpi (float) – Figure resolution. The dpi of fig (if not None) will override this parameter.

• vmin (float) – Minimum value to be shown on the map. If vmin is larger than the actual minimum value in the data, some of the data values will be “clipped”. This is useful if there are extreme values in the data and you do not want those values to complete skew the color distribution.

• vmax (float) – Maximum value to be shown on the map. Similar to vmin.

• map_title (str) – Title of the map, to be shown on the top of the map.

• unit (str) – Unit of the numerical (for example, “population per km^2”), to be shown on the right side of the color bar.

• cmap (str or matplotlib.colors.Colormap) – Color map name. Suggested names: ‘hot_r’, ‘summer_r’, and ‘RdYlBu’ for plotting deviation maps.

• fontsize (float) – Font size of all the texts on the map.

• cmap_midpoint (float) – A numerical value that specifies the “deviation point”. For example, if your data ranges from -200 to 1000, and you want negative values to appear blue-ish, and positive values to appear red-ish, then you can set cmap_midpoint to 0.0. If None, then the “deviation point” will be the median value of the data values.

• shapefile_dir (str) –

  Directory where shape files are stored. Shape files (state level and county level) should be organized as follows:

  shapefile_dir/usa_states/st99_d00.(…) shapefile_dir/usa_counties/cb_2016_us_county_500k.(…)

  If None, the shapefile directory within this library will be used.

Returns:

• fig (matplotlib.figure.Figure) – The figure object being created or being passed into this function.

• ax (matplotlib.axes._subplots.AxesSubplot) – The axes object being created or being passed into this function.

References

This function is based partly on an example in the Basemap repository (https://github.com/matplotlib/basemap/blob/master/examples/fillstates.py) as well as a modification on Stack Overflow (https://stackoverflow.com/questions/39742305).