Merge pull request #538 from martinRenou/choropleth_doc

GeoJSON/Choropleth/GeoData improvements

Author: martinRenou

docs/source/api_reference/choropleth.rst

@@ -45,8 +45,8 @@ Example
       m
 
 
-Information
------------
+Usage
+-----
 
 The ``Choropleth`` takes ``geo_data`` and ``choro_data`` as arguments.
 
@@ -69,23 +69,38 @@ The ``geo_data`` is a `GeoJSON
         }]
     }
 
-The ``choro_data`` is a dictionary that takes ``'id'`` from ``'features'`` as key and float as value, in order to build the colormap :
+The ``choro_data`` is a dictionary that maps an key to a float value, in order to build the colormap :
 
 .. code::
 
     {'AL': 7.1,
      'AK': 6.8}
 
 
+The ``Choropleth`` layer is then created specifying on which key the colormap is applied:
+
+.. code::
+
+    Choropleth(
+        geo_data=geo_data,
+        choro_data=choro_data,
+        key_on='id'
+    )
+
+
 Attributes
 ----------
 
-============   ==========================  ===========
-Attribute      Doc                         Description
-============   ==========================  ===========
-geo_data       Data dictionary             GeoJSON dictionary
-choro_data     Choropleth data dictionary  Dictionary id/float
-value_min      Color scale minimum value
-value_max      Color scale maximum value
-colormap       Map of color from branca
-============   ==========================  ===========
+==============   ==========================  ===========
+Attribute        Default                     Doc
+==============   ==========================  ===========
+geo_data         {}                          Data dictionary
+choro_data       {}                          Mapping key -> float data for constructing the colormap
+key_on           'id'                        Key used for the colormap construction
+value_min                                    Color scale minimum value
+value_max                                    Color scale maximum value
+colormap         OrRd_06                     Map of color from branca
+style                                        Style dictionary
+hover_style                                  Hover style dictionary
+style_callback                               Styling function that is called for each feature, and should return the feature style. This styling function takes the feature, the colormap function and the key data as arguments.
+==============   ==========================  ===========

docs/source/api_reference/geo_json.rst

@@ -6,11 +6,13 @@ Example
 
 .. jupyter-execute::
 
-    from ipyleaflet import Map, GeoJSON
-    import json
     import os
+    import json
+    import random
     import requests
 
+    from ipyleaflet import Map, GeoJSON
+
     if not os.path.exists('europe_110.geo.json'):
       url = 'https://github.com/jupyter-widgets/ipyleaflet/raw/master/examples/europe_110.geo.json'
       r = requests.get(url)
@@ -20,22 +22,51 @@ Example
     with open('europe_110.geo.json', 'r') as f:
       data = json.load(f)
 
+    def random_color(feature):
+        return {
+            'color': 'black',
+            'fillColor': random.choice(['red', 'yellow', 'green', 'orange']),
+        }
+
     m = Map(center=(50.6252978589571, 0.34580993652344), zoom=3)
-    geo_json = GeoJSON(data=data, style = {'color': 'green', 'opacity':1, 'weight':1.9, 'dashArray':'9', 'fillOpacity':0.1})
+
+    geo_json = GeoJSON(
+        data=data,
+        style={
+            'opacity': 1, 'dashArray': '9', 'fillOpacity': 0.1, 'weight': 1
+        },
+        hover_style={
+            'color': 'white', 'dashArray': '0', 'fillOpacity': 0.5
+        },
+        style_callback=random_color
+    )
     m.add_layer(geo_json)
+
     m
 
 
+Usage
+-----
+
+The ``GeoJSON`` layer is a widget, which means that you can update the ``data`` or any other attribute from Python and it will dynamically update the map:
+
+.. code::
+
+    geo_json.data = new_data
+    geo_json.hover_style = new_hover_style
+
+
 Attributes
 ----------
 
-============   ===
-Attribute      Doc
-============   ===
-data           Data dictionary
-style          Style dictionary
-hover_style    Hover style dictionary
-============   ===
+==============   ===
+Attribute        Doc
+==============   ===
+data             Data dictionary
+style            Style dictionary
+hover_style      Hover style dictionary
+style_callback   Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument.
+==============   ===
 
 Methods
 -------

examples/Choropleth.ipynb

@@ -36,8 +36,7 @@
     "layer = ipyleaflet.Choropleth(\n",
     "    geo_data=geo_json_data,\n",
     "    choro_data=unemployment,\n",
-    "    colormap=linear.YlOrRd_04, \n",
-    "    border_color='black',\n",
+    "    colormap=linear.YlOrRd_04,\n",
     "    style={'fillOpacity': 0.8, 'dashArray': '5, 5'}\n",
     ")"
    ]
@@ -62,7 +61,8 @@
     "def compute_style(feature, colormap, choro_data):\n",
     "    return {\n",
     "        'fillColor': colormap(choro_data),\n",
-    "        'weight': random.randint(1, 5),\n",
+    "        'color': 'white',\n",
+    "        'weight': random.randint(1, 3),\n",
     "    }"
    ]
   },
@@ -123,15 +123,6 @@
     "layer.colormap = linear.RdBu_11"
    ]
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "layer.border_color = 'white'"
-   ]
-  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -159,20 +150,6 @@
     "\n",
     "layer.on_hover(update_html)"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": []
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {
@@ -191,7 +168,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.3"
+   "version": "3.8.2"
   }
  },
  "nbformat": 4,

ipyleaflet/leaflet.py

@@ -547,7 +547,7 @@ def _validate_style_callback(self, proposal):
             raise TraitError('style_callback should be callable (functor/function/lambda)')
         return proposal.value
 
-    @observe('style', 'style_callback')
+    @observe('data', 'style', 'style_callback')
     def _update_data(self, change):
         self.data = self._get_data()
 
@@ -591,14 +591,13 @@ def on_hover(self, callback, remove=False):
 
 
 class GeoData(GeoJSON):
-
     geo_dataframe = Instance('geopandas.GeoDataFrame')
 
     def __init__(self, **kwargs):
         super(GeoData, self).__init__(**kwargs)
         self.data = self._get_data()
 
-    @observe('geo_dataframe')
+    @observe('geo_dataframe', 'style', 'style_callback')
     def _update_data(self, change):
         self.data = self._get_data()
 
@@ -619,8 +618,8 @@ def _update_bounds(self, change):
         self.value_min = min(self.choro_data.items(), key=lambda x: x[1])[1]
         self.value_max = max(self.choro_data.items(), key=lambda x: x[1])[1]
 
-    @observe('value_min', 'value_max', 'geo_data', 'choro_data', 'colormap')
-    def _update_choropleth_data(self, change):
+    @observe('style', 'style_callback', 'value_min', 'value_max', 'geo_data', 'choro_data', 'colormap')
+    def _update_data(self, change):
         self.data = self._get_data()
 
     @default('colormap')