You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This file describes the keplergl bindings for jupyter, i.e. the python package you can install as `keplergl` (see below).
6
+
7
+
It makes use of the `kepler.gl` javascript package, which is defined in `../..`, but pulls this dependency from [upstream](https://www.npmjs.com/package/kepler.gl).
8
+
Hence to build this binding it is _not_ required to build the parent project.
9
+
10
+
### Provided entities
11
+
12
+
The bindings actually provide two things:
13
+
14
+
- A JupyterLab/Jupyter Notebook extension, which is displayed/interacted with in your browser when using `jupyter`.
15
+
- A python package, that can be interacted with via `import keplergl` in python.
16
+
17
+
The python package bundles all of these together.
18
+
19
+
20
+
### Code organization
21
+
22
+
The python package is declared by `./pyproject.toml`.
23
+
The actual python code is in `./keplergl`.
24
+
This provides a jupyter widget (a `ipywidgets.DOMWidget`).
25
+
26
+
This python package contains and makes use of the javascript package `keplergl-jupyter`, which resides in [`./js`](./js).
27
+
It provides a [JupyterLab extension](https://jupyterlab.readthedocs.io/en/stable/extension/extension_dev.html) (see `./js/labplugin.js`) and a [Jupyter Notebook extension](https://nbclassic.readthedocs.io/en/latest/extending/index.html) (see `./js/extension.js`) which share all the 'functional' code to display the kepler.gl-widget.
28
+
29
+
When building the js code, this will generate javascript files in `./keplergl/static`.
30
+
When installing the python package, the code in `./js` is also automatically built (unless the build results are already there, i.e. if you manually built it).
31
+
32
+
Some example notebooks can be found in `./notebooks`.
33
+
34
+
35
+
### Release
36
+
37
+
See [`RELEASE.md`](RELEASE.md) for how this package is released.
38
+
39
+
40
+
## Setup
41
+
42
+
### Environment Setup
43
+
You will need to install node, yarn and Jupyter Notebook.
44
+
45
+
#### 1. Node and Yarn
46
+
We recommended to use [`nvm`](https://github.com/nvm-sh/nvm) to install `node` and to use `yarn` via `corepack`:
47
+
48
+
cd js
49
+
nvm install # this will install `node` in the version specified in `.nvmrc`
50
+
corepack enable
51
+
yarn # this will install yarn in the version specified in `yarn.lock`.
52
+
53
+
It may work to use other [node](https://nodejs.org/en/download/package-manager)`> 12` and [yarn](https://yarnpkg.com/getting-started/install) installations.
54
+
55
+
#### Jupyter
56
+
57
+
58
+
- Using conda
59
+
```shell
60
+
conda install jupyter
61
+
conda install notebook 6.0.1
62
+
```
63
+
64
+
- Using pip
65
+
(When working with `pip` you may want to first create a virtual environment via `python -m venv venv && source ./venv/bin/activate` -- on Ubuntu you will need to install `python3-venv` for that)
66
+
```shell
67
+
pip install jupyter
68
+
pip install notebook==6.0.1
69
+
```
70
+
71
+
#### 3. Install GeoPandas
72
+
73
+
- Using conda
74
+
```shell
75
+
conda install geopandas
76
+
```
77
+
78
+
- Using pip
79
+
80
+
```shell
81
+
pip install geopandas
82
+
```
83
+
84
+
### Download and run keplergl in your local Jupyter Notebook
The above command `jupyter nbextension install -py --symlink --sys-prefix keplergl` is trying to create a symoblic link from the folder `bindings/kepler.gl-jupyter/keplergl/static` into jupyter's folder `nbextensions`.
142
+
Please check if there folder `nbextensions/kepler-jupyter` already exists and if so, remove (or rename) it first.
143
+
144
+
To find the location of `nbextensions` folder, you can use the following command:
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.
170
+
171
+
172
+
#### 3. Development for JupyterLab
173
+
174
+
To target JupyterLab instead of Jupyter Notebook, use
175
+
176
+
```shell
177
+
pip install -e .# in this folder
178
+
cd js && jupyter labextension develop . --overwrite
179
+
cd ../notebooks && jupyter lab
180
+
```
181
+
for development.
182
+
This will automatically create the correct symlinks to let `jupyter lab` pick up the extension.
183
+
184
+
To build and install it use (in `./js`)
185
+
```shell
186
+
jupyter labextension build .
187
+
jupyter labextension install .
188
+
```
189
+
190
+
Alternatively you can build the extension via `jupyter labextension build .` and then manually create a symbolic link from the folder output folder `./kepler-jupyter/labextension` to JupyterLab's folder `labextensions`, e.g. `/Users/test/opt/anaconda3/envs/test37/share/jupyter/labextensions`. You will need to reload the jupyter lab page.
191
+
192
+
The output of the jupyter labextension is defined in the file `js/package.json`:
Copy file name to clipboardExpand all lines: bindings/kepler.gl-jupyter/README.md
+7-155Lines changed: 7 additions & 155 deletions
Original file line number
Diff line number
Diff line change
@@ -1,16 +1,15 @@
1
1
# kepler.gl for Jupyter
2
2
3
-
This is the [kepler.gl](http://kepler.gl) jupyter widget, an advanced geospatial visualization tool, to render large-scale interactive maps in Jupyter Notebook.
3
+
This is the [kepler.gl](http://kepler.gl) jupyter widget, an advanced geospatial visualization tool, to render large-scale interactive maps in Jupyter Notebook and JupyterLab.
4
4
5
-
![Kepler.gl for Jupyter][jupyter_widget]
5
+
6
6
7
-
Table of contacts
7
+
Table of contents
8
8
-[Installation](#installation)
9
9
-[Quick Start](#quick-start)
10
10
-[Demo Notebooks](#demo-notebooks)
11
11
-[Usage](#usage)
12
12
-[Local Development Setup](#local-development-setup)
13
-
-[FAQ & Troubleshoot](#faq--troubleshoot)
14
13
15
14
## Installation
16
15
@@ -199,8 +198,10 @@ Please note that the map is not interactive due to the limitation of Google Cola
199
198
-[GeoDataFrame](https://github.com/keplergl/kepler.gl/blob/master/bindings/kepler.gl-jupyter/notebooks/GeoDataFrame.ipynb): Load GeoDataFrame to kepler.gl
You will need to install node, yarn and Jupyter Notebook.
226
-
227
-
#### 1. Node and Yarn
228
-
Install [node](https://nodejs.org/en/download/package-manager/#macos)`> 12`, 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 12`.
229
-
230
-
231
-
#### 2. Install Jupyter
232
-
233
-
- Using conda
234
-
```shell
235
-
conda install jupyter
236
-
conda install notebook 6.0.1
237
-
```
238
-
239
-
- Using pip
240
-
241
-
```shell
242
-
pip install jupyter
243
-
pip install notebook==6.0.1
244
-
```
245
-
246
-
#### 3. Install GeoPandas
247
-
248
-
- Using conda
249
-
```shell
250
-
conda install geopandas
251
-
```
252
-
253
-
- Using pip
254
-
255
-
```shell
256
-
pip install geopandas
257
-
```
258
-
259
-
### Download and run keplergl in your local Jupyter Notebook
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.
306
-
307
-
To find the location of `nbextensions` folder, you can use the following command:
308
-
```shell
309
-
$ where jupyter
310
-
/Users/test/opt/anaconda3/envs/test37/bin/jupyter
311
-
312
-
# the nbextensions should be at: /Users/test/opt/anaconda3/envs/test37/share/jupyter/nbextensions
313
-
```
225
+
See file [`DEVELOPMENT.md`](DEVELOPMENT.md)
314
226
315
227
316
-
#### 2. Start jupyter notebook
317
-
318
-
```shell
319
-
cd notebooks
320
-
jupyter notebook
321
-
```
322
-
323
-
324
-
#### Have fun!
325
-
326
-
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.
327
-
328
-
329
-
#### 3. Development for JupyterLab
330
-
331
-
To test the development work in previous 2 steps for JupyterLab. You can build the `keplergl labextension` under the `js` directory:
332
-
333
-
```shell
334
-
jupyter labextension build .
335
-
```
336
-
337
-
The output of the jupyter labextension is defined in the file `js/package.json`:
338
-
```javascript
339
-
...
340
-
"jupyterlab": {
341
-
"extension":"babel/labplugin",
342
-
"outputDir":"../keplergl-jupyter/labextension",
343
-
"sharedPackages": {
344
-
"@jupyter-widgets/base": {
345
-
"bundled":false,
346
-
"singleton":true
347
-
}
348
-
}
349
-
}
350
-
```
351
-
352
-
Then, you can either install this labextension to test it:
353
-
```shell
354
-
jupyter labextension install .
355
-
```
356
-
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.
0 commit comments