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 likeadd_axes
,add_subplot
, andsubplots
, whereproj_name
is a registered PROJ projection name. You can also pass acartopy.crs.Projection
orBasemap
instance instead of a projection name. Alternatively, you can pass any of the matplotlib-recognized axes subclass namesproj='cartopy'
,proj='geo'
, orproj='geographic'
with acartopy.crs.Projection
map_projection
keyword argument, or passproj='basemap'
with aBasemap
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 theformat
keywordslonlim
,latlim
, andboundinglat
, or withset_extent
. Default isrc['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 isrc['cartopy.circular']
=True
.map_projection (
Projection
orBasemap
) – The cartopy or basemap projection instance. This is passed automatically when calling axes-creation commands likeadd_subplot
.lonlim, latlim (
2-tuple
offloat
, optional) – For cartopy axes only. The approximate longitude and latitude boundaries of the map, applied withset_extent
. Basemap axes extents must be declared by passing keyword arguments toProj
.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 toProj
.longrid, latgrid (
bool
, optional) – Whether to draw longitude and latitude gridlines. Default isrc.grid
=True
. Usegrid
to toggle both.longridminor, latgridminor (
bool
, optional) – Whether to draw “minor” longitude and latitude lines. Default isrc.gridminor
=False
. Usegridminor
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 theLocator
constructor. Can be string, float, list of float, ormatplotlib.ticker.Locator
instance.For basemap or cartopy < 0.18, the defaults are
'deglon'
and'deglat'
, which correspond to theLongitudeLocator
andLatitudeLocator
locators (adapted from cartopy). For cartopy >= 0.18, the defaults are'dmslon'
and'dmslat'
, which uses the same locators withdms=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
andlatlocator
but for the “minor” gridlines. The defaults arerc['grid.lonminorstep']
andrc['grid.latminorstep']
.lonminorlines_kw, latminorlines_kw (optional) – Aliases for
lonminorlocator_kw
,latminorlocator_kw
.lonminorlocator_kw, latminorlocator_kw (optional) – As with
lonlocator_kw
andlatlocator_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 is80
.labels (
bool
, optional) – Setslonlabels
andlatlabels
toTrue
. Default isrc['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:
Boolean
True
. Indicates the left side for latitudes, bottom side for longitudes.A string or tuple of strings indicating the side names, e.g.
'left'
for latitudes or'bottom'
for longitudes.A string indicating the side names with single characters, e.g.
'lr'
for latitudes or'bt'
for longitudes.A boolean 2-tuple indicating whether to draw labels on the
(left, right)
sides for latitudes, or(bottom, top)
sides for longitudes.A boolean 4-tuple indicating whether to draw labels on the
(left, right, bottom, top)
sides, as with the basemapdrawmeridians
anddrawparallels
labels
keyword.
lonformatter, latformatter (
formatter-spec
, optional) – Formatter used to style longitude and latitude gridline labels. Passed to theFormatter
constructor. Can be string, list of string, ormatplotlib.ticker.Formatter
instance.For basemap or cartopy < 0.18, the defaults are
'deglon'
and'deglat'
, which correspond toSimpleFormatter
presets with degree symbols and cardinal direction suffixes. For cartopy >= 0.18, the defaults are'dmslon'
and'dmslat'
, which uses cartopy’sLongitudeFormatter
andLatitudeFormatter
formatters withdms=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 isrc['grid.inlinelabels']
=False
. Setting these toTrue
also sets the default values forlonlabels
,latlabels
, andlabels
toTrue
(respectively).rotatelabels (
bool
, optional) – For cartopy axes only. Whether to rotate longitude and latitude gridline labels. Default isrc['grid.rotatelabels']
=False
.labelpad (
unit-spec
, optional) – For cartopy axes only. The padding between the map boundary and longitude and latitude gridline labels. Default isrc['grid.labelpad']
=4.0
. If float, units are points. If string, interpreted byunits
.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 toFalse
is equivalent to specifyingax.format(lonlocator='deglon', latlocator='deglon')
andax.format(lonformatter='deglon', latformatter='deglat')
. Default isrc['grid.dmslabels']
=True
.nsteps (
int
, optional) – For cartopy axes only. The number of interpolation steps used to draw gridlines. Default isrc['grid.nsteps']
=250
.land, ocean, coast, rivers, lakes, borders, innerborders (
bool
, optional) – Toggles various geographic features. These are actually therc.land
,rc.ocean
,rc.coast
,rc.rivers
,rc.lakes
,rc.borders
, andrc.innerborders
settings passed tocontext
. The style can be modified using additionalrc
settings.For example, to change
rc['land.color']
, useax.format(landcolor='green')
, and to changerc['land.zorder']
, useax.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 toProj
.color (
color-spec
, optional) – Color for the axes edge. Propagates tolabelcolor
unless specified otherwise (similar toproplot.axes.CartesianAxes.format
).labelcolor, gridlabelcolor (
color-spec
, optional) – Color for the grid labels. Default iscolor
orrc['grid.labelcolor']
='black'
ifcolor
was not passed.labelsize, gridlabelsize (
unit-spec
orstr
, optional) – Font size for the gridline labels. Default isrc['grid.labelsize']
='medium'
. If float, units are points. If string, interpreted byunits
.labelweight, gridlabelweight (
str
, optional) – Font weight for the gridline labels. Default isrc['grid.labelweight']
='normal'
.
- Other Parameters
title (
str
, optional) – The axes title.abc (
bool
orstr
, optional) – The “a-b-c” subplot label style. Must contain the charactera
orA
, for example'a.'
, or'A'
. IfTrue
then the default style of'a'
is used. Thea
orA
is replaced with the alphabetic character matching thenumber
. Ifnumber
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 arerc['abc.loc']
='left'
andrc['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 arerc['abc.border']
=True
andrc['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 arerc['abc.bbox']
=False
andrc['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 isrc['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 isrc['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 isrc['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 theax.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 tocontext
.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 anrc
setting are passed toproplot.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 therc.abc
setting,titleloc='left'
modifies therc['title.loc']
setting,gridminor=True
modifies therc.gridminor
setting, andgridbelow=True
modifies therc['grid.below']
setting. Many of the keyword arguments documented above are internally applied by retrieving settings passed tocontext
.
Note
This makes “longitude-latitude” coordinates the default for all plotting commands by passing
transform=cartopy.crs.PlateCarree()
when cartopy is the backend andlatlon=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 theBasemap
instance directly.See also
GeoAxes.format
,proplot.constructor.Proj
,proplot.axes.Axes
,proplot.axes.PlotAxes
,proplot.figure.Figure.subplot
,proplot.figure.Figure.add_subplot
Attributes Summary
The
Projection
orBasemap
instance associated with this axes.Methods Summary
format
()Modify map limits, longitude and latitude gridlines, geographic features, and more.