A new major release that brings some nice new features, a lot of updates and some outstanding api-changes.
🌩 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](
https://eomaps.readthedocs.io/en/dev/FAQ.html#port-script-from-eomaps-v3-x-to-v4-x)
[or click on the text below for details!]
<details>
<summary>🔸 <code>m.plot_specs</code> and <code>m.set_plot_specs(...)</code> have been removed</summary>
- **"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(...)`
</details>
<details>
<summary>🔸 <code>voroni_diagram</code> is now correctly called <code>voronoi_diagram</code></summary>
This just fixes the typo in the name.
python
--- OLD ---
m.set_shape.voroni_diagram()
--- NEW ---
m.set_shape.voronoi_diagram()
</details>
<details>
<summary>🔸 The data-specs <code>xcoord</code> and <code>ycoord</code> have been renamed to <code>x</code> and <code>y</code></summary>
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.
python
--- OLD ---
m.set_data(data=..., xcoord=..., ycoord=..., ...)
m.data_specs.xcoord
--- NEW ---
m.set_data(data=..., x=..., y=..., ...)
m.data_specs.x
</details>
<details>
<summary>🔸 Custom callback functions now have a slightly different call-signature </summary>
> 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!)
python
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)
<details>
<summary> 👾 [click to show] how to get back the old behaviour </summary>
To get back the old behavior you have to "bind" the callback functions to the Maps-object, e.g:
python
m = Maps()
def cb(self, **kwargs):
...
m.cb.click.attach(cb.__get__(m))
or simply pass the Maps-object as kwarg, e.g.:
python
m = Maps()
def cb(self, **kwargs):
...
m.cb.click.attach(cb self=m)
</details>
</details>
🌳 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
python
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`
A fast way to plot 2D datasets.
<details>
<summary>[click to show] 🔸 details </summary>
- 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
</details>
🌈 there have been some major improvements for manual color specifications!
Checkout the [🌎 Customizing the plot](https://eomaps.readthedocs.io/en/dev/api.html#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=`)!
<details>
<summary>[click to show] 🔸 Possible ways to specify colors.</summary>
- 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:
python
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