Update internal documentation in ChloroplethViz class; add chloroplet…

…h documentation to docs-markdown/viz.md template
mapbox · Feb 27, 2018 · 79fd36a · 79fd36a
1 parent 6b47dbc
commit 79fd36a
Show file tree

Hide file tree

Showing 3 changed files with 91 additions and 39 deletions.
diff --git a/docs-markdown/viz.md b/docs-markdown/viz.md
@@ -280,3 +280,61 @@ viz = HeatmapViz('points.geojson',
 viz.show()
 ```
 ![screen shot 2018-02-21 at 3 34 55 pm](https://user-images.githubusercontent.com/11286381/36511775-cfc4d794-171c-11e8-86b9-5f1a6060a387.png)
+
+
+## class ChloroplethViz
+
+The `ChloroplethViz` object handles the creation of a chloropleth map and is built on top of the `MapViz` class.
+
+### Params
+**ChloroplethViz**(_data, label_property=None, color_property=None, color_stops=None, color_default='grey', color_function_type='interpolate', line_color='white', line_stroke='solid', line_width=1, *args, **kwargs_)
+
+Parameter | Description | Example
+--|--|--
+data | name of GeoJson file or object
+label_property | property to use for marker label | "density"
+color_property | property to determine circle color | "density"
+color_stops | property to determine circle color | [[0, "red"], [0.5, "blue"], [1, "green"]]
+color_default | property to determine default circle color if match lookup fails | "#F0F0F0"
+color_function_type | property to determine `type` used by Mapbox to assign color | "interpolate"
+line_color | property to determine chloropleth line color | "#FFFFFF"
+line_stroke | property to determine chloropleth line stroke (one of solid, dashed, dotted, dash dot) | "solid"
+line_width | property to determine chloropleth line width | 1
+
+[View options](https://github.com/mapbox/mapboxgl-jupyter/blob/master/docs-markdown/viz.md#params)
+
+### Usage
+```python
+import os
+from mapboxgl.viz import *
+
+# Must be a public token, starting with `pk`
+token = os.getenv('MAPBOX_ACCESS_TOKEN')
+
+# Color stops
+color_stops = [
+    [0.0, 'rgb(255,255,204)'],
+    [100.0, 'rgb(255,237,160)'],
+    [500.0, 'rgb(253,141,60)'],
+    [2000.0, 'rgb(227,26,28)'],
+    [5000.0, 'rgb(189,0,38)'],
+    [10000.0,'rgb(128,0,38)']
+]
+
+# Create Chloropleth
+viz = ChloroplethViz('us-states.geojson', 
+                     access_token=token,
+                     color_property='density',
+                     color_stops=sample_color_stops,
+                     color_function_type='interpolate',
+                     line_stroke='dashed',
+                     line_color='rgb(128,0,38)',
+                     line_width=1,
+                     opacity=0.8,
+                     center=(-96, 37.8),
+                     zoom=3,
+                     below_layer='waterway-label
+                    )
+viz.show()
+```
+![screen shot 2018-02-26 at 4 54 59 pm](https://user-images.githubusercontent.com/13527707/36704653-186bb2e0-1b16-11e8-9dac-2d929e678be9.png)
diff --git a/examples/chloropleth-viz-example.ipynb b/examples/chloropleth-viz-example.ipynb
@@ -15,19 +15,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "import pandas as pd\n",
-    "import sys\n",
     "import os\n",
-    "\n",
     "from mapboxgl.viz import *\n",
-    "from mapboxgl.utils import *\n",
-    "from mapboxgl.colors import *\n",
     "\n",
     "# Must be a public token, starting with `pk`\n",
-    "token = os.getenv('MAPBOX_ACCESS_TOKEN')\n",
-    "\n",
-    "with open('us-states.geojson', 'r') as f:\n",
-    "    data = json.load(f)"
+    "token = os.getenv('MAPBOX_ACCESS_TOKEN')"
    ]
   },
   {
@@ -51,19 +43,19 @@
     "    [5000.0, 'rgb(189,0,38)'],\n",
     "    [10000.0,'rgb(128,0,38)']\n",
     "]\n",
-    "    \n",
-    "    \n",
-    "viz = ChloroplethViz(data, opacity=0.8)\n",
-    "viz.color_property = 'density'\n",
-    "viz.color_stops = sample_color_stops\n",
-    "viz.color_function_type = 'interpolate'\n",
-    "viz.default_color = '#bada55'\n",
-    "viz.line_stroke = 'dashed'\n",
-    "viz.line_color = 'rgb(128,0,38)'\n",
-    "viz.line_width = 1\n",
-    "viz.center = (-96, 37.8)\n",
-    "viz.zoom = 3\n",
-    "viz.below_layer = 'waterway-label'\n",
+    "   \n",
+    "viz = ChloroplethViz('us-states.geojson', \n",
+    "                     color_property='density',\n",
+    "                     color_stops=sample_color_stops,\n",
+    "                     color_function_type='interpolate',\n",
+    "                     line_stroke='dashed',\n",
+    "                     line_color='rgb(128,0,38)',\n",
+    "                     line_width=1,\n",
+    "                     opacity=0.8,\n",
+    "                     center=(-96, 37.8),\n",
+    "                     zoom=3,\n",
+    "                     below_layer='waterway-label'\n",
+    "                    )\n",
     "viz.show()"
    ]
   },
@@ -86,23 +78,18 @@
     "    ['California', 'rgb(142,68,173)'],\n",
     "]\n",
     "    \n",
-    "viz = ChloroplethViz(data, opacity=0.8)\n",
-    "viz.color_property = 'name'\n",
-    "viz.color_stops = match_color_stops\n",
-    "viz.color_function_type = 'match'\n",
-    "viz.color_default = 'rgba(52,73,94,0.5)'\n",
-    "viz.center = (-96, 37.8)\n",
-    "viz.zoom = 3\n",
-    "viz.below_layer = 'waterway-label'\n",
+    "viz = ChloroplethViz('us-states.geojson', \n",
+    "                     color_property='name', \n",
+    "                     color_stops = match_color_stops, \n",
+    "                     color_function_type = 'match', \n",
+    "                     color_default = 'rgba(52,73,94,0.5)', \n",
+    "                     opacity=0.8, \n",
+    "                     center = (-96, 37.8), \n",
+    "                     zoom = 3, \n",
+    "                     below_layer = 'waterway-label'\n",
+    "                    )\n",
     "viz.show()"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {

diff --git a/mapboxgl/viz.py b/mapboxgl/viz.py
@@ -279,7 +279,7 @@ def add_unique_template_variables(self, options):
 
 
 class ChloroplethViz(MapViz):
-    """Create a heatmap viz"""
+    """Create a chloropleth viz"""
 
     def __init__(self,
                  data,
@@ -295,7 +295,14 @@ def __init__(self,
                  **kwargs):
         """Construct a Mapviz object
 
-        :param weight_property: property to determine heatmap weight. EX. "population"
+        :param label_property: property to use for marker label
+        :param color_property: property to determine circle color
+        :param color_stops: property to determine circle color
+        :param color_default: property to determine default circle color if match lookup fails
+        :param color_function_type: property to determine `type` used by Mapbox to assign color
+        :param line_color: property to determine chloropleth line color
+        :param line_stroke: property to determine chloropleth line stroke (solid, dashed, dotted, dash dot)
+        :param line_width: property to determine chloropleth line width
 
         """
         super(ChloroplethViz, self).__init__(data, *args, **kwargs)