geoplot.cartogram

geoplot.cartogram(df, projection=None, scale=None, limits=(0.2, 1), scale_func=None, trace=True, trace_kwargs=None, hue=None, categorical=False, scheme=None, k=5, cmap='viridis', vmin=None, vmax=None, legend=False, legend_values=None, legend_labels=None, legend_kwargs=None, legend_var='scale', extent=None, figsize=(8, 6), ax=None, **kwargs)

Self-scaling area 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.
  • scale (str or iterable, optional) – Applies scaling to the output points. Defaults to None (no scaling).
  • limits ((min, max) tuple, optional) – The minimum and maximum scale limits. Ignored if scale is left specified.
  • scale_func (ufunc, optional) – The function used to scale point sizes. Defaults to a linear scale. For more information see the Gallery demo.
  • trace (boolean, optional) – Whether or not to include a trace of the polygon’s original outline in the plot result.
  • trace_kwargs (dict, optional) – If trace is set to True, this parameter can be used to adjust the properties of the trace outline. This parameter is ignored if trace is False.
  • 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 cartogram is a plot type which ingests a series of enclosed Polygon or MultiPolygon entities and spits out a view of these shapes in which area is distorted according to the size of some parameter of interest.

A basic cartogram specifies data, a projection, and a scale parameter.

import geoplot as gplt
import geoplot.crs as gcrs
gplt.cartogram(boroughs, scale='Population Density', projection=gcrs.AlbersEqualArea())
_images/cartogram-initial.png

The gray outline can be turned off by specifying trace, and a legend can be added by specifying legend.

gplt.cartogram(boroughs, scale='Population Density', projection=gcrs.AlbersEqualArea(),
               trace=False, legend=True)
_images/cartogram-trace-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.cartogram(boroughs, scale='Population Density', projection=gcrs.AlbersEqualArea(),
               trace=False, legend=True, legend_kwargs={'loc': 'upper left'})
_images/cartogram-legend-kwargs.png

Additional arguments to cartogram will be interpreted as keyword arguments for the scaled polygons, using matplotlib Polygon patch rules.

gplt.cartogram(boroughs, scale='Population Density', projection=gcrs.AlbersEqualArea(),
               edgecolor='darkgreen')
_images/cartogram-kwargs.png

Manipulate the outlines use the trace_kwargs argument, which accepts the same matplotlib Polygon patch parameters.

gplt.cartogram(boroughs, scale='Population Density', projection=gcrs.AlbersEqualArea(),
               trace_kwargs={'edgecolor': 'lightgreen'})
_images/cartogram-trace-kwargs.png

Adjust the level of scaling to apply using the limits parameter.

gplt.cartogram(boroughs, scale='Population Density', projection=gcrs.AlbersEqualArea(),
               limits=(0.5, 1))
_images/cartogram-limits.png

The default scaling function is linear: an observations at the midpoint of two others will be exactly midway between them in size. To specify an alternative scaling function, use the scale_func parameter. This should be a factory function of two variables which, when given the maximum and minimum of the dataset, returns a scaling function which will be applied to the rest of the data. A demo is available in the example gallery.

def trivial_scale(minval, maxval): return lambda v: 2
gplt.cartogram(boroughs, scale='Population Density', projection=gcrs.AlbersEqualArea(),
               limits=(0.5, 1), scale_func=trivial_scale)
_images/cartogram-scale-func.png

cartogram also provides the same hue visual variable parameters provided by e.g. pointplot. For more information on hue-related arguments, see the related sections in the pointplot documentation.

gplt.cartogram(boroughs, scale='Population Density', projection=gcrs.AlbersEqualArea(),
               hue='Population Density', k=None, cmap='Blues')
_images/cartogram-hue.png