EOmaps v3.0 comes with a lot of usability improvements and some nice new features!
❗ NOTE: There are breaking changes compared to EOmaps v2.x
... if you used EOmaps before, make sure to take a quick look at the list below!
(or check the [examples](https://eomaps.readthedocs.io/en/latest/EOmaps_examples.html) in the doc which have been updated accordingly)
<details>
<summary> ❗ details on breaking changes with respect to EOmaps v2.x - [click to expand] </summary>
- Removed functions and properties: `m.add_overlay`, `m.add_coastlines`, `m.crs_list`
- Changed arguments and/or behavior: `Maps`, `MapsGrid`, `m.copy`, `m.plot_map`, `m.add_gdf`, `m.add_colorbar`
- New functions: `m.new_layer`, `m.add_feature`, `m.add_logo`, `m.cb.pick.highlight_geometry`
- ❗ `m.add_overlay` and `m.add_coastlines` have been removed in favor of `m.add_feature`
- ⭐ use `m.add_feature.<category>.<feature>( ... )` instead
- ❗ the `coastlines` as well as the `colorbar` argument for `m.plot_map()` have been removed
- ⭐ use `m.add_feature.preset.coastline()` or `m.ax.coastlines()` instead
- ⭐ use `m.add_colorbar()` after calling `m.plot_map()` to add a colorbar for an existing map
- ❗ the arguments and behavior of `m.copy(...)` have changed
(note that most of the time users anyway will want the new ⭐`m.new_layer()` function)
- all arguments of `m.copy` are now without the "copy_" prefix, e.g.: "data" instead of "copy_data" etc.
- ❗ the first argument of `Maps` is now the plot-crs (e.g. `Maps(crs=3857)` is the same as `m.plot_specs.crs=3857` )
and additional `kwargs` are forwarded to the initialization of the matplotlib-figure (e.g. `plt.figure`)
</details>
🌳 New
⭐ the plot coordinate-system is now specified directly on initialization of `Maps` object
- ❗ NOTE: this replaces `m.set_plot_specs(crs=...)` as well as `m.plot_specs.crs=...`
- additional kwargs are passed to the initialization of the `matplotlib` figure
python
m=Maps(crs=4326, figsize=(10,5))
⭐ there's a new function `m.new_layer()` that simplifies adding new layers to a map
- it simply returns a new `Maps` object that shares the figure and plot-axes.
⭐ EOmaps now supports multiple ways for providing datasets!
- a single `pandas.DataFrame` containing both values and coordinates (the only option for EOmaps < v2.4.2)
- individual `pandas.Series` for data-values and coordinates
- individual 1D or 2D `numpy.arrays` for data-values and coordinates
- individual 1D lists for data-values and coordinates
⭐ The new `m.add_feature` container provides direct access to ALL NaturalEarth features!
- ❗ NOTE: this replaces `m.add_overlay` and `m.add_coastlines`
- autocompletion helps with identifying the relevant NaturalEarth features
- e.g. `m.add_feature.physical_10m.<...feature...>(...)` or `m.add_feature.cultural_50m.<...feature...>(...)`
- with `geopandas` installed, NaturalEarth features can be interactive too!
(adding static layers works also without `geopandas`)
python
access specific NaturalEarth layers:
m.add_feature.cultural_50m.admin_0_countries(fc="red", ec="k", alpha=0.5)
there are some presets to quickly add commonly used features
m.add_feature.preset.ocean() (coastline, land, countries)
make the layers interactive (requires geopandas)!
m.add_feature.cultural_50m.admin_0_countries(fc="none", ec="k", picker_name="countries")
m.cb.pick["countries"].attach.highlight_geometry(fc="r")
⭐ there's a new function `m.add_logo` that can be used to add images to the map
- particularly useful to add a smal logo in the corner of a plot
⭐ a lot of improvements to `m.add_gdf`
- it is now possible to pick a geometry based on the closest `"centroids"` or based on a `"contains"` query
- with this, picking now also works for lines and points!
python
for picking lines and points
m.add_gdf(gdf, picker_name="pickername", pick_method="centroids")
m.cb.pick["pickername"].attach.<...>
for picking polygons
m.add_gdf(gdf, picker_name="pickername2", pick_method="contains")
m.cb.pick["pickername2"].attach.<...>
⭐ there's a new pre-defined callback `m.cb.pick[<name>].highlight_geometries`
- this callback is exclusive to `geopandas.GeoDataFrames` and allows highlighting a shape when you click on it!
⭐ `m.add_colorbar()` can now be used to add colorbars to existing Maps!
- ❗ NOTE: this replaces the old `colorbar`-argument of `m.plot_map()`
⭐ `MapsGrid` now supports additional functionalities
- use `MapsGrid(crs=...)` to specify the crs
(unique crs for each Maps-objects can be specified by passing `lists` or `dicts`)
- there are a lot of new convenience-functions to execute actions on all `Maps` objects on the grid:
- `mgrid.add_feature`, `mgrid.add_wms`, `mgrid.add_colorbar`, `mgrid.set_shape`, `mgrid.add_logo`
⭐ the plot-axis can now be accessed directly via `m.ax`
⭐ possible crs for plotting are now accessible via `Maps.CRS` and possible classifiers are accessible via `Maps.CLASSIFIERS`
🔧 fixes
- fix `m.cb.pick.plot` callback
- fix forwarding of event attributes
- treatment of point- or line-like NaturalEarth features
- fix `layer` kwarg for `m.add_gdf`
- a lot more unittests!
- allow positional arguments for `m.set_data` (or `m.set_data_specs`)