EOmaps v3.0

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 in the doc which have been updated accordingly)

❗ details on breaking changes with respect to EOmaps v2.x - [click to expand]

• 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)

🌳 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

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)

# 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!

  # 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)