Maps

class eomaps.eomaps.Maps(crs=None, layer='base', f=None, ax=None, preferred_wms_service='wms', **kwargs)

The base-class for generating plots with EOmaps.

The first Maps object that is initialized will create a new matplotlib Figure and a cartopy GeoAxes for a map.

You can then create additional Maps objects on the same figure with the following methods:

See also

Maps.new_layer: Create a new layer for the map.
Maps.new_map: Add a new map to the figure.
Maps.new_inset_map: Add a new inset-map to the figure.
MapsGrid: Initialize a grid of Maps objects

Parameters:

crs (int or a cartopy-projection, optional) –
The projection of the map. If int, it is identified as an epsg-code Otherwise you can specify any projection supported by cartopy.crs A list for easy-accses is available as Maps.CRS

The default is 4326.
layer (str, optional) – The name of the plot-layer assigned to this Maps-object. The default is “base”.
f (matplotlib.Figure, optional) –
Explicitly specify the matplotlib figure instance to use. (ONLY useful if you want to add a map to an already existing figure!)
- If None, a new figure will be created (accessible via m.f)
- Connected maps-objects will always share the same figure! You do NOT need to specify it (just provide the parent and you’re fine)!
The default is None
ax (int, list, tuple, matplotlib.Axes, matplotlib.gridspec.SubplotSpec or None) –
Explicitly specify the position of the axes or use already existing axes.

Possible values are:
- None:
  Initialize a new axes at the center of the figure (the default)
- A tuple of 4 floats (left, bottom, width, height)
  The absolute position of the axis in relative figure-coordinates (e.g. in the range [0 , 1]) NOTE: since the axis-size is dependent on the plot-extent, the size of the map will be adjusted to fit in the provided bounding-box.
- A tuple of 3 integers (nrows, ncols, index)
  The map will be positioned at the index position of a grid with nrows rows and ncols columns. index starts at 1 in the upper left corner and increases to the right. index can also be a two-tuple specifying the (first, last) indices (1-based, and including last) of the subplot, e.g., ax = (3, 1, (1, 2)) makes a map that spans the upper 2/3 of the figure.
- A 3-digit integer
  Same as using a tuple of three single-digit integers. (e.g. 111 is the same as (1, 1, 1) )
- matplotilb.gridspec.SubplotSpec:
  Use the SubplotSpec for initializing the axes.
- matplotilb.Axes:
  Directly use the provided figure and axes instances for plotting. NOTE: The axes MUST be a geo-axes with m.crs_plot projection!
preferred_wms_service (str, optional) – Set the preferred way for accessing WebMap services if both WMS and WMTS capabilities are possible. The default is “wms”
kwargs – additional kwargs are passed to matplotlib.pyplot.figure() - e.g. figsize=(10,5)

Examples

Create a new Maps object and initialize a figure and axes for a map.

>>> from eomaps import Maps
>>> m = Maps()
>>> # add basic background features to the map
>>> m.add_feature.preset("coastline", "ocean", "land")
>>> # create a new layer and add more features
>>> m1 = m.new_layer("layer 1")
>>> m1.add_feature.physical.coastline(fc="none", ec="b", lw=2, scale=50)
>>> m1.add_feature.cultural.admin_0_countries(fc=(.2,.1,.4,.2), ec="b", lw=1, scale=50)
>>> # overlay a part of the new layer in a circle if you click on the map
>>> m.cb.click.attach.peek_layer(m1.layer, how=0.4, shape="round")

Use Maps-objects as context-manager to close the map and free memory once the map is exported.

>>> from eomaps import Maps
>>> with Maps() as m:
>>>     m.add_feature.preset.coastline()
>>>     m.savefig(...)

CRS

Type:: Accessor for available projections (Supercharged version of cartopy.crs)

CLASSIFIERS

Type:: Accessor for available classifiers (provided by mapclassify)

_companion_widget_key

Type:: Keyboard shortcut assigned to show/hide the companion-widget

Methods

`__init__`([crs, layer, f, ax, ...])
`add_annotation`([ID, xy, xy_crs, text, update])	Add an annotation to the plot.
`add_colorbar`(m[, pos, inherit_position, ...])	Add a colorbar to the map.
`add_compass`([pos, pos_transform, scale, ...])	Add a "compass" or "north-arrow" to the map.
`add_gdf`(gdf[, picker_name, pick_method, ...])	Plot a geopandas.GeoDataFrame on the map.
`add_gridlines`([d, auto_n, n, bounds, layer, ...])	Add gridlines to the map.
`add_line`(xy[, xy_crs, connect, n, del_s, ...])	Draw a line by connecting a set of anchor-points.
`add_logo`([filepath, position, size, pad, ...])	Add a small image (png, jpeg etc.) to the map.
`add_marker`([ID, xy, xy_crs, radius, ...])	Add a marker to the plot.
`add_scalebar`(m[, preset, scale, n, ...])	Add a scalebar to the map.
`add_title`(title[, x, y])	Convenience function to add a title to the map.
`apply_layout`(layout)	Set the positions of all axes within the current plot based on a previously defined layout.
`cleanup`()	Cleanup all references to the object so that it can be safely deleted.
`copy`([data_specs, classify_specs, shape])	Create a (deep)copy of the Maps object that shares selected specifications.
`edit_annotations`([q])	Toggle if annotations are editable or not.
`edit_layout`([filepath])	Activate the "layout-editor" to quickly re-arrange the positions of subplots.
`fetch_companion_wms_layers`([refetch])	Fetch (and cache) WebMap layer names for the companion-widget.
`fetch_layers`([layers])	Fetch (and cache) the layers of a map.
`get_crs`([crs])	Get the pyproj CRS instance of a given crs specification.
`get_extent`([crs])	Get the extent (x0, x1, y0, y1) of the map in the given coordinate system.
`get_layout`([filepath, override, precision])	Get the positions of all axes within the current plot.
`indicate_extent`(x0, y0, x1, y1[, crs, npts])	Indicate a rectangular extent in a given crs on the map.
`inherit_classification`(m)	Use the classification of another Maps-object when plotting the data.
`inherit_data`(m)	Use the data of another Maps-object (without copying).
`join_limits`(*args)	Join the x- and y- limits of the maps (crs must be equal!).
`make_dataset_pickable`()	Make the associated dataset pickable without plotting it first.
`new_inset_map`([xy, xy_crs, radius, ...])	Create a new (empty) inset-map that shows a zoomed-in view on a given extent.
`new_layer`([layer, inherit_data, ...])	Create a new Maps-object that shares the same plot-axes.
`new_map`([ax, keep_on_top, inherit_data, ...])	Create a new map that shares the figure with this Maps-object.
`on_layer_activation`(func[, layer, persistent])	Attach a callback that is executed if the associated layer is activated.
`plot_map`([layer, dynamic, set_extent, ...])	Plot the dataset assigned to this Maps-object.
`redraw`(*args)	Force a re-draw of cached background layers.
`refetch_wms_on_size_change`()	Set the behavior of WebMap services with respect to size changes.
`savefig`(**kwargs)	Save the current figure.
`set_classify_specs`([scheme])	Set classification specifications for the data.
`set_clipboard_kwargs`(**kwargs)	Set GLOBAL savefig parameters for all Maps objects on export to the clipboard.
`set_data`([data, x, y, crs, encoding, cpos, ...])	Set the properties of the dataset you want to plot.
`set_data_specs`([data, x, y, crs, encoding, ...])	WARNING: m.set_data_specs(...) is depreciated! Use m.set_data(...) instead!
`set_extent`(extents[, crs])	Set the extent (x0, x1, y0, y1) of the map in the given coordinate system.
`set_extent_to_location`(location[, annotate, ...])	Set the map-extent based on a given location query.
`set_frame`([rounded])	Set the properties of the map boundary and the background patch.
`show`([clear])	Show the map (only required for non-interactive matplotlib backends).
`show_layer`(*args[, clear])	Show a single layer or (transparently) overlay multiple selected layers.
`snapshot`(*layer[, transparent, clear])	Print a static image of the figure to the active IPython display.
`subplots_adjust`(**kwargs)	Update the subplot parameters of the grid.
`text`(x, y, s[, fontdict])	Add text to figure.

Attributes

`BM`	The Blit-Manager used to dynamically update the plots.
`CLASSIFIERS`	Accessor for available classification schemes.
`add_feature`	Interface to the feature-layers provided by NaturalEarth.
`add_wms`	A collection of open-access WebMap services that can be added to the maps.
`all`	Get a Maps-object on the "all" layer.
`ax`	The matplotlib (cartopy) GeoAxes associated with this Maps-object.
`cb`	Accessor for attaching callbacks and accessing return-objects.
`coll`	The collection representing the dataset plotted by m.plot_map().
`colorbar`	Get the most recently added colorbar of this Maps-object.
`crs_plot`	The crs used for plotting.
`data`	The data assigned to this Maps-object.
`draw`	Base-class for drawing shapes on a map.
`f`	The matplotlib Figure associated with this Maps-object.
`layer`	The layer-name associated with this Maps-object.
`new_layer_from_file`	A collection of methods to add a new layer to an existing Maps-object from a file.
`parent`	The parent-object to which this Maps-object is connected to.
`set_classify`	Interface to the classifiers provided by the 'mapclassify' module.
`set_shape`	Set the plot-shape to represent the data-points.
`shape`	The shape that is used to represent the dataset if m.plot_map() is called.
`util`	A collection of utility tools that can be added to EOmaps plots.