geoplot.choropleth

geoplot.choropleth(df, projection=None, hue=None, scheme=None, k=5, cmap='Set1', categorical=False, vmin=None, vmax=None, legend=False, legend_kwargs=None, legend_labels=None, extent=None, figsize=(8, 6), ax=None, **kwargs)

Area aggregation plot.

Parameters:
  • df (GeoDataFrame) – The data being plotted.
  • projection (geoplot.crs object instance, optional) – A geographic projection. For more information refer to the tutorial page on projections.
  • hue (None, Series, GeoSeries, iterable, or str, optional) – Applies a colormap to the output points.
  • categorical (boolean, optional) – Set to True if hue references a categorical variable, and False (the default) otherwise. Ignored if hue is left unspecified.
  • scheme (None or {"quantiles"|"equal_interval"|"fisher_Jenks"}, optional) – Controls how the colormap bin edges are determined. Ignored if hue is left unspecified.
  • k (int or None, optional) – Ignored if hue is left unspecified. Otherwise, if categorical is False, controls how many colors to use (5 is the default). If set to None, a continuous colormap will be used.
  • cmap (matplotlib color, optional) – The matplotlib colormap to be used. Ignored if hue is left unspecified.
  • vmin (float, optional) – Values below this level will be colored the same threshold value. Defaults to the dataset minimum. Ignored if hue is left unspecified.
  • vmax (float, optional) – Values above this level will be colored the same threshold value. Defaults to the dataset maximum. Ignored if hue is left unspecified.
  • legend (boolean, optional) – Whether or not to include a legend. Ignored if neither a hue nor a scale is specified.
  • legend_values (list, optional) – The values to use in the legend. Defaults to equal intervals. For more information see the Gallery demo.
  • legend_labels (list, optional) –

    The names to use in the legend. Defaults to the variable values. For more information see the Gallery demo.

  • legend_kwargs (dict, optional) – Keyword arguments to be passed to the underlying legend.
  • extent (None or (minx, maxx, miny, maxy), optional) – Used to control plot x-axis and y-axis limits manually.
  • figsize (tuple, optional) – An (x, y) tuple passed to matplotlib.figure which sets the size, in inches, of the resultant plot.
  • ax (AxesSubplot or GeoAxesSubplot instance, optional) – A matplotlib.axes.AxesSubplot or cartopy.mpl.geoaxes.GeoAxesSubplot instance. Defaults to a new axis.
  • kwargs (dict, optional) – Keyword arguments to be passed to the underlying matplotlib Polygon patches.
Returns:

The plot axis

Return type:

AxesSubplot or GeoAxesSubplot

Examples

A choropleth takes observations that have been aggregated on some meaningful polygonal level (e.g. census tract, state, country, or continent) and displays the data to the reader using color. It is a well-known plot type, and likeliest the most general-purpose and well-known of the specifically spatial plot types. It is especially powerful when combined with meaningful or actionable aggregation areas; if no such aggregations exist, or the aggregations you have access to are mostly incidental, its value is more limited.

The choropleth requires a series of enclosed areas consisting of shapely Polygon or MultiPolygon entities, and a set of data about them that you would like to express in color. A basic choropleth requires geometry, a hue variable, and, optionally, a projection.

import geoplot as gplt
import geoplot.crs as gcrs
gplt.choropleth(polydata, hue='latdep', projection=gcrs.PlateCarree())
_images/choropleth-initial.png

Change the colormap with the cmap parameter.

gplt.choropleth(polydata, hue='latdep', projection=gcrs.PlateCarree(), cmap='Blues')
_images/choropleth-cmap.png

If your variable of interest is already categorical, you can specify categorical=True to use the labels in your dataset directly. To add a legend, specify legend.

gplt.choropleth(boroughs, projection=gcrs.AlbersEqualArea(), hue='BoroName',
                categorical=True, legend=True)
_images/choropleth-legend.png

Keyword arguments can be passed to the legend using the legend_kwargs argument. These arguments will be passed to the underlying matplotlib.legend.Legend instance (ref). The loc and bbox_to_anchor parameters are particularly useful for positioning the legend. Other additional arguments will be passed to the underlying matplotlib scatter plot.

gplt.choropleth(boroughs, projection=gcrs.AlbersEqualArea(), hue='BoroName',
                categorical=True, legend=True, legend_kwargs={'loc': 'upper left'})
_images/choropleth-legend-kwargs.png

Additional arguments not in the method signature will be passed as keyword parameters to the underlying matplotlib Polygon patches.

gplt.choropleth(boroughs, projection=gcrs.AlbersEqualArea(), hue='BoroName', categorical=True,
                linewidth=0)
_images/choropleth-kwargs.png

Choropleths default to splitting the data into five buckets with approximately equal numbers of observations in them. Change the number of buckets by specifying k. Or, to use a continuous colormap, specify k=None. In this case a colorbar legend will be used.

gplt.choropleth(polydata, hue='latdep', cmap='Blues', k=None, legend=True,
                projection=gcrs.PlateCarree())
_images/choropleth-k-none.png

The choropleth binning methodology is controlled using by scheme` parameter. The default is quantile, which bins observations into classes of different sizes but the same numbers of observations. equal_interval will creates bins that are the same size, but potentially containing different numbers of observations. The more complicated fisher_jenks scheme is an intermediate between the two.

gplt.choropleth(census_tracts, hue='mock_data', projection=gcrs.AlbersEqualArea(),
        legend=True, edgecolor='white', linewidth=0.5, legend_kwargs={'loc': 'upper left'},
        scheme='equal_interval')
_images/choropleth-scheme.png