Merge pull request #63 from raphaelquast/dev

Merge for v3.4

.github/workflows/pre-commit.yml

@@ -5,7 +5,6 @@ name: pre-commit
 #  push:
 #    branches: [master, dev]
 on:
-    push:
     pull_request:
     # to trigger workflow manually from actions-tab
     workflow_dispatch:

.github/workflows/testMaps.yml

@@ -1,10 +1,9 @@
 name: test_Maps
 
 on:
-    push:
-    pull_request:
-    # to trigger workflow manually from actions-tab
-    workflow_dispatch:
+   pull_request:
+   # to trigger workflow manually from actions-tab
+   workflow_dispatch:
 
 jobs:
   build:

.pre-commit-config.yaml

@@ -9,6 +9,6 @@ repos:
         args: ["--markdown-linebreak-ext=md"]
     -   id: mixed-line-ending
 -   repo: https://github.com/psf/black
-    rev: 22.1.0
+    rev: 22.3.0
     hooks:
     -   id: black

docs/api.rst

@@ -13,23 +13,61 @@
 .. code-block:: python
 
     from eomaps import Maps
-    m = Maps(crs=4326)
+    m = Maps(crs=4326, layer="first layer", figsize=(10, 5))
     m.add_feature.preset.coastline()
 
+- ``crs`` represents the projection used for plotting
+- ``layer`` represents the name of the layer associated with the Maps-object (see below)
+- all additional keyword arguments are forwarded to the creation of the matplotlib-figure
+  (e.g.: ``figsize``, ``frameon``, ``edgecolor`` etc).
+
+
 Possible ways for specifying the crs for plotting are:
 
-- if you provide an ``integer``, it is identified as an epsg-code.
+- If you provide an integer, it is identified as an epsg-code (e.g. ``4326``, ``3035``, etc.).
 - All other CRS usable for plotting are accessible via ``Maps.CRS``,
   e.g.: ``crs=Maps.CRS.Orthographic()`` or ``crs=Maps.CRS.Equi7Grid_projection("EU")``.
+  (``Maps.CRS`` is just an accessor for ``cartopy.crs``)
 
-Once you have created your first ``Maps`` object, you can create **additional layers on the same map** by using:
+▤ Layers
+++++++++
+
+| Each ``Maps`` object represents an individual plot-layer of the map.
+| Once you have created your first ``Maps`` object, you can create **additional layers on the same map** by using:
 
 .. code-block:: python
 
-    m2 = m.new_layer(...)
+    m = Maps()    # same as `m = Maps(layer=0)`
+
+    # create a new layer
+    m2 = m.new_layer(layer="ocean")
+    # the ocean will only be visible if the "ocean" layer is visible.
+    m2.add_feature.preset.ocean()
+
+    # to add a feature to all layers, use `m.all`
+    m.all.add_feature.preset.coastline()
+
+    # show the "ocean" layer
+    m.show_layer("ocean")
+
+- ``m2`` and ``m.all`` are just ordinary ``Maps`` objects that share the figure and plot-axes with ``m``
+- If you don't provide an explicit layer name, the new Maps-object will use the same layer as its parent!
+  (you can have multiple ``Maps`` objects on the same layer!)
 
-(``m2`` is then just another ``Maps`` object that shares the figure and plot-axes with ``m``)
 
+.. note::
+    Features, datasets, colormaps etc. added to a ``Maps`` object are only visible if the associated layer is visible!
+    To manually switch between layers, use ``m.show_layer("the layer name")``, call ``m2.show()`` or have a look at the :ref:`utility`.
+
+.. note::
+
+    There is one layer-name that has a special meaning... the ``"all"`` layer.
+    Any callbacks, features or plots added to this layer will be **executed on all other layers** as well!
+
+    You can add features and callbacks to the ``all`` layer via:
+    - using the shortcut ``m.all. ...``
+    - creating a dedicated ``Maps`` object via ``m_all = Maps(layer="all")`` or ``m_all = m.new_layer("all")``
+    - using the "layer" kwarg of functions e.g. ``m.plot_map(layer="all")``
 
 .. currentmodule:: eomaps
 
@@ -40,9 +78,12 @@ Once you have created your first ``Maps`` object, you can create **additional la
 
     Maps
     Maps.new_layer
+    Maps.all
+    Maps.show_layer
     Maps.copy
 
 
+
 🔵 Setting the data and plot-shape
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -52,12 +93,16 @@ The shapes that are used to represent the data-points are then assigned via ``m.
 .. code-block:: python
 
     m = Maps()
-    m.set_data(data, xcoord, ycoord, parameter)
-    m.set_shape.rectangles(radius=1, radius_crs=4326)
-    m.plot_map()
+    m.add_feature.preset.ocean()           # add ocean-colors to the default layer (=0)
+    m.all.add_feature.preset.coastline()   # add coastlines to ALL layers
 
-    m2 = m.new_layer()
-    m2.set_data(...)
+    m2 = m.new_layer("data")
+    m2.set_data(data, xcoord, ycoord, parameter)
+    m2.set_shape.rectangles(radius=1, radius_crs=4326)
+    m2.plot_map()
+
+    m3 = m.new_layer("another layer")
+    m3.set_data(...)
     ...
 
 .. currentmodule:: eomaps
@@ -107,7 +152,6 @@ is performed (resampling based on the mean-value is used by default).
     You can install it via:
     ``conda install -c conda-forge datashader``
 
-
 .. image:: _static/minigifs/plot_shapes.gif
 
 
@@ -204,9 +248,12 @@ Some useful arguments that are supported by most shapes (except "shade"-shapes)
 .. code-block:: python
 
     m = Maps()
-    m.set_data(...)
+    m.add_feature.preset.coastline()
+
+    m2 = m.new_layer("a data layer")
+    m2.set_data(...)
     ...
-    m.plot_map(fc="none", ec="g", lw=2, alpha=0.5)
+    m2.plot_map(fc="none", ec="g", lw=2, alpha=0.5)
 
 
 You can then continue to add :ref:`colorbar`, :ref:`annotations_and_markers`,
@@ -242,19 +289,28 @@ and provides convenience-functions to perform actions on all maps of the figure.
 .. code-block:: python
 
     from eomaps import MapsGrid
-    mgrid = MapsGrid(r=2, c=2, crs=..., ... )
+    mg = MapsGrid(r=2, c=2, crs=..., layer=..., ... )
     # you can then access the individual Maps-objects via:
-    mgrid.m_0_0
-    mgrid.m_0_1
-    mgrid.m_1_0
-    mgrid.m_1_1
+    mg.m_0_0
+    mg.m_0_1
+    mg.m_1_0
+    mg.m_1_1
 
-    # to perform actions on all Maps-objects, simply loop over the MapsGrid object
-    for m in mgrid:
+    m2 = mg.m_0_0.new_layer("newlayer")
+    ...
+
+    # there are many convenience-functions to perform actions on all Maps-objects:
+    mg.add_feature.preset.coastline()
+    mg.add_compass()
+    ...
+
+    # to perform more complex actions on all Maps-objects, simply loop over the MapsGrid object
+    for m in mg:
         ...
 
     # set the margins of the plot-grid
-    mgrid.subplots_adjust(left=0.1, right=0.9, bottom=0.05, top=0.95, hspace=0.1, wspace=0.05)
+    mg.subplots_adjust(left=0.1, right=0.9, bottom=0.05, top=0.95, hspace=0.1, wspace=0.05)
+
 
 Custom grids and mixed axes
 ***************************
@@ -376,6 +432,15 @@ They can be attached to a map via:
 There are many pre-defined callbacks, but it is also possible to define custom
 functions and attach them to the map.
 
+.. Note::
+
+    Callbacks are only executed if the layer of the associated ``Maps`` object is actually visible!
+    (This assures that pick-callbacks always refer to the visible dataset.)
+
+    To define callbacks that are executed independent of the visible layer, attach it to the ``"all"``
+    layer using something like ``m.all.cb.click.attach.annotate()``.
+
+
 Pre-defined click & pick callbacks
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -495,14 +560,15 @@ and ``< LAYER >`` indicates the actual layer-name.
 
     Maps.add_wms
 
-
 .. note::
+
     It is highly recommended (and sometimes even required) to use the native crs
     of the WebMap service in order to avoid re-projecting the images
     (which degrades image quality and sometimes takes quite a lot of time to finish...)
 
     - most services come either in ``epsg=4326`` or in ``Maps.CRS.GOOGLE_MERCATOR`` projection
 
+
 .. table::
     :widths: 50 50
     :align: center
@@ -530,11 +596,6 @@ and ``< LAYER >`` indicates the actual layer-name.
 
 
 
-
-
-
-
-
 Pre-defined (global) WebMap services:
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -571,14 +632,14 @@ Services specific for Austria (Europa)
     Services might be nested directory structures!
     The actual layer is always added via the `add_layer` directive.
 
-        :code:`m.add_wms.<...>. ... .<...>.add_layer.<...>()`
+        :code:`m.add_wms.<...>. ... .<...>.add_layer.<LAYER NAME>()`
 
     Some of the services dynamically fetch the structure via HTML-requests.
     Therefore it can take a short moment before autocompletion is capable of
     showing you the available options!
     A list of available layers from a sub-folder can be fetched via:
 
-        :code:`m.add_wms.<...>. ... .<...>.layers`
+        :code:`m.add_wms.<...>. ... .<LAYER NAME>.layers`
 
 
 .. _geodataframe:
@@ -923,7 +984,21 @@ To indicate rectangular areas in any given crs, simply use ``m.indicate_extent``
 🌈 Colorbars (with a histogram)
 -------------------------------
 
-A colorbar with a colored histogram on top can be added to the map via ``m.add_colorbar``.
+| Before adding a colorbar, you must plot the data using ``m.plot_map()``.
+| A colorbar with a colored histogram on top can then be added to the map via ``m.add_colorbar``.
+
+.. note::
+    Colorbars are only visible if the layer at which the data was plotted is visible!
+
+    .. code-block:: python
+
+        m = Maps(layer=0)
+        ...
+        m.add_colorbar()   # this colorbar is only visible on the layer 0
+
+        m2 = m.new_layer("data")
+        ...
+        m2.add_colorbar()  # this colorbar is only visible on the "data" layer
 
 .. currentmodule:: eomaps
 
@@ -955,9 +1030,9 @@ A colorbar with a colored histogram on top can be added to the map via ``m.add_c
     +--------------------------------------------------------------------+------------------------------------------+
 
 .. note::
-    You must plot a dataset first! (e.g. by calling ``m.plot_map()``)
-    The colorbar always represents the dataset that was used in the last call to ``m.plot_map()``.
-    If you need multiple colorbars, use an individual layer for each dataset! (e.g. via ``m2  = m.new_layer()``)
+    | You must plot a dataset first! (e.g. by calling ``m.plot_map()``)
+    | The colorbar always represents the dataset that was used in the last call to ``m.plot_map()``.
+    | If you need multiple colorbars, use an individual ``Maps`` object for each dataset! (e.g. via ``m2  = m.new_layer()``)
 
 
 .. _scalebar:
@@ -1093,6 +1168,11 @@ To simplify switching between layers, there are currently 2 widgets available:
 - ``m.util.layer_selector()`` : Add a set of clickable buttons to the map that activates the corresponding layers.
 - ``m.util.layer_slider()`` : Add a slider to the map that iterates through the available layers.
 
+By default the widgets will show all available layers (except the "all" layer).
+
+- To show only a subset of layers, use ``layers=[...layer names...]``.
+- To exclude certain layers from the widget, use ``exclude_layers=[...layer-names to exclude...]``
+
 .. currentmodule:: eomaps.utilities.utilities
 
 .. autosummary::
@@ -1127,6 +1207,10 @@ To simplify switching between layers, there are currently 2 widgets available:
 
 EOmaps provides some basic capabilities to read and plot directly from commonly used file-types.
 
+By default, the ``Maps.from_file`` and ``m.new_layer_from_file`` functions try to plot the data
+with ``shade_raster`` (if it fails it will fallback to ``shade_points`` and finally to ``ellipses``).
+
+
 .. note::
 
     The readers are intended for well-structured datasets!
@@ -1231,9 +1315,6 @@ Similar to ``Maps.from_file``, a new layer based on a file can be added to an ex
     new_layer_from_file.CSV
 
 
-
-
-
 🔸 Miscellaneous
 ----------------
 some additional functions and properties that might come in handy:
@@ -1251,3 +1332,5 @@ some additional functions and properties that might come in handy:
     Maps.parent
     Maps.crs_plot
     Maps.add_colorbar
+    Maps.show
+    Maps.show_layer