Introducing kepler.gl for Jupyter

kepler.gl is an advanced geospatial visualization tool open sourced by Uber’s Visualization team in 2018 and contributed to the Urban Computing Foundation earlier this year. At Uber, kepler.gl is the defacto tool for geospatial data analysis.

In order to help data scientists work more effectively, we integrated kepler.gl into many widely used data analysis platforms, now including Jupyter Notebook. Jupyter Notebook is a popular open source web application used to create and share documents that contain live code, equations, visualizations, and text, commonly used among data scientists to conduct data analysis and share results. At Uber, data scientists have utilized this integration to analyze multitudes of geospatial data collected through the app, in order to better understand how people use Uber, and how to improve their trip experience. Now, everyone can leverage kepler.gl within Jupyter Notebook.

We integrated kepler.gl as a Jupyter Widget. It loads kepler.gl inside a notebook cell, allowing users to quickly plot maps with simple python commands and interact with the UI to customize the visualization (Figure 1). It provides a seamless analysis workflow, combining data querying, transformation, analysis, and visualization — all inside Jupyter Notebook.

Figure 1. Using kepler.gl in Jupyter Notebook to visualize geospatial data

How to use the kepler.gl widget on Jupyter Notebook

You can find the complete user guide and demo notebooks in the kepler.gl repo documentation folder.

First, install keplergl with pip.

$ pip install keplergl

Launch Jupyter Notebook either on your local machine or on the server.

$ jupyter notebook

Load the kepler.gl widget with the command below, and an empty kepler.gl map will be loaded below the cell (Figure 2.). You can use the `height` parameter to define window size.

Figure 2. Load an empty kepler.gl map

Now, let’s add data to the map. Like the kepler.gl app, the kepler.gl widget supports CSV and GeoJSON. In addition, it also supports Pandas DataFrame and GeoPandas GeoDataFrame. For more on supported data formats, go to the Data Format section of the user guide. Call add_data To add data to map. Dataset is required to have a name. Name is the id of the dataset in kepler.gl config, and will be used to link layers and filters to it.

After the data is loaded into the map, you can use the side panel to edit the layers, filters and base map style just like how you would with kepler.gl (Figure 3).

Figure 3. Interact with kepler.gl to edit layers and filters

When you are happy with the final result, print out the current map configuration using .config and save it for later to be used as a template (Figure 4).

When calling keplergl.KeplerGl(), you can pass in config and data values to initialize a predefined map. Pay attention to the name of the data and dataId saved in layer and filter config. They need to match each other for the config to be applied. Read more about match config with data.

kepler.gl also supports saving the map as an interactive HTML document with save_to_html.

kepler.gl map data and config are saved to iPython widget state. This allows the notebook file to be rendered with rendered map. Unfortunately, widget state is not automatically saved when the kernel shuts down. Which means in order to load the map after restarting the kernel, you need to manually save notebook widget state before shutting down the kernel (Figure 5).

Figure 5. Save widget state to preserve map

That’s it! This is all you need to know to use kepler.gl inside Jupyter Notebook. You can submit bug and feature request using our GitHub template. Make sure to share your maps and notebooks built with kepler.gl widget on Twitter with #keplergl or tag @heshan_cheri.