Merge pull request #26 from raphaelquast/dev

merge for v2.0.0

.gitignore

@@ -1,3 +1,8 @@
 __pycache__
 examples/.ipynb_checkpoints
 _additional
+docs/build
+docs/_build
+docs/debug.log
+docs/.vscode
+docs/generated

README.md

@@ -1,41 +1,36 @@
 [![tests](https://github.com/raphaelquast/EOmaps/actions/workflows/testMaps.yml/badge.svg?branch=master)](https://github.com/raphaelquast/EOmaps/actions/workflows/testMaps.yml)
 [![codecov](https://codecov.io/gh/raphaelquast/EOmaps/branch/dev/graph/badge.svg?token=25M85P7MJG)](https://codecov.io/gh/raphaelquast/EOmaps)
 [![pypi](https://img.shields.io/pypi/v/eomaps)](https://pypi.org/project/eomaps/)
+[![Documentation Status](https://readthedocs.org/projects/eomaps/badge/?version=latest)](https://eomaps.readthedocs.io/en/latest/?badge=latest)
 # EOmaps
 
-A general-purpose library to plot interactive maps of geographical datasets.
+### A library to create interactive maps of geographical datasets.
 
-#### 🌍 Get a simple interface to plot large (>1M datapoints) irregularly sampled geographical datasets  
-- Represent your data as shapes with actual geographic dimensions  
-- Reproject the map to any cartopy-projection
-- Add overlays to the maps (NaturalEarth features, geo-dataframes, etc.)  
-- Get a nice colorbar with a colored histogram on top  
+#### 🌍 Simple interface to visualize geographical datasets  
+- A `pandas.DataFrame` is all you need as input!
+  - plots of large (>1M datapoints) irregularly sampled datasets are generated in a few seconds!
+  - Represent your data as shapes with actual geographic dimensions
+  - Re-project the data to any crs supported by `cartopy`
+- Add annotations, overlays, WebMap-layers etc. to the maps
+- ... and get a nice colorbar with a colored histogram on top!
 
-#### 🌎 Easily turn the plot into a clickable data-analysis widget  
-- pick datapoints, add markers/annotations, create plots, execute custom functions etc.
+#### 🌎 Turn your maps into powerful interactive data-analysis widgets
+- Add "callbacks" to interact with your data
+   - Many pre-defined functions for common tasks are available!
+      - display coordinates and values, add markers, compare data-layers etc.
+      - ... or define your own function and attach it to the plot!
+- Maps objects can be interactively connected to analyze relations between datasets!
 
+#### 🛸 check out the [documentation](https://eomaps.readthedocs.io) for more details and [examples](https://eomaps.readthedocs.io/en/latest/EOmaps_examples.html)! 🛸
 
-#### 🛸 check out the example-notebook:  [EOmaps_examples](https://github.com/raphaelquast/maps/blob/dev/examples/EOmaps_examples.ipynb) 🛸
 
-![EOmaps example image](https://github.com/raphaelquast/EOmaps/blob/dev/examples/example_image.png?raw=true)
+![EOmaps example image](https://github.com/raphaelquast/EOmaps/blob/dev/docs/_static/fig2.gif?raw=true)
+
 
 ## install
-The recommended way to install EOmaps with conda + pip:
-
-1. (only if you're on WINDOWS)  
-   due to an issue with libspatialindex.dll for the conda-forge build of rtree, install rtree from default channel  
-   [(corresponding issue on rtree-feedstock)](https://github.com/conda-forge/rtree-feedstock/issues/31)
-   ```
-   conda install "rtree>=0.9.7"
-   ```
-2. install remaining dependencies from `conda-forge` channel
-   ```
-   conda install -c conda-forge numpy pandas geopandas "matplotlib>=3.0" "cartopy>=0.20.0" descartes mapclassify pyproj pyepsg
-   ```
-3. install EOmaps from pip
-   ```
-   pip install eomaps
-   ```
+
+Installing EOmaps can be done via `pip`. To make sure all dependencies are correctly installed, please have a look at the [🛸 installation instructions 🛸](https://eomaps.readthedocs.io/en/latest/usage.html#installation) in the documentation.
+
 
 ## basic usage
 ```python
@@ -47,29 +42,37 @@ data = pd.DataFrame(dict(lat=[...], lon=[...], value=[...]))
 
 # initialize Maps object
 m = Maps()
-
 # set the data
 m.set_data(data=data, xcoord="lon", ycoord="lat", parameter="value", crs=4326)
-
+# set the shapes that you want to use to represent the data-points
+m.set_shape.geod_circles(radius=10000) # (e.g. geodetic circles with 10km radius)
 # set the appearance of the plot
-m.set_plot_specs(plot_epsg=4326, cmap="viridis")
-# set the shapes that you want to assign to the data-points
-m.set_shape.geod_circles(radius=10000)
-
+m.set_plot_specs(crs=Maps.CRS, cmap="viridis")
 # (optionally) classify the data
-m.set_classify_specs(scheme=m.classify_specs.SCHEMES.Quantiles, k=5)
-
+m.set_classify_specs(scheme=Maps.CLASSIFIERS.Quantiles, k=5)
 # plot the map
 m.plot_map()
 ```
 #### attach callback functions to interact with the plot
 ```python
-m.cb.attach.annotate()
-m.cb.attach.mark(facecolor="r", edgecolor="g", shape="rectangles", radius=1, radius_crs=4326)
-m.cb.attach(<... a custom function ...>)
+# get a nice annotation if you click on a datapoint
+m.cb.pick.attach.annotate()
+# draw a marker if you click on a datapoint
+m.cb.pick.attach.mark(facecolor="r", edgecolor="g", shape="rectangles", radius=1, radius_crs=4326)
+
+# show the data-layer `1` in a inset-rectangle (size=20% width of the axes) if you click on the map
+m.cb.click.attach.peek_layer(how=0.2, layer=1)
+#attach some custom function to interact with the map
+m.cb.click.attach(<... a custom function ...>)
+
+# show the data-layer `1` if you press "a" on the keyboard and the layer `0` if you press "q"
+m.cb.keypress.attach.switch_layer(layer=0, key="q")
+m.cb.keypress.attach.switch_layer(layer=1, key="a")
 ```
 #### add additional layers and overlays
 ```python
+m.add_wms(...)             # add WebMapService layers
+m.add_wms(...)             # add WebMapTileService layers
 m.add_gdf(...)             # add geo-dataframes
 m.add_overlay(...)         # add overlay-layers from NaturalEarth
 
@@ -83,11 +86,29 @@ m.savefig("oooh_what_a_nice_figure.png", dpi=300)
 ## advanced usage
 #### connect Maps-objects to get multiple interactive layers of data!
 ```python
-m2 = Maps()
-m2.connect(m)       # connect the maps-objects
+m = Maps()
+...
+m.plot_map()
+
+m2 = Maps(parent=m) # connect Maps to get multiple interactive data-layers
 m2.set_data(...)
 m2.set_shape(...)
 ...
-m2.plot_map()       # plot another layer of data
-m2.cb.attach.annotate()
+m2.plot_map(layer=2)         # plot another layer of data
+m2.cb.attach.peek_layer(layer=2, how=0.25)
+```
+#### plot map-grids
+```python
+from eomaps import MapsGrid
+mgrid = MapsGrid(2, 2, connect=True)
+
+for m in mgrid:
+   m.plot_specs.plot_crs = 3857
+
+mgrid.ax_0_0.plot_map()
+mgrid.ax_0_1.plot_map()
+mgrid.ax_1_0.plot_map()
+mgrid.ax_1_1.plot_map()
+
+mgrid.parent.join_limits(*mgrid.children)   # join limits
 ```