geoplot.voronoi

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

Geospatial Voronoi diagram.

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 Line2D objects.
Returns:

The axis object with the plot on it.

Return type:

AxesSubplot or GeoAxesSubplot instance

Examples

The neighborhood closest to a point in space is known as its Voronoi region. Every point in a dataset has a Voronoi region, which may be either a closed polygon (for inliers) or open infinite region (for points on the edge of the distribution). A Voronoi diagram works by dividing a space filled with points into such regions and plotting the result. Voronoi plots allow efficient assessmelt of the density of points in different spaces, and when combined with a colormap can be quite informative of overall trends in the dataset.

The geoplot voronoi is a spatially aware application of this technique. It compares well with the more well-known choropleth, which has the advantage of using meaningful regions, but the disadvantage of having defined those regions beforehand. voronoi has fewer requirements and may perform better when the number of observations is small. Compare also with the quadtree technique available in aggplot.

A basic voronoi specified data and, optionally, a projection. We overlay geometry to aid interpretability.

ax = gplt.voronoi(injurious_collisions.head(1000))
gplt.polyplot(boroughs, ax=ax)
_images/voronoi-simple.png

hue parameterizes the color, and cmap controls the colormap.

ax = gplt.voronoi(injurious_collisions.head(1000), hue='NUMBER OF PERSONS INJURED', cmap='Reds')
gplt.polyplot(boroughs, ax=ax)
_images/voronoi-cmap.png

Add a clip of iterable geometries to trim the voronoi against local geography.

ax = gplt.voronoi(injurious_collisions.head(1000), hue='NUMBER OF PERSONS INJURED', cmap='Reds',
                  clip=boroughs.geometry)
gplt.polyplot(boroughs, ax=ax)
_images/voronoi-clip.png

legend adds a a matplotlib Legend. This can be tuned even further using the legend_kwargs argument. Other keyword parameters are passed to the underlying matplotlib Polygon patches.

ax = gplt.voronoi(injurious_collisions.head(1000), hue='NUMBER OF PERSONS INJURED', cmap='Reds',
                  clip=boroughs.geometry,
                  legend=True, legend_kwargs={'loc': 'upper left'},
                  linewidth=0.5, edgecolor='white',
                 )
gplt.polyplot(boroughs, ax=ax)
_images/voronoi-kwargs.png

Change the number of bins by specifying an alternative k value. To use a continuous colormap, explicitly specify k=None. You can change the binning sceme with scheme. 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.

ax = gplt.voronoi(injurious_collisions.head(1000),
                  hue='NUMBER OF PERSONS INJURED', cmap='Reds', k=5, scheme='fisher_jenks',
                  clip=boroughs.geometry,
                  legend=True, legend_kwargs={'loc': 'upper left'},
                  linewidth=0.5, edgecolor='white',
                 )
gplt.polyplot(boroughs, ax=ax)
_images/voronoi-scheme.png

If your variable of interest is already categorical, specify categorical=True to use the labels in your dataset directly.

ax = gplt.voronoi(injurious_collisions.head(1000), hue='NUMBER OF PERSONS INJURED', cmap='Reds',
     edgecolor='white', clip=boroughs.geometry,
     linewidth=0.5, categorical=True
     )
gplt.polyplot(boroughs, linewidth=1, ax=ax)
_images/voronoi-multiparty.png