`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(...)

Note

You can access possible crs via the CRS accessor (alias of cartopy.crs):

>>> m = Maps(crs=Maps.CRS.Orthographic())

Properties#

`Maps.f`	The matplotlib Figure associated with this Maps-object.
`Maps.ax`	The matplotlib (cartopy) GeoAxes associated with this Maps-object.
`Maps.layer`	The layer-name associated with this Maps-object.
`Maps.crs_plot`	The crs used for plotting.

`Maps.data`	The data assigned to this Maps-object.
`Maps.data_specs`	Container for accessing the data-properties.
`Maps.classify_specs`	a container for accessing the data classification specifications
`Maps.colorbar`	Get the most recently added colorbar of this Maps-object.

Layers and Maps#

`Maps.new_map`	Create a new map that shares the figure with this Maps-object.
`Maps.new_inset_map`	Create a new (empty) inset-map that shows a zoomed-in view on a given extent.

Maps.new_layer

Create a new Maps-object that shares the same plot-axes.

`Maps.new_layer_from_file`	A collection of methods to add a new layer to an existing Maps-object from a file.
`Maps.from_file`	A collection of methods to initialize a new Maps-object from a file.

`Maps.show_layer`	Show a single layer or (transparently) overlay multiple selected layers.
`Maps.fetch_layers`	Fetch (and cache) the layers of a map.
`Maps.on_layer_activation`	Attach a callback that is executed if the associated layer is activated.

Map Features#

`Maps.add_feature`	Interface to features provided by NaturalEarth.
`Maps.add_wms`	A collection of open-access WebMap services that can be added to the maps.

`Maps.add_gdf`	Plot a geopandas.GeoDataFrame on the map.
`Maps.add_annotation`	Add an annotation to the plot.
`Maps.add_marker`	Add a marker to the plot.
`Maps.add_line`	Draw a line by connecting a set of anchor-points.
`Maps.add_logo`	Add a small image (png, jpeg etc.) to the map.
`Maps.add_title`	Convenience function to add a title to the map.
`Maps.indicate_extent`	Indicate a rectangular extent in a given crs on the map.

`Maps.add_compass`	Add a "compass" or "north-arrow" to the map.
`Maps.add_gridlines`	Add gridlines to the map.
`Maps.add_scalebar`	Add a scalebar to the map.

Callbacks#

Maps.cb

Accessor for attaching callbacks and accessing return-objects.

`Maps.cb.click`	Callbacks that are executed if you click anywhere on the Map.
`Maps.cb.pick`	Callbacks that select the nearest datapoint if you click on the map.
`Maps.cb.keypress`	Callbacks that are executed if you press a key on the keyboard.
`Maps.cb.move`	Callbacks that are executed if you move the mouse without holding down a button.

Data visualization#

`Maps.set_data`	Set the properties of the dataset you want to plot.
`Maps.set_shape`	Set the plot-shape to represent the data-points.
`Maps.set_classify`	Interface to the classifiers provided by the 'mapclassify' module.
`Maps.set_classify_specs`	Set classification specifications for the data.

`Maps.inherit_data`	Use the data of another Maps-object (without copying).
`Maps.inherit_classification`	Use the classification of another Maps-object when plotting the data.

`Maps.plot_map`	Plot the dataset assigned to this Maps-object.
`Maps.add_colorbar`	Add a colorbar to the map.
`Maps.make_dataset_pickable`	Make the associated dataset pickable without plotting it first.

Map Extent#

`Maps.set_extent`	Set the extent (x0, x1, y0, y1) of the map in the given coordinate system.
`Maps.get_extent`	Get the extent (x0, x1, y0, y1) of the map in the given coordinate system.
`Maps.set_extent_to_location`	Set the map-extent based on a given location query.
`Maps.join_limits`	Join the x- and y- limits of the maps (crs must be equal!).

Layout and Export#

`Maps.savefig`	Save the current figure as an image or vector graphic to a file.
`Maps.snapshot`	Print a static image of the figure to the active IPython display.

`Maps.set_frame`	Set the properties of the map boundary and the background patch.
`Maps.subplots_adjust`	Update the subplot parameters of the grid.

`Maps.edit_layout`	Activate the "layout-editor" to quickly re-arrange the positions of subplots.
`Maps.get_layout`	Get the positions of all axes within the current plot.
`Maps.apply_layout`	Set the positions of all axes of the current figure based on a given layout.

Utilities#

`Maps.util`	A collection of utility tools that can be added to EOmaps plots.
`Maps.draw`	Base-class for drawing shapes on a map.
`Maps.edit_annotations`	Toggle if annotations are editable or not.

Miscellaneous#

`Maps.config`	Set global configuration parameters for figures created with EOmaps.
`Maps.BM`	Manager used to schedule draw events, cache backgrounds, etc.

`Maps.delay_draw`	A contextmanager to delay drawing until the context exits.
`Maps.fetch_companion_wms_layers`	Fetch (and cache) WebMap layer names for the companion-widget.
`Maps.refetch_wms_on_size_change`	Set the behavior of WebMap services with respect to size changes.
`Maps.cleanup`	Cleanup all references to the object so that it can be safely deleted.
`Maps.get_crs`	Get the pyproj CRS instance of a given crs specification.

`Maps.read_file.GeoTIFF`	Read all relevant information necessary to add a GeoTIFF to the map.
`Maps.read_file.NetCDF`	Read all relevant information necessary to add a NetCDF to the map.
`Maps.read_file.CSV`	Read all relevant information necessary to add a CSV-file to the map.

`Maps.show`	Show the map (only required for non-interactive matplotlib backends).
`Maps.redraw`	Force a re-draw of cached background layers.
`Maps.copy`	Create a (deep)copy of the Maps object that shares selected specifications.