GeoAxes

class GeoAxes(*args, **kwargs)[source]

Bases: proplot.axes.plot.PlotAxes

Axes subclass for plotting in geographic projections. Uses either cartopy or basemap as a “backend”.

Important

This axes subclass can be used by passing proj='proj_name' to axes-creation commands like add_axes, add_subplot, and subplots, where proj_name is a registered PROJ projection name. You can also pass a cartopy.crs.Projection or Basemap instance instead of a projection name. Alternatively, you can pass any of the matplotlib-recognized axes subclass names proj='cartopy', proj='geo', or proj='geographic' with a cartopy.crs.Projection map_projection keyword argument, or pass proj='basemap' with a Basemap map_projection keyword argument.

Parameters
  • *args – Passed to matplotlib.axes.Axes.

  • autoextent (bool, optional) – For cartopy axes only. Whether to automatically adjust map bounds based on plotted content or enforce a global map extent (or a map bounded at the equator for polar projections). The extent can subsequently by adjusted with the format keywords lonlim, latlim, and boundinglat, or with set_extent. Default is rc['cartopy.autoextent'] = False.

  • circular (bool, optional) – For cartopy axes only. Whether to bound polar projections with circles rather than squares. Note that outer gridline labels cannot be added to circularly bounded polar projections. Default is rc['cartopy.circular'] = True.

  • map_projection (Projection or Basemap) – The cartopy or basemap projection instance. This is passed automatically when calling axes-creation commands like add_subplot.

  • lonlim, latlim (2-tuple of float, optional) – For cartopy axes only. The approximate longitude and latitude boundaries of the map, applied with set_extent. Basemap axes extents must be declared by passing keyword arguments to Proj.

  • boundinglat (float, optional) – For cartopy axes only. The edge latitude for the circle bounding North Pole and South Pole-centered projections. Basemap bounding latitudes must be declared by passing keyword arguments to Proj.

  • longrid, latgrid (bool, optional) – Whether to draw longitude and latitude gridlines. Default is rc.grid = True. Use grid to toggle both.

  • longridminor, latgridminor (bool, optional) – Whether to draw “minor” longitude and latitude lines. Default is rc.gridminor = False. Use gridminor to toggle both.

  • lonlines, latlines (optional) – Aliases for lonlocator, latlocator.

  • lonlocator, latlocator (locator-spec, optional) – Used to determine the longitude and latitude gridline locations. Passed to the Locator constructor. Can be string, float, list of float, or matplotlib.ticker.Locator instance.

    For basemap or cartopy < 0.18, the defaults are 'deglon' and 'deglat', which correspond to the LongitudeLocator and LatitudeLocator locators (adapted from cartopy). For cartopy >= 0.18, the defaults are 'dmslon' and 'dmslat', which uses the same locators with dms=True. This selects gridlines at nice degree-minute-second intervals when the map extent is very small.

  • lonlines_kw, latlines_kw (optional) – Aliases for lonlocator_kw, latlocator_kw.

  • lonlocator_kw, latlocator_kw (dict-like, optional) – Keyword arguments passed to the matplotlib.ticker.Locator class.

  • lonminorlocator, latminorlocator, lonminorlines, latminorlines (optional) – As with lonlocator and latlocator but for the “minor” gridlines. The defaults are rc['grid.lonminorstep'] and rc['grid.latminorstep'].

  • lonminorlines_kw, latminorlines_kw (optional) – Aliases for lonminorlocator_kw, latminorlocator_kw.

  • lonminorlocator_kw, latminorlocator_kw (optional) – As with lonlocator_kw and latlocator_kw but for the “minor” gridlines.

  • latmax (float, optional) – The maximum absolute latitude for longitude and latitude gridlines. Longitude gridlines are cut off poleward of this latitude for all basemap projections and cartopy projections predating cartopy 0.18. Default is 80.

  • labels (bool, optional) – Sets lonlabels and latlabels to True. Default is rc['grid.labels'] = False. To draw labels by default use e.g. pplt.rc['grid.labels'] = True.

  • lonlabels, latlabels (optional) – Whether to label longitudes and latitudes, and on which sides of the map. There are four different options:

    1. Boolean True. Indicates the left side for latitudes, bottom side for longitudes.

    2. A string or tuple of strings indicating the side names, e.g. 'left' for latitudes or 'bottom' for longitudes.

    3. A string indicating the side names with single characters, e.g. 'lr' for latitudes or 'bt' for longitudes.

    4. A boolean 2-tuple indicating whether to draw labels on the (left, right) sides for latitudes, or (bottom, top) sides for longitudes.

    5. A boolean 4-tuple indicating whether to draw labels on the (left, right, bottom, top) sides, as with the basemap drawmeridians and drawparallels labels keyword.

  • lonformatter, latformatter (formatter-spec, optional) – Formatter used to style longitude and latitude gridline labels. Passed to the Formatter constructor. Can be string, list of string, or matplotlib.ticker.Formatter instance.

    For basemap or cartopy < 0.18, the defaults are 'deglon' and 'deglat', which correspond to SimpleFormatter presets with degree symbols and cardinal direction suffixes. For cartopy >= 0.18, the defaults are 'dmslon' and 'dmslat', which uses cartopy’s LongitudeFormatter and LatitudeFormatter formatters with dms=True. This formats gridlines that do not fall on whole degrees as “minutes” and “seconds” rather than decimal degrees.

  • lonformatter_kw, latformatter_kw (dict-like, optional) – Keyword arguments passed to the matplotlib.ticker.Formatter class.

  • loninline, latinline, inlinelabels (bool, optional) – For cartopy axes only. Whether to draw inline longitude and latitude gridline labels. Default is rc['grid.inlinelabels'] = False. Setting these to True also sets the default values for lonlabels, latlabels, and labels to True (respectively).

  • rotatelabels (bool, optional) – For cartopy axes only. Whether to rotate longitude and latitude gridline labels. Default is rc['grid.rotatelabels'] = False.

  • labelpad (unit-spec, optional) – For cartopy axes only. The padding between the map boundary and longitude and latitude gridline labels. Default is rc['grid.labelpad'] = 4.0. If float, units are points. If string, interpreted by units.

  • dms (bool, optional) – For cartopy axes only. Specifies whether the default locators and formatters should use “minutes” and “seconds” for gridline labels on small scales rather than decimal degrees. Setting this to False is equivalent to specifying ax.format(lonlocator='deglon', latlocator='deglon') and ax.format(lonformatter='deglon', latformatter='deglat'). Default is rc['grid.dmslabels'] = True.

  • nsteps (int, optional) – For cartopy axes only. The number of interpolation steps used to draw gridlines. Default is rc['grid.nsteps'] = 250.

  • land, ocean, coast, rivers, lakes, borders, innerborders (bool, optional) – Toggles various geographic features. These are actually the rc.land, rc.ocean, rc.coast, rc.rivers, rc.lakes, rc.borders, and rc.innerborders settings passed to context. The style can be modified using additional rc settings.

    For example, to change rc['land.color'], use ax.format(landcolor='green'), and to change rc['land.zorder'], use ax.format(landzorder=4).

  • reso ({'lo', 'med', 'hi', 'x-hi', 'xx-hi'}, optional) – For cartopy axes only. The resolution of geographic features. For basemap axes, this must be passed to Proj.

  • color (color-spec, optional) – Color for the axes edge. Propagates to labelcolor unless specified otherwise (similar to proplot.axes.CartesianAxes.format).

  • labelcolor, gridlabelcolor (color-spec, optional) – Color for the grid labels. Default is color or rc['grid.labelcolor'] = 'black' if color was not passed.

  • labelsize, gridlabelsize (unit-spec or str, optional) – Font size for the gridline labels. Default is rc['grid.labelsize'] = 'medium'. If float, units are points. If string, interpreted by units.

  • labelweight, gridlabelweight (str, optional) – Font weight for the gridline labels. Default is rc['grid.labelweight'] = 'normal'.

Other Parameters
  • title (str, optional) – The axes title.

  • abc (bool or str, optional) – The “a-b-c” subplot label style. Must contain the character a or A, for example 'a.', or 'A'. If True then the default style of 'a' is used. The a or A is replaced with the alphabetic character matching the number. If number is greater than 26, the characters loop around to a, …, z, aa, …, zz, aaa, …, zzz, etc.

  • abcloc, titleloc (str, optional) – Strings indicating the location for the a-b-c label and main title. The following locations are valid (defaults are rc['abc.loc'] = 'left' and rc['title.loc'] = 'center'):

    Location

    Valid keys

    center above axes

    'center', 'c'

    left above axes

    'left', 'l'

    right above axes

    'right', 'r'

    lower center inside axes

    'lower center', 'lc'

    upper center inside axes

    'upper center', 'uc'

    upper right inside axes

    'upper right', 'ur'

    upper left inside axes

    'upper left', 'ul'

    lower left inside axes

    'lower left', 'll'

    lower right inside axes

    'lower right', 'lr'

  • abcborder, titleborder (bool, optional) – Whether to draw a white border around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes. Defaults are rc['abc.border'] = True and rc['title.border'] = True.

  • abcbbox, titlebbox (bool, optional) – Whether to draw a white bbox around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes. Defaults are rc['abc.bbox'] = False and rc['title.bbox'] = False.

  • abc_kw, title_kw (dict-like, optional) – Additional settings used to update the a-b-c label and title with text.update().

  • titlepad (float, optional) – The padding for the inner and outer titles and a-b-c labels in arbitrary units (default is points). Default is rc['title.pad'] = 5.0.

  • titleabove (bool, optional) – Whether to try to put outer titles and a-b-c labels above panels, colorbars, or legends that are above the axes. Default is rc['title.above'] = True.

  • abctitlepad (float, optional) – The horizontal padding between the a-b-c label and title when they are in the same location. Default is rc['abc.titlepad'] = 4.0.

  • ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle (str, optional) – Shorthands for the below keywords.

  • lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle, lowerlefttitle, lowercentertitle, lowerrighttitle (str, optoinal) – Additional titles in specific positions. This works as an alternative to the ax.format(title='Title', titleloc=loc) workflow and permits adding more than one title-like label for a single axes.

  • a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle (optional) – Additional settings applied to the background patch, and their shorthands. Defaults are rc['axes.alpha'], rc['axes.facecolor'], rc['axes.edgecolor'], rc['axes.linewidth'], and '-', respectively.

  • rc_mode (int, optional) – The context mode passed to context.

  • rc_kw (dict-like, optional) – An alternative to passing extra keyword arguments. See below.

  • **kwargs – Remaining keyword arguments are passed to matplotlib.axes.Axes.Keyword arguments that match the name of an rc setting are passed to proplot.config.Configurator.context and used to update the axes. If the setting name has “dots” you can simply omit the dots. For example, abc='A.' modifies the rc.abc setting, titleloc='left' modifies the rc['title.loc'] setting, gridminor=True modifies the rc.gridminor setting, and gridbelow=True modifies the rc['grid.below'] setting. Many of the keyword arguments documented above are internally applied by retrieving settings passed to context.

Note

This makes “longitude-latitude” coordinates the default for all plotting commands by passing transform=cartopy.crs.PlateCarree() when cartopy is the backend and latlon=True when basemap is the projection. Also, regardless of the backend, plotting is accomplished “cartopy-style” by calling plotting methods on the axes instance. You should not have to work with the Basemap instance directly.

Attributes Summary

projection

The Projection or Basemap instance associated with this axes.

Methods Summary

format()

Modify map limits, longitude and latitude gridlines, geographic features, and more.