👀 FAQ

Need some help to setup python for EOmaps?

Have a look at the Quickstart Guide to learn how to setup a python environment that can be used to create EOmaps maps!

Interested in contributing to EOmaps?

Have a look at the Contribution Guide on how to setup a development environment to start contributing to EOmaps! Any contributions are welcome!

Configuring the editor (IDE)

EOmaps can be used with whatever editor you like!

However, for some editors there are special settings that can be adjusted to improve your mapping experience with EOmaps:

Spyder

To use the whole potential of EOmaps with the awesome Spyder IDE , the plot-settings must be adjusted to ensure that matplotlib plots are created as interactive Qt widgets.

  • By default, figures are rendered as static images into the plots-pane. To avoid this and create interactive (popup) figures instead, go to the preferences and set the “Graphics Backend” to “Automatic” :

_images/spyder_preferences.png

Note

If the gaphics-backend is set to “Automatic”, you can still plot static snapshots of a figure to the “plots-pane” with Maps.snapshot()!

VSCode / VSCodium

In general, EOmaps should work “out of the box” with VSCode or the open-source variant VSCodium (together with the standard Python extension).

However, there are some tipps that might help with your mapping workflow:

  • In a normal python-terminal, the default matplotlib backend will be QtAgg in a non-interactive mode. This means that you must call Maps.show() at the end of the script to actually show the figure. Once the figure is shown, the terminal is blocked until the figure is closed.

  • To avoid blocking the terminal while a figure is running, you can activate matplotlib’s interactive-mode using

    from eomaps import Maps
Maps.config(use_interactive_mode=True)

    Once activated, figures are immediately shown as soon as a new Maps object is created and the terminal is not blocked (e.g. you can continue to execute commands that update the figure).

Note

If you run a whole script using the interactive mode, the script will run until the end and then usually terminate the associated kernel… and in turn also closing the figure! If you want to keep the figure open, either make sure that the terminal is kept alive by entering debug-mode, or avoid activating the interactive mode and block the terminal with m.show().

Interactive IPython (e.g. Jupyter)

If you enjoy interactive coding in a Jupyter-Notebook style, make sure to have a look at the nice Jupyter extension!

It allows you to work with an interactive IPython terminal and execute code-blocks (separated by the # %% indicator).

  • With IPython, the default behavior is to create static (inline) figures (same as with Jupyter Notebooks)!

    To print a snapshot of the current state of a figure to the IPython terminal, call Maps.show() or Maps.snapshot().

  • Similar to Jupyter Notebooks, you can use “magic” commands to set the used matpltolib backend.

    • For interactive (popup) figures, switch to the default Qt backend using %matplotlib qt

    • For interactive (inline) figures, you’ll need to install ipympl and then activate the widget with %matplotlib widget.

    • For more details, see details on Jupyter Notebooks below!

PyCharm

The PyCharm IDE automatically registers its own matplotlib backend which (for some unknown reason) freezes on interactive plots.

To my knowledge there are 2 possibilities to force pycharm to use the original matplotlib backends:

  • 🚲 The “manual” way:
    Add the following lines to the start of each script:
    (for more info and alternative backends see matplotlib docs)
    import matplotlib
matplotlib.use("Qt5Agg")
  • 🚗 The “automatic” way:
    Go to the preferences and add the aforementioned lines to the “Starting script”
    (to ensure that the matplotlib backend is always set prior to running a script)
    _images/pycharm_preferences.png

In addition, if you use a commercial version of PyCharm, make sure to disable “Show plots in tool window” in the Python Scientific preferences since it forces plots to be rendered as static images.

_images/pycharm_preferences_2.png
Jupyter Notebooks

When working with Jupyter Notebooks, we recommend to use Jupyter Lab.

  • By default, EOmaps will use the inline backend and put a static snapshot of the current state of the figure to the Jupyter Notebook cell whenever you call Maps.show() or Maps.snapshot().

  • To get interactive inline figures in Jupyter Notebooks, you have to switch to the ipympl (widget) backend.

    • To install, use conda install -c conda-forge ipympl

    • Once it’s installed, you can use the “magic command” %matplotlib widget at the start of the code to activate the backend.

Using the Companion Widget

To use the 🧰 Companion Widget in backends other than Qt the Qt event-loop must be integrated. This can be done with the %gui qt command.

%matplotlib widget
%gui qt

from eomaps import Maps
m = Maps()
m.add_feature.preset("coastline", "ocean")
Alternative backends

  • For classical notebooks, there’s also the nbagg backend provided by matplotlib

    • To use it, simply execute the magic %matplotlib notebook before starting to plot.

  • You can also use the magic %matplotlib qt to use the default qt5agg backend.

    • This way the plots will NOT be embedded in the notebook, they show up as interactive popup figures!

Note

Irrespective of the used backend, you can always plot a static snapshots of the current state of a map to a Jupyter Notebook with Maps.snapshot()!

%matplotlib qt    # Create figures as interactive popup widgets

from eomaps import Maps
m = Maps()
m.add_feature.preset("coastline", "ocean")
m.snapshot()      # Print a snapshot of the current state of the figure to the Jupyter Notebook

Checkout the matplotlib doc for more info!

Record interactive maps to create animations

The best way to record interactions on a EOmaps map is with the free and open source ScreenToGif software.

All animated gifs in this documentation have been created with this awesome piece of software.

LICENSING and redistribution

Information is provided WITHOUT WARRANTY FOR CORRECTNESS!

Since v8.0, the source-code of EOmaps is licensed under a BSD 3-clause license.

However, it must be notet that EOmaps has a number of required and optional dependencies whose licenses must be taken into account when packaging and redistributing works that build on top of EOmaps. While most dependencies are either BSD or MIT licensed, there are some dependencies that might require additional considerations.

Most notably (start of 2024), the required dependency cartopy is licensed under LGPLv3+ (however they are in the process of re-licensing to BSD-3-clause) and the optional Qt GUI framework is available via commertial and open-source (LGPLv3+) licenses and the used python-bindings (PyQt5) are licensed under GPL v3.

Tip

If you want to get a quick overview of the licenses of an existing pyhton environment, I recommend having a look at the pip-licenses package!

Important changes between major versions

⚙ From EOmaps v3.x to v4.x

Changes between EOmaps v3.x and EOmaps v4.0:

  • the following properties and functions have been removed:

    • ❌ m.plot_specs.

    • ❌ m.set_plot_specs()

    • arguments are now directly passed to relevant functions:
      m.plot_map(), m.add_colorbar() and m.set_data()

  • 🔶 m.set_shape.voroni_diagram() is renamed to m.set_shape.voronoi_diagram()

  • 🔷 custom callbacks are no longer bound to the Maps-object
    the call-signature of custom callbacks has changed to:
    def cb(self, *args, **kwargs) >> def cb(*args, **kwargs)

Porting a script from v3.x to v4.x is quick and easy and involves the following steps:

  1. Search your script for all occurrences of the words .plot_specs and .set_plot_specs(, move the affected arguments to the correct functions (and remove the calls once you’re done):

    • vmin, vmax alpha and cmap are now set in
      m.plot_map(vmin=..., vmax=..., alpha=..., cmap=...)
    • histbins, label, tick_precision and density are now set in
      m.add_colorbar(histbins=..., label=..., tick_precision=..., density=...)
    • cpos and cpos_radius are now (optionally) set in
      m.set_data(data, x, y, cpos=..., cpos_radius=...)

  2. Search your script for all occurrences of the words xcoord and ycoord and replace them with x and y

  3. ONLY if you used voronoi diagrams:

  • search in your script for all occurrences of the word voroni_diagram and replace it with voronoi_diagram

  1. ONLY if you used custom callback functions:

  • the first argument of custom callbacks is no longer identified as the Maps object.

  • if you really need access to the Maps object within the callback, pass it as an explicit argument!

EOmaps v3.x:

m = Maps()
m.set_data(data=..., xcoord=..., ycoord=...)
m.set_plot_specs(vmin=1, vmax=20, cmap="viridis", histbins=100, cpos="ul", cpos_radius=1)
m.set_shape.voroni_diagram()
m.add_colorbar()
m.plot_map()

# ---------------------------- custom callback signature:
def custom_cb(m, asdf=1):
    print(asdf)

m.cb.click.attach(custom_cb)

EOmaps v4.x:

m = Maps()
m.set_data(data=..., x=..., y=..., cpos="ul", cpos_radius=1)
m.plot_map(vmin=1, vmax=20, cmap="viridis")
m.set_shape.voronoi_diagram()
m.add_colorbar(histbins=100)

# ---------------------------- custom callback signature:
def custom_cb(**kwargs, asdf=None):
    print(asdf)

m.cb.click.attach(custom_cb, asdf=1)

Note: if you really need access to the maps-object within custom callbacks, simply provide it as an explicit argument!

def custom_cb(**kwargs, m=None, asdf=None):
    ...

m.cb.click.attach(custom_cb, m=m, asdf=1)
⚙ From EOmaps v5.x to v6.x

General changes in behavior

  • 🔶 Starting with EOmaps v6.0 multiple calls to m.plot_map()
    on the same Maps-object completely remove (and replace) the previous dataset!
    (use a new Maps-object on the same layer for datasets that should be visible at the same time!)
  • 🔶 WebMap services are no longer re-fetched by default when exporting images with m.savefig()
    To force a re-fetch of WebMap services prior to saving the image at the desired dpi, use m.savefig(refetch_wms=True)
    (see m.refetch_wms_on_size_change() for more details)
  • 🔷 m.add_gdf now uses only valid geometries
    (to revert to the old behavior, use: m.add_gdf(..., only_valid=False))

  • 🔷 the order at which multi-layers are combined now determines the stacking of the artists

    • m.show_layer("A|B") plots all artists of the layer "A" on top of the layer "B"

    • the ordering of artists inside a layer is determined by their zorder (e.g. m.plot_map(zorder=123))

Removed (previously depreciated) functionalities

  • ❌ the m.figure accessor has been removed!

    • Use m.ax, m.f, m.colorbar.ax_cb, m.colorbar.ax_cb_plot instead

  • ❌ kwargs for m.plot_map(...)

    • "coastlines" use m.add_feature.preset.coastline() instead

  • ❌ kwargs for m.set_data(...)

    • "in_crs" use "crs" instead

    • "xcoord" use "x" instead

    • "ycoord" use "y" instead

  • ❌ kwargs for Maps(...)

    • "parent" … no longer needed

    • "gs_ax" use "ax" instead

  • ❌ kwargs for m.new_inset_maps(...)

    • "edgecolor" and "facecolor" use boundary=dict(ec=..., fc=...) instead

  • ❌ kwargs for m.add_colorbar(...)

    • "histbins" use "hist_bins" instead

    • "histogram_size" use "hist_size" instead

    • "density" use "hist_kwargs=dict(density=...)" instead

    • "top", "bottom", "left", "right" use margin=dict(top=..., bottom=..., left=..., right=...) instead

    • "add_extend_arrows"

  • ❌ m.indicate_masked_points() has been removed, use m.plot_map(indicate_masked_points=True) instead

  • ❌ m.shape.get_transformer is now a private (e.g. m.shape._get_transformer)

  • ❌ m.shape.radius_estimation_range is now a private (e.g. m.shape._radius_estimation_range)

⚙ From EOmaps v6.x to v7.x

  • ⚠️ A lot of internal functions and classes have been re-named to better follow PEP8 naming conventions. While this should not interfere with the public API, more extensive customizations might need to be adjusted with respect to the new names.

    If you encounter any problems, feel free to open an issue , and I’ll see what I can do!

    • For example: the module _shapes.py is now called shapes.py and the class shapes is now called Shapes

  • ⚠️ The use of m.set_data_specs(...) is depreciated. Use m.set_data(...) instead!

  • Figure export routines have been completely re-worked (but should result in the exact same output as in v6.x)

⚙ From EOmaps v7.x to v8.x

  • ❗ Starting with v8.x eomaps is licensed under a “BSD 3 clause” license!

  • ⚠️ Some functions and classes have been re-named/moved to better follow PEP8 naming conventions. While this should not interfere with the public API, more extensive customizations might need to be adjusted with respect to the new names.

    • If you encounter any problems, feel free to open an issue , and I’ll see what I can do!

  • ⚠️ pip install has been updated to implement optional dependency groups.

    • ❗ pip install eomaps now only installs minimal dependencies required for eomaps

    • Have a look at the 🐛 Installation instructions for more details!

  • setup.py and _version.py have been removed in favor of using a pyproject.toml file

  • scripts for the examples have been re-named and are now located in docs\examples

  • Colorbar kwargs show_outline and ylabel have been renamed to outline and hist_label

The following (previously deprecated) methods are now removed:

  • m.set_data_specs -> use m.set_data instead

  • m.add_wms.DLR_basemaps… -> use m.add_wms.DLR.basemap... instead

  • m_inset.indicate_inset_extent -> use m_inset.add_extent_indicator instead

There have been substantial changes to the internals of the callback machinery

  • The public Maps API is unaffected

  • Changes are primarily in the modules cb_container.py and callbacks.py