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.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.