geoplot.pointplot

geoplot.pointplot(df, projection=None, hue=None, categorical=False, scheme=None, k=5, cmap='Set1', vmin=None, vmax=None, scale=None, limits=(0.5, 2), scale_func=None, legend=False, legend_values=None, legend_labels=None, legend_kwargs=None, legend_var=None, figsize=(8, 6), extent=None, ax=None, **kwargs)

Geospatial scatter 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.
  • 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.
  • 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_var ("hue" or "scale", optional) – If both hue and scale are specified, which variable to use in the legend.
  • 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 scatter plot.
Returns:

The plot axis

Return type:

AxesSubplot or GeoAxesSubplot

Examples

The pointplot is a geospatial scatter plot representing each observation in your dataset with a single point. It is simple and easily interpretable plot that is nearly universally understood, making it an ideal choice for showing simple pointwise relationships between observations.

The expected input is a GeoDataFrame containing geometries of the shapely.geometry.Point type. A bare-bones pointplot goes thusly:

import geoplot as gplt
import geoplot.crs as gcrs
gplt.pointplot(points)
_images/pointplot-initial.png

The hue parameter accepts a data column and applies a colormap to the output. The legend parameter toggles a legend.

gplt.pointplot(cities, projection=gcrs.AlbersEqualArea(), hue='ELEV_IN_FT', legend=True)
_images/pointplot-legend.png

The pointplot 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.pointplot(cities, projection=gcrs.AlbersEqualArea(), hue='ELEV_IN_FT',
               legend=True, scheme='equal_interval')
_images/pointplot-scheme.png

Alternatively, your data may already be categorical. In that case specify categorical=True instead.

gplt.pointplot(collisions, projection=gcrs.AlbersEqualArea(), hue='BOROUGH',
               legend=True, categorical=True)
_images/pointplot-categorical.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.pointplot(collisions[collisions['BOROUGH'].notnull()], projection=gcrs.AlbersEqualArea(),
               hue='BOROUGH', categorical=True,
               legend=True, legend_kwargs={'loc': 'upper left'},
               edgecolor='white', linewidth=0.5)
_images/pointplot-kwargs.png

Change the number of bins by specifying an alternative k value. Adjust the colormap using the cmap parameter. To use a continuous colormap, explicitly specify k=None. Note that if legend=True, a matplotlib colorbar legend will be used.

gplt.pointplot(data, projection=gcrs.AlbersEqualArea(),
               hue='var', k=8,
               edgecolor='white', linewidth=0.5,
               legend=True, legend_kwargs={'bbox_to_anchor': (1.25, 1.0)})
_images/pointplot-k.png

scale provides an alternative or additional visual variable.

gplt.pointplot(collisions, projection=gcrs.AlbersEqualArea(),
               scale='NUMBER OF PERSONS INJURED',
               legend=True, legend_kwargs={'loc': 'upper left'})
_images/pointplot-scale.png

The limits can be adjusted to fit your data using the limits parameter.

gplt.pointplot(collisions, projection=gcrs.AlbersEqualArea(),
               scale='NUMBER OF PERSONS INJURED', limits=(0, 10),
               legend=True, legend_kwargs={'loc': 'upper left'})
_images/pointplot-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):
    def scalar(val):
        return 2
    return scalar

gplt.pointplot(collisions, projection=gcrs.AlbersEqualArea(),
               scale='NUMBER OF PERSONS INJURED', scale_func=trivial_scale,
               legend=True, legend_kwargs={'loc': 'upper left'})
_images/pointplot-scale-func.png

hue and scale can co-exist. In case more than one visual variable is used, control which one appears in the legend using legend_var.

gplt.pointplot(collisions[collisions['BOROUGH'].notnull()],
               projection=gcrs.AlbersEqualArea(),
               hue='BOROUGH', categorical=True,
               scale='NUMBER OF PERSONS INJURED', limits=(0, 10),
               legend=True, legend_kwargs={'loc': 'upper left'},
               legend_var='scale')
_images/pointplot-legend-var.png