Skip to content

Commit

Permalink
update documentation for keplergl-jupyter upgrade
Browse files Browse the repository at this point in the history 
1. add "Installation -- Using conda"
2. add notes for install keplergl for jupyterlab3
3. add section to setup local dev env for jupyter notebook and jupyterlab
4. add section to use KeplerGL in google colab
5. add comments for show() function

Signed-off-by: Xun Li <lixun910@gmail.com>
  • Loading branch information
@lixun910
lixun910 committed Aug 19, 2021
1 parent 26acd67 commit f438ccd
Show file tree
Hide file tree
Showing 2 changed files with 166 additions and 32 deletions.
182 changes: 150 additions & 32 deletions bindings/kepler.gl-jupyter/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,31 +14,61 @@ Table of contacts

## Installation

### Prerequisites
- Python >= 2
- ipywidgets >= 7.0.0
[![Anaconda-Server Badge](https://anaconda.org/conda-forge/keplergl/badges/version.svg)](https://anaconda.org/conda-forge/keplergl) [![PyPI version](https://badge.fury.io/py/keplergl.svg)](https://badge.fury.io/py/keplergl)

### Using conda:

To install use pip:
```shell
conda install -c conda-forge keplergl
```

#### Prerequisites
- Python >= 3.7

$ pip install keplergl
### Using pip:

```shell
pip install keplergl
```

#### Prerequisites
- For Kelplergl <= 0.3.0
- Python >= 2
- ipywidgets >= 7.0.0

### Installation Issues:

#### For Jupyter Notebook

If you on Mac used `pip install` and running Notebook 5.3 and above, you don't need to run the following

$ jupyter nbextension install --py --sys-prefix keplergl # can be skipped for notebook 5.3 and above
```shell
jupyter nbextension install --py --sys-prefix keplergl # can be skipped for notebook 5.3 and above

$ jupyter nbextension enable --py --sys-prefix keplergl # can be skipped for notebook 5.3 and above
jupyter nbextension enable --py --sys-prefix keplergl # can be skipped for notebook 5.3 and above
```

#### For JupyterLab

Note: to work with JupyterLab3, you need to install KeplerGL > 0.3.0. Otherwise, you will get the following error message:

> Error displaying widget: model not found
**For KeplerGL <= 0.3.0 and JupyterLab <=2:**

If you are in JupyterLab, you will also need to install the JupyterLab extension. This require [node](https://nodejs.org/en/download/package-manager/#macos) `> 8.15.0`

If you use [Homebrew](https://brew.sh/) on Mac:

$ brew install node@8
```shell
brew install node@8
```

Then install jupyter labextension.

$ jupyter labextension install @jupyter-widgets/jupyterlab-manager keplergl-jupyter
```shell
jupyter labextension install @jupyter-widgets/jupyterlab-manager keplergl-jupyter
```

**Prerequisites for JupyterLab:**
- Node > 8.15.0
Expand All @@ -48,6 +78,8 @@ Then install jupyter labextension.

## Quick Start

### For Jupyter Notebook and JupyterLab:

```python
# Load kepler.gl with an empty map
from keplergl import KeplerGl
Expand All @@ -72,6 +104,33 @@ map_1.config
map_1.save_to_html(file_name='keplergl_map.html')
```

### For Google Colab:

KeplerGL (>0.3.0) works with Google Colab. You can install it using pip or conda.

```python
# Install keplergl (>0.3.0)
!conda install keplergl

# Load Kepler.gl with an empty map
from keplergl import KeplerGl
map_1 = KeplerGl()

# Display map
map_1.show()
```

The function `show()` is newly introduced for displaying map in Google Colab. The function is defined as:
```python
def show(self, data=None, config=None, read_only=False, center_map=False)
```
with input parameters:
- data: a data dictionary {"name": data}, if not provided, will use current map data
- config: map config dictionary, if not provided, will use current map config
- read_only: if read_only is True, hide side panel to disable map customization
- center_map: if center_map is True, the bound of the map will be updated acoording to the current map data

Please note that the map is not interactive due to the limitation of Google Colab. For example, when applying config to the map in Colab, the map won't be updated and one needs to call `show()` again to render a new map in a new cell.

## Demo Notebooks
- [Load kepler.gl](https://github.com/keplergl/kepler.gl/blob/master/bindings/kepler.gl-jupyter/notebooks/Load%20kepler.gl.ipynb): Load kepler.gl widget, add data and config
Expand Down Expand Up @@ -110,31 +169,45 @@ You will need to install node, yarn and Jupyter Notebook.
Install [node](https://nodejs.org/en/download/package-manager/#macos) `> 10.15.0`, and [yarn](https://yarnpkg.com/en/docs/install#mac-stable). Use [nvm](https://github.com/creationix/nvm) for better node version management e.g. `nvm install 10`.


#### 2. Install Jupyter with pip
#### 2. Install Jupyter

Python 3
```bash
$ python3 -m pip install --upgrade pip
$ python3 -m pip install jupyter
- Using conda
```shell
conda install jupyter
```

Python 2
```bash
$ python -m pip install --upgrade pip
$ python -m pip install jupyter
- Using pip

```shell
pip install jupyter
```

#### 3. Install GeoPandas

- Using conda
```shell
conda install geopandas
```

- Using pip

```shell
pip install geopandas
```

### Download and run keplergl in your local Jupyter Notebook

#### Clone Repo
$ git clone https://github.com/keplergl/kepler.gl.git
```shell
git clone https://github.com/keplergl/kepler.gl.git
```

### Setup JS
#### 1. Install Js module
```sh
$ cd bindings/kepler.gl-jupyter
$ cd js
$ yarn
cd bindings/kepler.gl-jupyter
cd js
yarn
```

#### 2. Load mapbox token
Expand All @@ -145,7 +218,10 @@ export MapboxAccessTokenJupyter=<your_mapbox_token>
```

#### 3. Build js module, start a local server to watch for changes
$ npm start

```shell
npm start
```

You need to run step 2 and 3 to restart the js program. And step 1-3 if any js dependency has changed (Usually after pulling new changes from master).

Expand All @@ -155,27 +231,69 @@ You need to run step 2 and 3 to restart the js program. And step 1-3 if any js d
This command must be run **AFTER** the `js` setup, and folder `static/` was created. It only needs to be run once.

```sh
# dev install from folder containing setup.py
$ pip install -e .
# dev install from folder containing setup.py
pip install -e .

# only needed in dev mode, not in normal mode.
jupyter nbextension install --py --symlink --sys-prefix keplergl

# only needed in dev mode, not in normal mode.
jupyter nbextension enable --py --sys-prefix keplergl
```

NOTE: The above command `jupyter nbextension install -py --symlink --sys-prefix keplergl` is trying to create a symoblic link of the folder `bindings/kepler.gl-jupyter/keplergl/static` under the jupyter's folder `nbextensions`. Please check if there is already a folder "nbextensions/kepler-jupyter" existed, and you might need to remove it first.

# only needed in dev mode, not in normal mode.
$ jupyter nbextension install --py --symlink --sys-prefix keplergl
To find the location of `nbextensions` folder, you can use the following command:
```shell
$ where jupyter
/Users/test/opt/anaconda3/envs/test37/bin/jupyter

# only needed in dev mode, not in normal mode.
$ jupyter nbextension enable --py --sys-prefix keplergl
# the nbextensions should be at: /Users/test/opt/anaconda3/envs/test37/share/jupyter/nbextensions
```


#### 2. Start jupyter notebook
$ cd notebooks
$ jupyter notebook

```shell
cd notebooks
jupyter notebook
```


### Have fun!
#### Have fun!

You can now start editing the .js and .py files to see changes reflected in your local notebook. After changing files in the js folder, the local start script will recompile the js files and put them in to `keplergl/static` folder. You need to reload the jupyter notebook page to reload the files.


#### 3. Development for JupyterLab

To test the development work in previous 2 steps for JupyterLab. You can build the `keplergl labextension` under the `js` directory:

```shell
jupyter labextension build .
```

The output of the jupyter labextension is defined in the file `js/package.json`:
```javascript
...
"jupyterlab": {
"extension": "babel/labplugin",
"outputDir": "../keplergl-jupyter/labextension",
"sharedPackages": {
"@jupyter-widgets/base": {
"bundled": false,
"singleton": true
}
}
}
```

Then, you can either install this labextension to test it:
```shell
jupyter labextension install @jupyter-widgets/jupyterlab-manager keplergl-jupyter
```
or, you can manually create a symbolic link for the folder `bindings/kepler.gl-jupyter/kepler-jupyter/labextension` under the jupyter's folder `labextensions`, e.g. `/Users/test/opt/anaconda3/envs/test37/share/jupyter/labextensions`. You will need to reload the jupyter lab page.

[jupyter_widget]: https://d1a3f4spazzrp4.cloudfront.net/kepler.gl/documentation/jupyter_widget.png
[empty_map]: https://d1a3f4spazzrp4.cloudfront.net/kepler.gl/documentation/jupyter_empty_map.png
[geodataframe_map]: https://d1a3f4spazzrp4.cloudfront.net/kepler.gl/documentation/jupyter_geodataframe.png
Expand Down
16 changes: 16 additions & 0 deletions bindings/kepler.gl-jupyter/keplergl/keplergl.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,21 @@ def add_data(self, data, name="unnamed"):
self.data = copy

def show(self, data=None, config=None, read_only=False, center_map=False):
''' Display current map in Google Colab
Inputs:
- data: a data dictionary {"name": data}, if not provided, will use current map data
- config: map config dictionary, if not provided, will use current map config
- read_only: if read_only is True, hide side panel to disable map customization
- center_map: if center_map is True, the bound of the map will be updated acoording to the current map data
Example of use:
# this will display map in Google Colab
from keplergl import KeplerGL
map1 = KeplerGL()
map1.show()
'''
keplergl_html = resource_string(__name__, 'static/keplergl.html').decode('utf-8')
# find open of body
k = keplergl_html.find("<body>")
Expand All @@ -168,6 +183,7 @@ def _repr_html_(self, data=None, config=None, read_only=False, center_map=False)
- data: a data dictionary {"name": data}, if not provided, will use current map data
- config: map config dictionary, if not provided, will use current map config
- read_only: if read_only is True, hide side panel to disable map customization
- center_map: if center_map is True, the bound of the map will be updated acoording to the current map data
Returns:
- a html encoded string
Expand Down

0 comments on commit f438ccd

Please sign in to comment.