Merge for EOmaps v4.0

[raphaelquast]

🌦️ changes

❗ There are breaking changes to EOmaps v3.x ❗
🌞 For a quick-guide on how to port existing scripts to v4.x see: ⚙️ port script from v3.x to v4.x

[or click on the text below for details!]

🔸 m.plot_specs and m.set_plot_specs(...) have been removed

• "vmin", "vmax" and "cmap" are now set when calling m.plot_map(...)
• "density", "tick_precision", "histbins" and "label" are now set when calling m.add_colorbar(...)
• "cpos" and "cpos_radius" are now set with m.set_data_specs(...)

🔸 voroni_diagram is now correctly called voronoi_diagram

This just fixes the typo in the name.

# --- OLD ---
m.set_shape.voroni_diagram()

# --- NEW ---
m.set_shape.voronoi_diagram()

🔸 The data-specs xcoord and ycoord have been renamed to x and y

This change is optional and will only raise a depreciation warning for now...
The old naming-convention will however be removed in future releases so it's highly recommended to use the new (shorter and more intuitive🙂) x and y variable names.

# --- OLD ---
m.set_data(data=..., xcoord=..., ycoord=..., ...)
m.data_specs.xcoord

# --- NEW ---
m.set_data(data=..., x=..., y=..., ...)
m.data_specs.x

🔸 Custom callback functions now have a slightly different call-signature

This removes the contra-intuitive "binding" of functions to the Maps-objects and ensures that class-methods can be used as callbacks without unwanted side-effects.

• The first argument is no longer identified automatically as the Maps-object!
  (if you need access to the underlying Maps-object, simply pass it as an argument!)

m = Maps()
def cb(m, **kwargs):
    pos = kwargs["pos"]
    print("the Maps-object:", m)
    print("the click-position is", pos)

m.cb.click.attach(cb, m=m)

👾 [click to show] how to get back the old behaviour

To get back the old behavior you have to "bind" the callback functions to the Maps-object, e.g:

m = Maps()
def cb(self, **kwargs):
    ...

m.cb.click.attach(cb.__get__(m))

or simply pass the Maps-object as kwarg, e.g.:

m = Maps()
def cb(self, **kwargs):
    ...

m.cb.click.attach(cb self=m)

🌳 NEW

• ⭐ The Sentinel-2 cloudless WebMap service can now be used via m.add_wms.s2_cloudless
• 🌟 It is now possible to set "coordinate-only" datasets!
  • This is particularly useful if you want to manually assign colors

  m.set_data(None, [1,2,3], [1,2,3])
  m.plot_map(fc=["r", "g", "b"])

🚀 there's a new plot shape! m.set_shape.raster

• works only with 2D datasets
• it's quite similar to plt.imshow (e.g. a QuadMesh is used to speed up plotting of 2D datasets)
• the differences to shade_raster are:
  • the whole dataset is always plotted (so for very very large datasets shade_raster is much faster!)
  • it supports manual color specifications (shade_raster does not)
• the differences between rectangles and raster are:
  • raster does not take the curvature of the edges into account
  • raster determines the pixel-size based on neighboring pixels, rectangles allows arbitrary pixel-dimensions

🌈 there have been some major improvements for manual color specifications!

Checkout the 🌎 Customizing the plot section of the docs for details!

Colors can now be set manually with all shapes (except shade shapes) using
m.plot_map(fc=[...]) (or facecolor= or color=)!

Several ways to specify colors are supported:

• a single value (RGB/RGBA tuple, a matplotlib color-name or a hex-color)
• a tuple of 3/4 arrays in the same shape as the coordinates (identified as RGB/RGBA values)
• a list/array of RGB tuples, e.g. [(1, 0, 0.25), (0.3, 0.4, 0.5), ....]
• a list/array of RGBA tuples, e.g.: [(1, 0, 0.25, 0.15), (0.3, 0.4, 0.5, 0.25), ....]
• a list/array of matplotlib named-colors, e.g. ["r", "olive", "darkblue", ...]
• a list/array of hex-colors, e.g.: ['#ff0040', '#4c6680', ...]
  For example:

m = Maps()
m.set_data(None, [1,2,3,4,5], [1,2,3,4,5])
# use named colors
m.plot_map(ec="k", fc=["r", "olive", "darkblue", "orange", "indigo"])
# or RGB tuples
m.plot_map(color=[(1, 0, 0), (.4, .5, .6), (.2, .7, .2), (.45, .12, .98), (.94, .45, .56)])
# or a single color for all datapoints
m.plot_map(facecolor="g", edgecolor="r")
# or use 3 individual arrays that should be identified as RGB values
m.plot_map(fc=([0.1,0.2,0.3,0.4,0.5], [0.1,0.2,0.3,0.4,0.5], [0.1,0.2,0.3,0.4,0.5])

☁️ minor (non-breaking) changes

• the default radius_crs for the mark callback is now determined based on the radius_crs assigned in the plot-shape
  ... this definition allows using m.cb.pick.attach.mark(buffer=3) directly without having to worry about the crs
  (previously in, e.g. the input-crs was used by default)
• the background patch of the compass is now by default set to None

🔨 fixes

• fix issues with manual color specifications for various plot-shapes
  (e.g. when providing explicit color-arrays via m.plot_map(color=[...]) )
• fix issues with shapes close to crs-bounds
• support estimation of different x- and y- radius for 2D datasets
• warn if datapoints are masked or if datapoints are outside the CRS-bounds
• cache shape transformers (so they are not re-initialized all the time)

[codecov-commenter]

Codecov Report

Merging #71 (6421810) into master (cc7fdf2) will decrease coverage by 2.27%.
The diff coverage is 56.45%.

❗ Current head 6421810 differs from pull request most recent head 8a62e85. Consider uploading reports for the commit 8a62e85 to get more accurate results

@@            Coverage Diff             @@
##           master      #71      +/-   ##
==========================================
- Coverage   73.94%   71.67%   -2.28%     
==========================================
  Files          12       12              
  Lines        5323     5669     +346     
==========================================
+ Hits         3936     4063     +127     
- Misses       1387     1606     +219     

Impacted Files	Coverage Δ
eomaps/reader.py	17.94% <0.00%> (+0.87%)	⬆️
eomaps/eomaps.py	65.25% <45.51%> (-5.95%)	⬇️
eomaps/_shapes.py	72.07% <58.51%> (-8.55%)	⬇️
eomaps/_containers.py	69.51% <64.70%> (-1.66%)	⬇️
eomaps/helpers.py	76.19% <81.81%> (+0.66%)	⬆️
eomaps/_cb_container.py	79.19% <83.67%> (+0.51%)	⬆️
eomaps/callbacks.py	86.47% <89.47%> (-0.49%)	⬇️
eomaps/utilities.py	65.28% <90.00%> (+0.96%)	⬆️
eomaps/scalebar.py	83.33% <95.45%> (+0.02%)	⬆️
... and 2 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 6439af4...8a62e85. Read the comment docs.