Merge 82f1f52 into 8c85d51

bindings/python/pydeck/docs/README.md

@@ -0,0 +1,4 @@
+pydeck API Documentation
+=========
+
+TODO This will be a table of contents for the pydeck documentation

bindings/python/pydeck/docs/data_utils.md

@@ -0,0 +1,104 @@
+pydeck.data\_utils
+=======
+
+## pydeck.data\_utils.compute\_viewport
+
+```python
+def compute_viewport(
+    points,
+    view_proportion=1,
+    viewport_type=pydeck.ViewState)
+```
+
+Computes a view state (zoom level and bounding box)
+for the points passed in.
+
+#### Parameters
+`points` : `list` of `list` of `float` or `pandas.core.frame`
+    A list of points
+`view_propotion` : `float`
+    Proportion of the data that will be viewable on the screen.
+    Useful for filtering outlying points from a visualization.
+`viewport_type` : `pydeck.ViewState`
+    Class constructor for a viewport
+
+#### Returns
+    `pydeck.Viewport` : Viewport fitted to the data
+
+
+## pydeck.data\_utils.assign\_random\_colors
+
+Produces a lookup table keyed by each class of data, with value as an RGB array
+
+This helps enable multi-class visualization in pydeck
+
+```python
+def assign_random_colors(data_vector)
+```
+
+#### Parameters
+
+`data_vector` : `list`
+    Vector of data classes to be categorized, passed from the data itself
+
+#### Returns
+    `collections.OrderedDict` : Dictionary of random RGBA value per class, keyed on class
+
+#### Examples
+
+See the PointCloudLayer notebook example, which uses many classes.
+
+As an illustration below, with a smaller data set of only two classes and three rows:
+
+```python
+    import pandas
+    data = pandas.DataFrame([
+    	{
+	    'site': 'Big Ben',
+	    'attraction_type': 'Clock Tower',
+	    'lat': 51.5006958,
+	    'lng': -0.1266639
+	},
+	{
+	    'site': 'Kensington Palace',
+	    'attraction_type': 'Palace':
+	    'lat': 51.5046188,
+	    'lng': -0.1839472
+	},
+    	{
+	    'attraction_type': 'Palace',
+	    'site': 'Buckingham Palace',
+	    'lat': 51.501364,
+	    'lng': -0.14189
+	}
+    ])
+    color_lookup = assign_random_colors(data['attraction_type'])
+    # Assign a color based on attraction_type
+    data['color'] = data.apply(lambda row: color_lookup.get(row['attraction_type']), axis=1)
+
+    # Data now has a color by attraction type:
+    #
+    # [
+    # 	{
+    #         'site': 'Big Ben',
+    #         'attraction_type': 'Clock Tower',
+    #         'lat': 51.5006958,
+    #         'lng': -0.1266639,
+    #         'color': [0, 10, 35]
+    #     },
+    #     {
+    #         'site': 'Kensington Palace',
+    #         'attraction_type': 'Palace':
+    #         'lat': 51.5046188,
+    #         'lng': -0.1839472,
+    #         'color': [53, 243, 130]
+    #     },
+    # 	{
+    #         'attraction_type': 'Palace',
+    #         'site': 'Buckingham Palace',
+    #         'lat': 51.501364,
+    #         'lng': -0.14189,
+    #         'color': [53, 243, 130]
+    #     }
+    # ]
+```

bindings/python/pydeck/docs/deck.md

@@ -0,0 +1,102 @@
+pydeck.Deck API Documentation
+==========
+
+## pydeck.Deck
+
+```python
+class pydeck.*Deck*(
+    layers=[],
+    views=[pydeck.View()],
+    map_style="mapbox://styles/mapbox/dark-v9",
+    mapbox_key=None, 
+    initial_view_state=pydeck.ViewState()
+)
+```
+
+Constructor for a Deck object, similar to the [Deck](https://deck.gl/#/documentation/deckgl-api-reference/deck) class from deck.gl
+
+Requires a Mapbox API token to display a basemap, see notes below.
+
+#### Parameters
+
+`layers` : `pydeck.Layer` or list of pydeck.Layer`, default `[]`
+    pydeck.Layer objects to render
+
+`views` : `list` of `pydeck.View`, default `[pydeck.View()]`
+    List of `pydeck.View` objects to render. If rendering a standard map, there is rarely a reason to modify this.
+
+`map_style` : `str`, default `"mapbox://styles/mapbox/dark-v9"`
+    URI for Mapbox basemap style
+
+`mapbox_key` : `str`, default None
+    Read on initialization from the MAPBOX_API_KEY environment variable. Defaults to None if not set.
+    If not using a basemap, you can set this value to `None`.
+    See https://docs.mapbox.com/help/how-mapbox-works/access-tokens/#mapbox-account-dashboard
+
+`initial_view_state` : `pydeck.ViewState`, default `pydeck.ViewState()`
+    Initial camera angle relative to the map, defaults to a fully zoomed out 0, 0-centered map with 0 pitch and bearing
+    To compute a viewport from data, see `pydeck.data\_utils.compute\_viewport`
+
+## pydeck.Deck.show
+
+```python
+pydeck.Deck.show(self)
+```
+
+Displays current Deck object for a Jupyter notebook
+
+## pydeck.Deck.update
+
+```python
+pydeck.Deck.update(self)
+```
+
+Updates a deck.gl map to reflect the current state of the configuration.
+
+For example, if you've modified data passed to Layer and rendered the map using `.show()`,
+you can call `update` to pass the new configuration to the map.
+
+Intended for use in a Jupyter notebook.
+
+## pydeck.Deck.to\_html
+
+```python
+pydeck.Deck.to_html(
+    self,
+    filename=None,
+    open_browser=False,
+    notebook_display=True,
+    iframe_width=500,
+    iframe_height=500)
+```
+Writes a file and loads it to an iframe, if `notebook\_display` is set to `True`.
+Otherwise, writes a file and optionally opens it in a web browser.
+
+The single HTML page uses RequireJS, a technology that requires
+Internet access to download the Javascript libraries which render a visualization.
+In other words, you will need an Internet connection or the visualization will
+not render.
+
+#### Parameters
+
+`filename` : `str`, default `None`
+    Name of the file. If no name is provided, a randomly named file will be written locally.
+
+`open_browser` : `bool`, default `False`
+    Whether to open the visualization in a browser after execution.
+
+`notebook_display` : `bool`, default `True`
+    Attempts to display the HTML output in an iframe if True. Only works in a Jupyter notebook.
+
+`iframe_width` : `int`, default `500`
+    Height of Jupyter notebook iframe in pixels, if rendered in a Jupyter notebook.
+
+`iframe_height` : `int`, default `500`
+    Width of Jupyter notebook iframe in pixels, if rendered in a Jupyter notebook.
+
+#### Returns
+    `str` : A string path to the HTML file
+
+#### Examples
+
+To add

bindings/python/pydeck/docs/layer.md

@@ -0,0 +1,38 @@
+pydeck.Layer API Documentation
+==========
+
+## pydeck.Layer
+
+```python
+class pydeck.Layer(
+    self,
+    type,
+    data,
+    id=None,
+    get_position='-',
+    **kwargs)
+```
+
+Constructs a geospatial layer for plotting.
+
+A catalog of available layers is viewable [here](https://github.com/uber/deck.gl/tree/master/docs/layers#deckgl-layer-catalog-overview).
+Note that this is Javascript documentation and parameters in pydeck usually will be snake-cased according to Python convention.
+
+#### Parameters
+
+`type` : `str`
+    Type of layer to render, e.g., `HexagonLayer`. See the layer catalog above.
+`data` : `str` or `list` of `dict` or `pandas.DataFrame`
+    A URL of data to load in, a list of dictionaries, 
+`id` : `str`, default `None`
+    Unique name for the layer. Will autopopulate with a UUID if no ID is provided.
+`get_position` : `str`, default `'-'`
+    Name of position field. If `'-'` is provided, the position field will be assumed to be the common case where a flat file has separate columns `lat` and `lng`.
+`**kwargs` : `int` or `str` or `float` or `bool` or `list`
+    Various other keyword arguments can be provided as well, provided they exist in the layer documentation.
+    For examples, `extruded=True` will extrude the underlying layer if this is a property it can have.
+    Fill color can be specified with `get_fill_color` as of RGBA values, e.g., `get_fill_color=[0, 0, 0]` for an all-black fill,
+    or as the name of a field of color values in the data, e.g., `get_fill_color='fill_color'`.
+
+#### Returns
+    `pdk.Layer` : Layer object

bindings/python/pydeck/docs/view_state.md

@@ -0,0 +1,42 @@
+pydeck.ViewState API Documentation
+=======
+
+## pydeck.ViewState
+
+```python
+class ViewState(
+    self,
+    longitude=0.0,
+    latitude=0.0,
+    zoom=10,
+    min_zoom=1,
+    max_zoom=21,
+    pitch=0,
+    bearing=0,
+    **kwargs)
+```
+
+An object that represents where the state of a viewport, essentially where the screen is focused.
+
+If you have two dimensional data and you don't want to set this manually, see `pydeck.data_utils.viewport_helpers.`compute_viewport`.
+
+#### Parameters
+
+`longitude` : `float`
+    x-coordinate of focus
+`latitude` : `float`
+    y-coordinate of focus
+`zoom` : `float`
+    Magnification level of the map, usually between 0 (representing the whole world) and 21 (close to individual buildings)
+`min_zoom` : `float`
+    Least magnified zoom level the user can navigate to
+`max_zoom` : float`
+    Most magnified zoom level the user can navigate to
+`pitch` : `float`
+    Up/down angle relative to the map's plane, with 0 being looking directly at the map
+`bearing` : `float`
+    Left/right angle relative to the map's true north, with 0 being aligned to true north
+
+
+#### Returns
+    `pydeck.ViewState` : Object indicating location of map viewport

bindings/python/pydeck/examples/01 - Introduction.ipynb

@@ -82,7 +82,7 @@
     "\n",
     "We also have to specifiy a **`ViewState`** object.\n",
     "\n",
-    "The **`ViewState`** object specifies a camera angle relative to the map data. If you don't want to manually specify it, the function **`pydeck.data_utils.autocompute_viewport`** can take your data and automatically zoom to it.\n",
+    "The **`ViewState`** object specifies a camera angle relative to the map data. If you don't want to manually specify it, the function **`pydeck.data_utils.compute_viewport`** can take your data and automatically zoom to it.\n",
     "\n",
     "pydeck also provides some controls, most of which should be familiar from map applications throughout the web. By default, you can hold out and drag to rotate the map."
    ]

bindings/python/pydeck/examples/02 - Scatterplots.ipynb

@@ -81,7 +81,7 @@
    "source": [
     "## Automatically generate a viewport\n",
     "\n",
-    "pydeck features some nifty utilities for visualizing data, like an **automatic zoom using `data_utils.autocompute_viewport`** for 2D data sets.\n",
+    "pydeck features some nifty utilities for visualizing data, like an **automatic zoom using `data_utils.compute_viewport`** for 2D data sets.\n",
     "\n",
     "We'll render the viewport, as well, just to verify that the visualization looks sensible."
    ]
@@ -93,7 +93,7 @@
    "outputs": [],
    "source": [
     "# Use pydeck's data_utils module to fit a viewport to the data\n",
-    "viewport = data_utils.autocompute_viewport(points=df[['lng', 'lat']], view_proportion=0.9)\n",
+    "viewport = data_utils.compute_viewport(points=df[['lng', 'lat']], view_proportion=0.9)\n",
     "auto_zoom_map = Deck(layers=None, initial_view_state=viewport)\n",
     "auto_zoom_map.show()"
    ]

bindings/python/pydeck/pydeck/bindings/deck.py

@@ -33,7 +33,7 @@ def __init__(
             URI for Mapbox basemap style
         initial_view_state : pydeck.ViewState, default pydeck.ViewState()
             Initial camera angle relative to the map, defaults to a fully zoomed out 0, 0-centered map
-            To compute a viewport from data, see `pydeck.data_utils.autocompute_viewport`
+            To compute a viewport from data, see `pydeck.data_utils.compute_viewport`
         mapbox_key : str, default None
             Read on initialization from the MAPBOX_API_KEY environment variable. Defaults to None if not set.
             See https://docs.mapbox.com/help/how-mapbox-works/access-tokens/#mapbox-account-dashboard

bindings/python/pydeck/pydeck/data_utils/__init__.py

@@ -1,3 +1,3 @@
-from .viewport_helpers import autocompute_viewport  # noqa
+from .viewport_helpers import compute_viewport  # noqa
 from .type_checking import is_pandas_df  # noqa
 from .color_scales import assign_random_colors  # noqa

bindings/python/pydeck/pydeck/data_utils/color_scales.py

@@ -13,7 +13,7 @@ def get_random_rgb():
 
 
 def assign_random_colors(data_vector):
-    """Produces a vector of lookup table keyed by each class of data, with value as an RGB array
+    """Produces lookup table keyed by each class of data, with value as an RGB array
 
     Parameters
     ---------

bindings/python/pydeck/pydeck/data_utils/viewport_helpers.py

@@ -143,7 +143,7 @@ def bbox_to_zoom_level(bbox):
     return zoom_level
 
 
-def autocompute_viewport(points, view_proportion=1, viewport_type=ViewState):
+def compute_viewport(points, view_proportion=1, viewport_type=ViewState):
     """Automatically computes a zoom level for the points passed in.
 
     Parameters

bindings/python/pydeck/tests/test_data_utils.py

@@ -1,7 +1,7 @@
 import pandas as pd
 
 from pydeck.data_utils.viewport_helpers import (
-    autocompute_viewport,
+    compute_viewport,
     bbox_to_zoom_level,
     euclidean,
     is_pandas_df,
@@ -48,9 +48,9 @@ def test_is_pandas_df():
     assert is_pandas_df(pd.DataFrame())
 
 
-def test_autocompute_viewport():
-    actual = autocompute_viewport(POINTS, 0.95, ViewState)
-    actual_pandas = autocompute_viewport(pd.DataFrame(POINTS), 0.95, ViewState)
+def test_compute_viewport():
+    actual = compute_viewport(POINTS, 0.95, ViewState)
+    actual_pandas = compute_viewport(pd.DataFrame(POINTS), 0.95, ViewState)
     EXPECTED = '{"bearing": 0, "latitude": 20.0, "longitude": 20.0, "maxZoom": 21, "minZoom": 1, "pitch": 0, "zoom": 7}'
     assert str(actual) == str(actual_pandas)
     assert str(actual) == str(EXPECTED)