Eomaps

🌳 New

⭐ New bindings for the awesome [datashader](https://datashader.org/) library!
- Particularly useful to speed up plotting of **extremely large datasets** (>10M datapoints)
- Requires `datashader` to be installed (e.g. `conda install -c conda-forge datashader`)
- To use "datashader" for rendering the map, set the `plot-shape` to:
- `m.set_shape.shade_points(...)` :
use datashader to "shade" the data with infinitesimal points
- `m.set_shape.shade_raster(...)` :
(only for rectangular datasets with data_crs=plot_crs)
use datashader to "shade" the data as a dynamically updated QuadMesh

⭐ It is now possible to add a **Compass** (or a **North-Arrow**) to the map!
- simply use `c = m.add_compass(...)`
- the compass is dynamically updated on zoom events and can be dragged around with the mouse!

⭐ EOmaps now has some basic readers for common data-types (NetCDF, GeoTIFF, CSV)
- Requires `xarray`, `rioxarray` and `pandas`
- Use `gdf = m.read_file.NetCDF(...)` to read all relevant data
- Use `m = Maps.from_file.NetCDF(...)` to directly initialize a ``Maps``-object from a file
- Use `m2 = m.new_layer_from_file.NetCDF(...)` to add a new layer to an existing ``Maps`` object from a file

⭐ Support for Equi7Grid projection
- EOmaps now provides a cartopy-compatible crs for [Equi7Grid](https://github.com/TUW-GEO/Equi7Grid) projections!
- Requires `equi7grid` to be installed (e.g. `pip install equi7grid`)
python
from eomaps.projections import Equi7Grid_projection
m = Maps(Equi7Grid_projection("EU")


⭐ New clipping & re-projection methods for GeoDataFrames
- `m.add_gdf()` and `m.add_feature()` now have 2 new arguments: `reproject` and `clip`
(useful to avoid re-projection issues):
- `reproject` lets you select between geopandas (="gpd") and "cartopy" for re-projecting the geometries
- `clip` lets you select multiple ways for clipping the data prior to plotting
- "crs", "crs_bounds", "extent", "gdal_SymmetricDifference", "gdal_Intersection" and "gdal_Difference"

🌦️ changes
- The pixel-radius is now estimated using a more robust method if no explicit radius is provided.
- it's based on the median of the nearest-neighbour distances for the first 100k datapoints
- the number of datapoints used to estimate the radius can be adjusted by setting
`m.set_shape.radius_estimation_range `
- The `title` argument of `m.set_plot_specs` is now depreciated... use `m.ax.set_title()` instead!

⚙️ fixes
- fix `MapsGrid` crs-specifications with pyproj and `numpy`-dtypes
- fix skipping re-projection if "in-crs" == "plot_crs"
- fix `MapsGrid` has no attribute `preferred_wms_service`
- fix 'radius' estimation for shapes that do not explicitly require a radius
- fix background-layers need to be re-fetched if the figure canvas is resized
- clear data from memory if the figure is closed
- fix masking of nan-values prior to plotting
- `m.add_colorbar()` now supports setting the number of bins used to draw the histogram via the `histbins` kwarg
- make sure that zoom and close callbacks are only attached once to the figure
- fix delayed fetching of RestAPI services

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

A minor bugfix release

🔧 fixes
- fix nested copying of Maps objects with "connect=True"
- fix `EEA_DiscoMap` WMS service
- fix toolbar-action check if no toolbar exists
- fix `m.cb.dynamic.indicate_extent()` does not show extent right away
- ... update some warnings, remove obsolete functions and print-statements

⚙️ updates
- ... a lot of new unittests
- all examples from the doc are run during the unittests
- added tests for WebMap services
- added tests for interactive capabilities (scalebar, draggable axes, etc.)

🌳 New
- there's a new example in the docs to show how to analyse an underlying database
[🌌 Data analysis widgets - interacting with a database](https://eomaps.readthedocs.io/en/dev/EOmaps_examples.html#data-analysis-widgets-interacting-with-a-database)

🌻 NEW functionalities for `eomaps.MapsGrid` !
- It is now possible to use `Maps` objects alongside **ordinary matplotlib axes** with `MapsGrid` !
- 2 additional kwargs (`m_inits` and `ax_inits`) provide full control over the initialization of the MapsGrid object.

For example:
python
from eomaps import MapsGrid
mgrid = MapsGrid(2, 2,
m_inits=dict(top_row=(0, slice(0, 2)),
bottom_left=(1, 0)),
ax_inits=dict(bottom_right=(1,1))
)
mgrid.m_top_row A Maps object whose axis spans over the entire top-row of the grid
mgrid.m_bottom_left A Maps object with an axis in the bottom left corner of the grid
mgrid.ax_bottom_right An ordinary matplotlib axis in the bottom right corner of the grid


-------------

🔨 updates and fixes
- the creation of a colorbar-axes is now omitted in case `plot_map` is called without a dataset
- some doc updates
- from now on, a warning to install `geopandas` is only shown if a function that actually requires geopandas is called
(e.g. `add_overlay` and `add_gdf`)
- it is now possible to partially re-create an already closed figure
- attached callbacks are automatically re-assigned to the newly created figure
- all properties that are not related to the figure object remain unchanged in case the figure is closed
- ... however, any plot-functions (`plot_map`, `add_marker`, `add_wms` etc. ) must be called again!
- fix sharing of click events
- disable arrows in colorbar (for now) to ensure that the limits are correct

📏📏📏 There's an awesome new (fully customizable) **scalebar** feature available!
Checkout the new example in the docs! [>> Adding scalebars <<](https://eomaps.readthedocs.io/en/dev/EOmaps_examples.html#adding-scalebars-what-about-distances)
- You can now add a scalebar to the map via `m.add_scalebar()`
- works on any cartopy projection!
- Use mouse & keyboard to adjust the scalebar directly inside the plot
- drag the scalebar with the mouse!
- rotate it with the `+` and `-` keys
- remove it by pressing the `delete` key
- change the frame-width with the arrow-keys

🔧Fixes
- remove unnecessary print in `m.add_gdf`
- better testing for event-forwarding

some fixes and a new feature: pickable `geopandas.GeoDataFrames` >> [checkout the new example ](https://eomaps.readthedocs.io/en/latest/EOmaps_examples.html#using-geopandas-interactive-shapes)!

🌳 new
- It is now possible to use `geopandas.GeoDataFrames` for picking!
- first, use `m.add_gdf(picker_name="MyPicker")` to make the GeoDataFrame pickable
- then you can attach callbacks via `m.cb.MyPicker...` or `m.cb.pick["MyPicker"]...`
- you can also assign custom pickers for arbitrary artists via `m.cb.add_picker`
- callback-artists can now easily be made "temporary" via `m.cb.[click/pick].add_temporary_artist()`
🔨 fixes
- fix docstring issue with S1GBM wms service on python 3.10
- fix typo in MapsGrid when accessing individual objects via `mg[0,0]` instead of `mg.m_0_0`
- fix issues with shared callbacks for non-global projections
- always use the shape of the Maps object as default for markers (if possible)