Search…
Welcome
Docs
User guides
API Reference
Jupyter Notebook
Examples
Contributing
Change Log
Upgrade Guide
Powered By GitBook
Jupyter Notebook

Jupyter Notebook

kepler.gl for Jupyter User Guide

Table of contents

Install

Prerequisites

  • Python >= 2
  • ipywidgets >= 7.0.0
To install use pip:
1
$ pip install keplergl
Copied!
If you on Mac used pip install and running Notebook 5.3 and above, you don't need to run the following
1
$ jupyter nbextension install --py --sys-prefix keplergl # can be skipped for notebook 5.3 and above
2
$ jupyter nbextension enable --py --sys-prefix keplergl # can be skipped for notebook 5.3 and above
Copied!
If you are using Jupyter Lab, you will also need to install the JupyterLab extension. This require node > 10.15.0
If you use Homebrew on Mac:
1
$ brew install [email protected]
Copied!
Then install jupyter labextension.
1
$ jupyter labextension install @jupyter-widgets/jupyterlab-manager keplergl-jupyter
Copied!

Prerequisites for JupyterLab

  • Node > 10.15.0
  • Python 3
  • JupyterLab>=1.0.0

1. Load keplergl map

KeplerGl()

  • Input:
    • height optional default: 400
      Height of the map display
    • data dict optional
      Datasets as a dictionary, key is the name of the dataset. Read more on Accepted data format​
    • config dict optional
      Map config as a dictionary. The dataId in the layer and filter settings should match the name of the dataset they are created under
    • show_docs bool optional
      By default, the User Guide URL (https://docs.kepler.gl/docs/keplergl-jupyter) will be printed when a map is created. To hide the User Guide URL, set show_docs=False.
The following command will load kepler.gl widget below a cell. The map object created here is map_1 it will be used throughout the code example in this doc.
1
# Load an empty map
2
from keplergl import KeplerGl
3
map_1 = KeplerGl()
4
map_1
Copied!
You can also create the map and pass in the data or data and config at the same time. Follow the instruction to match config with data​
1
# Load a map with data and config and height
2
from keplergl import KeplerGl
3
map_2 = KeplerGl(height=400, data={"data_1": my_df}, config=config)
4
map_2
Copied!

2. Add Data

.add_data()

  • Inputs
    • data required CSV, GeoJSON or DataFrame. Read more on Accepted data format​
    • name required Name of the data entry.
name of the dataset will be the saved to the dataId property of each layer, filter and interactionConfig in the config.
kepler.gl expected the data to be CSV, GeoJSON, DataFrame or GeoDataFrame. You can call add_data multiple times to add multiple datasets to kepler.gl
1
# DataFrame
2
df = pd.read_csv('hex-data.csv')
3
map_1.add_data(data=df, name='data_1')
4
​
5
# CSV
6
with open('csv-data.csv', 'r') as f:
7
csvData = f.read()
8
map_1.add_data(data=csvData, name='data_2')
9
​
10
# GeoJSON as string
11
with open('sf_zip_geo.json', 'r') as f:
12
geojson = f.read()
13
​
14
map_1.add_data(data=geojson, name='geojson')
Copied!

.data

Print the current data added to the map. As a Dict
1
map_1.data
2
# {'data_1': 'hex_id,value\n89283082c2fffff,64\n8928308288fffff,73\n89283082c07ffff,65\n89283082817ffff,74\n89283082c3bffff,66\n8...`,
3
# 'data_3': 'location, lat, lng, name\n..',
4
# 'data_3': '{"type": "FeatureCollecti...'}
Copied!

3. Data Format

kepler.gl supports CSV, GeoJSON, Pandas DataFrame or GeoPandas GeoDataFrame.

CSV

You can create a CSV string by reading from a CSV file.
1
with open('csv-data.csv', 'r') as f:
2
csvData = f.read()
3
# csvData = "hex_id,value\n89283082c2fffff,64\n8928308288fffff,73\n89283082c07ffff,65\n89283082817ffff,74\n89283082c3bffff,66\n8..."
4
map_1.add_data(data=csvData, name='data_2')
Copied!

GeoJSON

According to GeoJSON Specification (RFC 7946): GeoJSON is a format for encoding a variety of geographic data structures. A GeoJSON object may represent a region of space (a Geometry), a spatially bounded entity (a Feature), or a list of Features (a FeatureCollection). GeoJSON supports the following geometry types: Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, and GeometryCollection. Features in GeoJSON contain a Geometry object and additional properties, and a FeatureCollection contains a list of Features.
kepler.gl supports all the GeoJSON types above excepts GeometryCollection. You can pass in either a single Feature or a FeatureCollection. You can format the GeoJSON either as a string or a dict type
1
feature = {
2
"type": "Feature",
3
"properties": {"name": "Coors Field"},
4
"geometry": {"type": "Point", "coordinates": [-104.99404, 39.75621]}
5
}
6
​
7
featureCollection = {
8
"type": "FeatureCollection",
9
"features": [{
10
"type": "Feature",
11
"geometry": {"type": "Point", "coordinates": [102.0, 0.5]},
12
"properties": {"prop0": "value0"}
13
}]
14
}
15
​
16
map_1.add_data(data=feature, name="feature")
17
map_1.add_data(data=featureCollection, name="feature_collection")
Copied!
Geometries (Polygons, LindStrings) can be embedded into CSV or DataFrame with a GeoJSON Json string. Use the geometry property of a Feature, which includes type and coordinates.
1
# GeoJson Feature geometry
2
geometryString = {
3
'type': 'Polygon',
4
'coordinates': [[[-74.158491,40.835947],[-74.148473,40.834522],[-74.142598,40.833128],[-74.151923,40.832074],[-74.158491,40.835947]]]
5
}
6
​
7
# create json string
8
json_str = json.dumps(geometryString)
9
​
10
# create data frame
11
df_with_geometry = pd.DataFrame({
12
'id': [1],
13
'geometry_string': [json_str]
14
})
15
​
16
# add to map
17
map_1.add_data(df_with_geometry, "df_with_geometry")
Copied!

DataFrame

kepler.gl accepts pandas.DataFrame​
1
df = pd.DataFrame(
2
{'City': ['Buenos Aires', 'Brasilia', 'Santiago', 'Bogota', 'Caracas'],
3
'Latitude': [-34.58, -15.78, -33.45, 4.60, 10.48],
4
'Longitude': [-58.66, -47.91, -70.66, -74.08, -66.86]})
5
​
6
w1.add_data(data=df, name='cities')
Copied!

GeoDataFrame

kepler.gl accepts geopandas.GeoDataFrame, it automatically converts the current geometry column from shapely to wkt string and re-projects geometries to latitude and longitude (EPSG:4326) if the active geometry column is in a different projection.
1
url = 'http://eric.clst.org/assets/wiki/uploads/Stuff/gz_2010_us_040_00_500k.json'
2
country_gdf = geopandas.read_file(url)
3
w1.add_data(data=country_gdf, name="state")
Copied!

WKT

You can embed geometries (Polygon, LineStrings etc) into CSV or DataFrame using WKT​
1
# WKT
2
wkt_str = 'POLYGON ((-74.158491 40.835947, -74.130031 40.819962, -74.148818 40.830916, -74.151923 40.832074, -74.158491 40.835947))'
3
​
4
df_w_wkt = pd.DataFrame({
5
'id': [1],
6
'wkt_string': [wkt_str]
7
})
8
​
9
map_1.add_data(df_w_wkt, "df_w_wkt")
Copied!

4. Customize the map

Interact with kepler.gl and customize layers and filters. Map data and config will be stored locally to the widget state. To make sure the map state is saved, select Widgets > Save Notebook Widget State, before shutting down the kernel.

5. Save and load config

.config

you can print your current map configuration at any time in the notebook
1
map_1.config
2
## {u'config': {u'mapState': {u'bearing': 2.6192893401015205,
3
# u'dragRotate': True,
4
# u'isSplit': False,
5
# u'latitude': 37.76209132041332,
6
# u'longitude': -122.42590232651203,
Copied!

Config panel

Config can be copied from the side panel with the {} icon.
When the map is final, you can copy this config and load it later to reproduce the same map. Follow the instruction to match config with data.
Apply config to a map:
  1. 1.
    Directly apply config to the map.
    1
    config = {
    2
    'version': 'v1',
    3
    'config': {
    4
    'mapState': {
    5
    'latitude': 37.76209132041332,
    6
    'longitude': -122.42590232651203,
    7
    'zoom': 12.32053899007826
    8
    }
    9
    ...
    10
    }
    11
    },
    12
    map_1.add_data(data=df, name='data_1')
    13
    map_1.config = config
    Copied!
  2. 2.
    Load it when creating the map
    1
    map_1 = KeplerGl(height=400, data={'data_1': my_df}, config=config)
    Copied!
If want to load the map next time with this saved config, the easiest way to do is to save the it to a file and use the magic command %run to load it w/o cluttering up your notebook.
1
# Save map_1 config to a file
2
with open('hex_config.py', 'w') as f:
3
f.write('config = {}'.format(map_1.config))
4
​
5
# load the config
6
%run hex_config.py
Copied!

6. Match config with data

All layers, filters and tooltips are associated with a specific dataset. Therefore the data and config in the map has to be able to match each other. The name of the dataset is assigned to:
  • dataId of layer.config,
  • dataId of filter
  • key in interactionConfig.tooltip.fieldToShow.
You can use the same config on another dataset with the same name and schema.

7. Save Map

When you click in the map and change settings, config is saved to widget state. Closing the notebook and reopen it will reload current map. However, you need to manually select Widget > Save Notebook Widget State before shut downing the kernel to make sure it will be reloaded.

.save_to_html()

  • input
    • data: optional A data dictionary {"name": data}, if not provided, will use current map data
    • config: optional map config dictionary, if not provided, will use current map config
    • file_name: optional the html file name, default is keplergl_map.html
    • read_only: optional if read_only is True, hide side panel to disable map customization
You can export your current map as an interactive html file.
1
# this will save current map
2
map_1.save_to_html(file_name='first_map.html')
3
​
4
# this will save map with provided data and config
5
map_1.save_to_html(data={'data_1': df}, config=config, file_name='first_map.html')
6
​
7
# this will save map with the interaction panel disabled
8
map_1.save_to_html(file_name='first_map.html', read_only=True)
Copied!

._repr_html_()

  • input
    • data: optional A data dictionary {"name": data}, if not provided, will use current map data
    • config: optional map config dictionary, if not provided, will use current map config
    • read_only: optional if read_only is True, hide side panel to disable map customization
You can also directly serve the current map via a flask app. To do that return kepler’s map HTML representation. Here is an example on how to do that:
1
from flask import Flask
2
​
3
app = Flask(__name__)
4
​
5
@app.route('/')
6
def index():
7
return map_1._repr_html_()
8
​
9
if __name__ == '__main__':
10
app.run(debug=True)
Copied!

Demo Notebooks

FAQ & Troubleshoot

1. What about windows?
keplergl is currently only published to PyPI, and unfortunately I use a Mac. If you encounter errors installing it on windows. This issue might shed some light. Follow this issue for conda support.
2. Install keplergl-jupyter on Jupyter Lab failed?
Make sure you are using node 8.15.0. and you have installed @jupyter-widgets/jupyterlab-manager. Depends on your JupyterLab version. You might need to install the specific version of jupyterlab-manager. with jupyter labextension install @jupyter-widgets/[email protected]. When use it in Jupyter lab, keplergl is only supported in JupyterLab > 1.0 and Python 3.
Run jupyter labextension install keplergl-jupyter --debug and copy console output before creating an issue.
If you are running install and uninstall several times. You should run.
1
jupyter lab clean
2
jupyter lab build
Copied!
2.1 JavaScript heap out of memory when installing lab extension
If you see this error during install labextension
1
$ FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory
Copied!
run
1
$ export NODE_OPTIONS=--max-old-space-size=4096
Copied!
3. Is my lab extension successfully installed?
Run jupyter labextension list You should see below. (Version may vary)
1
JupyterLab v1.1.4
2
Known labextensions:
3
app dir: /Users/xxx/jupyter-python3/ENV3/share/jupyter/lab
4
@jupyter-widgets/jupyterlab-manager v1.0.2 enabled OK
5
keplergl-jupyter v0.1.0 enabled OK
Copied!
4. What's your python and node env
Python
1
python==3.7.4
2
notebook==6.0.3
3
jupyterlab==2.1.2
4
ipywidgets==7.5.1
Copied!
Node (Only for JupyterLab)
1
node==8.15.0
2
yarn==1.7.0
Copied!
Previous
Localization
Next
Examples
Last modified 9mo ago
Copy link
Contents
Jupyter Notebook
kepler.gl for Jupyter User Guide
Install
1. Load keplergl map
2. Add Data
3. Data Format
4. Customize the map
5. Save and load config
6. Match config with data
7. Save Map
Demo Notebooks
FAQ & Troubleshoot