Update docs for VectorMixin class, vector properties and label proper…

…ties inherited from MapViz parent class
mapbox · Aug 18, 2018 · 3896dc3 · 3896dc3
1 parent 4ed345e
commit 3896dc3
Show file tree

Hide file tree

Showing 2 changed files with 91 additions and 93 deletions.
diff --git a/docs/viz.md b/docs/viz.md
@@ -20,27 +20,41 @@
 
 The `MapViz` class is the parent class of the various `mapboxgl-jupyter` visualizations. You can use this class to set default values for all visualizations rather than calling them directly from the other visualization objects.
 
+
 ### Params
-**MapViz**(_data, access_token=None, center=(0, 0), below_layer='', opacity=1, div_id='map', height='500px', style='mapbox://styles/mapbox/light-v9?optimize=true', width='100%', zoom=0, min_zoom=0, max_zoom=24, pitch=0, bearing=0, box_zoom_on=True, double_click_zoom_on=True, scroll_zoom_on=True, scroll_wheel_zoom_on=True, touch_zoom_on=True, legend=True, legend_layout='vertical', legend_gradient=False, legend_style='', legend_fill='white', legend_header_fill='white', legend_text_color='#6e6e6e', legend_text_numeric_precision=None, legend_title_halo_color='white', legend_key_shape='square', legend_key_borders_on=True_)
+**MapViz**(_data, vector_url=None, vector_layer_name=None, vector_join_property=None, data_join_property=None, disable_data_join=False, access_token=None, center=(0, 0), below_layer='', opacity=1, div_id='map', height='500px', style='mapbox://styles/mapbox/light-v9?optimize=true', label_property=None, label_size=8, label_color='#131516', label_halo_color='white', label_halo_width=1, width='100%', zoom=0, min_zoom=0, max_zoom=24, pitch=0, bearing=0, box_zoom_on=True, double_click_zoom_on=True, scroll_zoom_on=True, touch_zoom_on=True, legend=True, legend_layout='vertical', legend_gradient=False, legend_style='', legend_fill='white', legend_header_fill='white', legend_text_color='#6e6e6e', legend_text_numeric_precision=None, legend_title_halo_color='white', legend_key_shape='square', legend_key_borders_on=True_)
 
-Parameter | Description
---|--
-data | GeoJSON Feature Collection
-access_token | Mapbox GL JS access token.
-center | map center point
-style | url to mapbox style or stylesheet as a Python dictionary in JSON format
-div_id | The HTML div id of the map container in the viz
-width | The CSS width of the HTML div id in % or pixels.
-height | The CSS height of the HTML map div in % or pixels.
-zoom | starting zoom level for map
-opacity | opacity of map data layer
-pitch | starting pitch (in degrees) for map
-bearing | starting bearing (in degrees) for map
+Parameter | Description | Example
+--|--|--
+data | GeoJSON Feature Collection or JSON Join-Data | 
+vector_url | optional property to define vector data source (supported for basic MapViz, CircleViz, GraduatedCircleViz, HeatmapViz, ChoroplethViz, LinestringViz) | "mapbox://mapbox.mapbox-terrain-v2"
+vector_layer_name | property to define target layer of vector source | "contour"
+vector_join_property | property to aid in determining color for styling vector layer | "ele"
+data_join_property | property of json data to use as link to vector features | "elevation"
+disable_data_join | optional property to switch off default data-join technique using vector layer and JSON join-data; also determines if a layer filter based on joined data is applied to features in vector layer | False
+access_token | Mapbox GL JS access token. | 
+center | map center point | 
+below_layer |  | 
+style | url to mapbox style or stylesheet as a Python dictionary in JSON format | 
+div_id | The HTML div id of the map container in the viz | 
+width | The CSS width of the HTML div id in % or pixels. | 
+height | The CSS height of the HTML map div in % or pixels. | 
+zoom | starting zoom level for map | 
+min_zoom | min zoom level for displaying data layer on map | 
+max_zoom | max zoom level for displaying data layer on map | 
+opacity | opacity of map data layer | 
+pitch | starting pitch (in degrees) for map | 
+bearing | starting bearing (in degrees) for map | 
 box_zoom_on | boolean indicating if map can be zoomed to a region by dragging a bounding box | True
 double_click_zoom_on | boolean indicating if map can be zoomed with double-click | True
 scroll_zoom_on | boolean indicating if map can be zoomed with the scroll wheel | True
 scroll_wheel_zoom_on | boolean indicating if map can be zoomed with the scroll wheel | True
 touch_zoom_on | boolean indicating if map can be zoomed with two-finger touch gestures | True
+label_property | property to use for marker label.  No labels will be shown if omitted | None
+label_size | size of text labels | 8
+label_color | color of text labels | '#131516'
+label_halo_color | color of text halo outline | 'white'
+label_halo_width | width (in pixels) of text halo outline | 1
 legend | controls visibility of map legend | True
 legend_layout | controls orientation of map legend | 'horizontal'
 legend_style | reserved for future custom CSS loading | ''
@@ -51,7 +65,7 @@ legend_text_color | string color for legend text | '#6e6e6e'
 legend_text_numeric_precision | decimal precision for numeric legend values | 0
 legend_title_halo_color | color of legend title text halo | 'white'
 legend_key_shape | shape of the legend item keys, default varies by viz type; one of square, contiguous_bar, rounded-square, circle, line | 'square'
-legend_key_borders_on | boolean for whether to show/hide legend key borders | False
+legend_key_borders_on | boolean for whether to show/hide legend key borders | True
 
 ### Methods
 **as_iframe**(_self, html_data_)  
@@ -63,21 +77,32 @@ Display the visual in an iframe result cell of a Jupyter Notebook.
 **create_html**(_self_)  
 Build the HTML text representation of the visual. The output of this is a valid HTML document containing the visual object.
 
+
+## class VectorMixin
+
+The `VectorMixin` class is a parent class of the various `mapboxgl-jupyter` visualizations supporting vector source data that provides methods for developing the vector color, weight, height, line-width or intensity mapping for use with the data-join technique.  `CircleViz`, `GraduatedCircleViz`, `HeatmapViz`, `ChoroplethViz`, and `LinestringViz` support using a vector data source.
+
+### Methods
+**generate_vector_color_map**(_self_)  
+Generate color stops array for use with match expression in mapbox template.
+
+**generate_vector_numeric_map**(_self, numeric_property_)    
+Generate stops array for use with match expression in mapbox template.
+
+**check_vector_template**(_self_)  
+Determines if features are defined as vector source based on MapViz arguments.
+
+
 ## class CircleViz
 
 The `CircleViz` class handles the creation of a circle map and is built on top of the `MapViz` class.
 
 ### Params
-**CircleViz**(_data, label_property=None, label_size=8, label_color='#131516', label_halo_color='white', label_halo_width=1, radius=1, color_property=None, color_stops=None, color_default='grey', color_function_type='interpolate', stroke_color='grey', stroke_width=0.1, \*args, \*\*kwargs_)
+**CircleViz**(_data, radius=1, color_property=None, color_stops=None, color_default='grey', color_function_type='interpolate', stroke_color='grey', stroke_width=0.1, \*args, \*\*kwargs_)
 
 Parameter | Description
 --|--
-data | name of GeoJson file or object
-label_property | property to use for marker label.  No labels will be shown if omitted
-label_size | size of text labels
-label_color | color of text labels
-label_halo_color | color of text halo outline
-label_halo_width | width (in pixels) of text halo outline
+data | name of GeoJson file or object or JSON join-data
 color_property | property to determine circle color
 color_stops | property to determine circle color
 color_default | color of circle to use if no lookup value matches the property value. Only used for the **match** color_function_type.
@@ -130,18 +155,14 @@ viz.show()
 
 ## class ClusteredCircleViz
 
-The `ClusteredCircleViz` object handles the creation of a clustered circle map and is built on top of the `MapViz` class.  Cluster radius and color are keyed on point density.
+The `ClusteredCircleViz` object handles the creation of a clustered circle map and is built on top of the `MapViz` class.  Cluster radius and color are keyed on point density.  Vector data source is not supported for `ClusteredCircleViz`.
 
 ### Params
-**ClusteredCircleViz**(_data, label_size=8, label_color='#131516', label_halo_color='white', label_halo_width=1, color_stops=None, radius_stops=None, cluster_radius=30, cluster_maxzoom=14, radius_default=2, color_default='black', stroke_color='grey', stroke_width=0.1, \*args, \*\*kwargs_)
+**ClusteredCircleViz**(_data, color_stops=None, radius_stops=None, cluster_radius=30, cluster_maxzoom=14, radius_default=2, color_default='black', stroke_color='grey', stroke_width=0.1, \*args, \*\*kwargs_)
 
 Parameter | Description
 --|--
 data | name of GeoJson file or object
-label_size | size of text labels
-label_color | color of text labels
-label_halo_color | color of text halo outline
-label_halo_width | width (in pixels) of text halo outline
 color_stops | property to determine circle color
 radius_stops | property to determine circle radius
 cluster_radius | property to determine radius of each cluster when clustering points
@@ -177,16 +198,15 @@ color_stops = create_color_stops([1,10,50,100], colors='BrBG')
 
 viz = ClusteredCircleViz('points.geojson',
                           access_token=token,
-                          color_stops = color_stops,
-                          radius_stops = [[1,5], [10, 10], [50, 15], [100, 20]],
-                          radius_default = 2,
-                          cluster_maxzoom = 10,
-                          cluster_radius = 30,
-                          label_size = 12,
-                          opacity = 0.9,
-                          center = (-95, 40),
-                          zoom = 3
-                        )
+                          color_stops=color_stops,
+                          radius_stops=[[1,5], [10, 10], [50, 15], [100, 20]],
+                          radius_default=2,
+                          cluster_maxzoom=10,
+                          cluster_radius=30,
+                          label_size=12,
+                          opacity=0.9,
+                          center=(-95, 40),
+                          zoom=3)
 
 viz.show()
 ```
@@ -198,16 +218,11 @@ viz.show()
 The `GraduatedCircleViz` object handles the creation of a graduated map and is built on top of the `MapViz` class.
 
 ### Params
-**GraduatedCircleViz**(_data, label_property=None, label_size=8, label_color='#131516', label_halo_color='white', label_halo_width=1, color_property=None, color_stops=None, color_default='grey', color_function_type='interpolate', stroke_color='grey', stroke_width=0.1, radius_property=None, radius_stops=None, radius_default=2, radius_function_type='interpolate', \*args, \*\*kwargs_)
+**GraduatedCircleViz**(_data, color_property=None, color_stops=None, color_default='grey', color_function_type='interpolate', stroke_color='grey', stroke_width=0.1, radius_property=None, radius_stops=None, radius_default=2, radius_function_type='interpolate', \*args, \*\*kwargs_)
 
 Parameter | Description
 --|--
-data | name of GeoJson file or object
-label_property | property to use for marker label.
-label_size | size of text labels
-label_color | color of text labels
-label_halo_color | color of text halo outline
-label_halo_width | width (in pixels) of text halo outline
+data | name of GeoJson file or object or JSON join-data
 color_property | property to determine circle color.
 color_stops | property to determine circle color.
 color_default | color of the circle to use if no lookup value matches the property value. Only used for the **match** color_function_type.
@@ -253,16 +268,15 @@ radius_stops = create_radius_stops(radius_breaks, 0.5, 10)
 # Create the viz
 viz = GraduatedCircleViz('points.geojson',
                           access_token=token,
-                          color_property = "Avg Covered Charges",
-                          color_stops = color_stops,
-                          radius_property = "Avg Medicare Payments",
-                          stroke_color = 'black',
-                          stroke_width = 0.5,
-                          radius_stops = radius_stops,
-                          center = (-95, 40),
-                          zoom = 3,
-                          below_layer = 'waterway-label'
-                        )
+                          color_property='Avg Covered Charges',
+                          color_stops=color_stops,
+                          radius_property='Avg Medicare Payments',
+                          stroke_color='black',
+                          stroke_width=0.5,
+                          radius_stops=radius_stops,
+                          center=(-95, 40),
+                          zoom=3,
+                          below_layer='waterway-label')
 
 viz.show()
 ```
@@ -278,7 +292,7 @@ The `HeatmapViz` object handles the creation of a heat map and is built on top o
 
 Parameter | Description | Example
 --|--|--
-data | name of GeoJson file or object
+data | name of GeoJson file or object or JSON join-data
 weight_property | property to determine heatmap weight. | "population"
 weight_stops | stops to determine heatmap weight. | [[10, 0], [100, 1]]
 color_stops | stops to determine heatmap color. | [[0, "red"], [0.5, "blue"], [1, "green"]]
@@ -319,15 +333,14 @@ heatmap_weight_stops = create_weight_stops(color_breaks)
 #Create a heatmap
 viz = HeatmapViz('points.geojson',
                   access_token=token,
-                  weight_property = "Avg Medicare Payments",
-                  weight_stops = heatmap_weight_stops,
-                  color_stops = heatmap_color_stops,
-                  radius_stops = heatmap_radius_stops,
-                  opacity = 0.9,
-                  center = (-95, 40),
-                  zoom = 3,
-                  below_layer='waterway-label'
-                )
+                  weight_property='Avg Medicare Payments',
+                  weight_stops=heatmap_weight_stops,
+                  color_stops=heatmap_color_stops,
+                  radius_stops=heatmap_radius_stops,
+                  opacity=0.9,
+                  center=(-95, 40),
+                  zoom=3,
+                  below_layer='waterway-label')
 
 viz.show()
 ```
@@ -339,15 +352,11 @@ viz.show()
 The `ChoroplethViz` object handles the creation of a choropleth map and inherits from the `MapViz` class. It applies a thematic map style to polygon features with color shading in proportion to the intensity of the data being displayed. Choropleth polygons can be initialized with geojson source or vector source styled using the data-join technique.
 
 ### Params
-**ChoroplethViz**(_data, vector_url=None, vector_layer_name=None, vector_join_property=None, data_join_property=None, # vector only 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, height_property=None, height_stops=None, height_default=0.0, height_function_type='interpolate', *args, **kwargs_)
+**ChoroplethViz**(_data, color_property=None, color_stops=None, color_default='grey', color_function_type='interpolate', line_color='white', line_stroke='solid', line_width=1, height_property=None, height_stops=None, height_default=0.0, height_function_type='interpolate', *args, **kwargs_)
 
 Parameter | Description | Example
 --|--|--
 data | can be either GeoJSON (containing polygon features) or JSON for data-join technique with vector polygons |
-vector_url | optional property to define vector polygon source | "mapbox://mapbox.us_census_states_2015"
-vector_layer_name | property to define target layer of vector source if using vector polygon source | "states"
-vector_join_property | property to aid in determining color for styling vector polygons | "STATEFP"
-data_join_property | property of json data to use as link to vector features | "state_name"
 label_property | property to use for marker label | "density"
 color_property | property to determine fill color | "density"
 color_stops | property to determine fill color | [[0, "red"], [0.5, "blue"], [1, "green"]]
@@ -383,8 +392,7 @@ viz = ChoroplethViz('us-states.geojson',
                      opacity=0.8,
                      center=(-96, 37.8),
                      zoom=3,
-                     below_layer='waterway-label'
-                    )
+                     below_layer='waterway-label')
 viz.show()
 ```
 ![ChoroplethViz](https://user-images.githubusercontent.com/13527707/37823022-73782a0a-2e45-11e8-9fdd-4a8ddd35cb92.png)
@@ -415,18 +423,17 @@ from mapboxgl.viz import ImageViz
 img_url = 'https://raw.githubusercontent.com/mapbox/mapboxgl-jupyter/master/examples/mosaic.jpg'
 
 # Coordinates must be an array in the form of [UL, UR, LR, LL]
-coordinates = [
-    [-123.40515640309, 38.534294809274336],
-    [-115.92938988349292, 38.534294809274336],
-    [-115.92938988349292, 32.08296982365502],
-    [-123.40515640309, 32.08296982365502]]
+coordinates = [[-123.40515640309, 38.534294809274336],
+               [-115.92938988349292, 38.534294809274336],
+               [-115.92938988349292, 32.08296982365502],
+               [-123.40515640309, 32.08296982365502]]
 
 # Create the viz
 viz = ImageViz(img_url, coordinates, access_token=token,
-                height='600px',
-                center = (-119, 35),
-                zoom = 5,
-                below_layer = 'waterway-label')
+               height='600px',
+               center=(-119, 35),
+               zoom=5,
+               below_layer='waterway-label')
 viz.show()
 ```
 ![ImageViz](https://user-images.githubusercontent.com/10407788/37532428-5c8ff7a8-2915-11e8-8d03-2b258a0a53a8.jpg)
@@ -520,21 +527,12 @@ viz.show()
 The `LinestringViz` object handles the creation of a vector or GeoJSON-based Linestring visualization and inherits from the `MapViz` class.
 
 ### Params
-**LinestringViz**(_data, vector_url=None, vector_layer_name=None, vector_join_property=None, data_join_property=None, label_property=None, label_size=8, label_color='#131516', label_halo_color='white', label_halo_width=1, color_property=None, color_stops=None, color_default='grey', color_function_type='interpolate', line_stroke='solid', line_width_property=None, line_width_stops=None, line_width_default=1, line_width_function_type='interpolate', *args, **kwargs_)
+**LinestringViz**(_data, color_property=None, color_stops=None, color_default='grey', color_function_type='interpolate', line_stroke='solid', line_width_property=None, line_width_stops=None, line_width_default=1, line_width_function_type='interpolate', *args, **kwargs_)
 
 
 Parameter | Description | Example
 --|--|--
 data | can be either GeoJSON (containing polygon features) or JSON for data-join technique with vector polygons |
-vector_url | optional property to define vector linestring source | "mapbox://mapbox.mapbox-terrain-v2"
-vector_layer_name | property to define target layer of vector source if using vector linestring source | "contour"
-vector_join_property | property to aid in determining color for styling vector lines | "ele"
-data_join_property | property of json data to use as link to vector features | "elevation"
-label_property | property to use for marker label | "elevation"
-label_size | size of label text | 8
-label_color | color of label text | '#131516'
-label_halo_color | color of label text halo | 'white'
-label_halo_width | width of label text halo | 1
 color_property | property to determine line color | "elevation"
 color_stops | property to determine line color | [[0, "red"], [0.5, "blue"], [1, "green"]]
 color_default | property to determine default line color if match lookup fails | "#F0F0F0"
@@ -573,8 +571,7 @@ viz = LinestringViz(data,
                     opacity=0.8,
                     center=(-122.48, 37.83),
                     zoom=16,
-                    below_layer='waterway-label'
-                   )
+                    below_layer='waterway-label')
 viz.show()
 ```
 

diff --git a/mapboxgl/viz.py b/mapboxgl/viz.py
@@ -62,6 +62,7 @@ def generate_vector_numeric_map(self, numeric_property):
         return vector_stops
 
     def check_vector_template(self):
+        """Determines if features are defined as vector source based on MapViz arguments."""
 
         if self.vector_url is not None and self.vector_layer_name is not None:
             self.template = 'vector_' + self.template