Skip to content

Commit 8033578

Browse files
distefanodevinjigorDykhtalixun910ilyabo
authored
[docs] update docs for Kepler.gl release 3.1 (#2941)
- Added a new release notes/what's new section to show new user-facing features (not a replacement for the changelog, which is a complete timeline of all kepler.gl development) - Vector tile layer page - AI assistant page - SQL explorer/duckdb page - Updates to ToCs --------- Signed-off-by: distefanodevinj <ddistefano@foursquare.com> Co-authored-by: Igor Dykhta <igorDykhta@users.noreply.github.com> Co-authored-by: Xun Li <lixun910@gmail.com> Co-authored-by: Ilya Boyandin <ilya@boyandin.me>
1 parent b1953cf commit 8033578

File tree

7 files changed

+238
-14
lines changed

7 files changed

+238
-14
lines changed

‎SUMMARY.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# Table of contents
22

33
* [Welcome](README.md)
4+
* [What's new?](docs/release-notes.md)
45
* [Docs](docs/README.md)
56
* [User guides](docs/user-guides/README.md)
67
* [Get Started](docs/user-guides/j-get-started.md)

‎docs/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# Docs
22

33
## Table of contents
4+
- [What's new?](./release-notes.md)
45
- [API References](./api-reference/README.md)
56
- [User Guides](./user-guides/README.md)
67
- [Jupyter Notebook](./keplergl-jupyter/README.md)

‎docs/release-notes.md

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# What's New?
2+
3+
This page shows features that have landed to kepler.gl in major versions. For a complete list of changes to kepler.gl including each minor version, please [visit the full change log](../CHANGELOG.md).
4+
5+
## 3.1
6+
7+
_Released January 29th, 2025_
8+
9+
### Vector Tiles
10+
11+
The new [Vector Tile layer](/docs/user-guides/c-types-of-layers/vector.md) allows the map to dynamically retrieve data based on the user's viewport and zoom level. This initial release supports both Mapbox Vector Tiles and PMTiles.
12+
13+
By leveraging the efficiency of vector tiles, users can visualize complex, large-scale datasets without compromising performance, making it easier to explore and analyze geospatial data.
14+
15+
![Vector layer](https://4sq-studio-public.s3.us-west-2.amazonaws.com/statics/keplergl/images/kepler-vector.gif)
16+
17+
18+
### DuckDB Support & SQL Explorer
19+
20+
Leverage DuckDB directly within kepler.gl your geospatial projects with big data. Write and execute SQL queries to perform custom analyses, visualizing the results on your map.
21+
22+
DuckDB enables in-browser data processing, allowing you to work with large datasets without the need for external infrastructure.
23+
24+
![SQL Data Explorer](https://4sq-studio-public.s3.us-west-2.amazonaws.com/statics/keplergl/images/kepler-duck-db.png)
25+
26+
### AI Assistant
27+
28+
Kepler’s AI assistant can edit the map, including filters, base map customization, and a variety of layer configurations. Accessible via text chat, voice chat, and screenshot. The assistant can also produce SQL from natural language, which can be passed to DuckDB.
29+
30+
![AI Assistant](https://4sq-studio-public.s3.us-west-2.amazonaws.com/statics/keplergl/images/kepler-ai-assistant.png)
31+
32+
### Base Map Updates: MapLibre + Mapbox
33+
34+
Mapbox and MapLibre base maps are now simultaneously supported.
35+
36+
37+
### Color Scale Improvements
38+
39+
Custom color scale is now supported in categorial/ordinal fields, aggregate layers, and other layer components. In addition, custom breaks are now supported within the color scales.
40+
41+
42+
### Value Formatting
43+
44+
Formatting for numeric values (e.g. 10,000 can be formatted 10k, $10,000.00, etc; .42 can be formatted as 42%).
45+
46+
47+
### Animation Improvements
48+
49+
Includes various updates to the user interface for animation (for both time filters and the trip layer). You may also sync the layers (such as the trip layer) with filters, and conversely sync filters with the layer.
50+
51+
52+
### Legend Improvements
53+
54+
The legend is now both movable and resizable, supports the editing of legend values, and offers a scale for radius scaling.
55+
56+
57+
### Various Layer Improvements
58+
59+
A number of improvements to layers, including:
60+
61+
- Zoom to layer button lets users center their viewport on the layer’s data
62+
- Point layer now supports geojson
63+
- Arc layer supports creation from h3
64+
- A vast number of other layer improvements
65+
66+
This release also includes a wide range of bug fixes and performance improvements, which can be viewed in the [full change log.](../CHANGELOG.md)
67+
68+
69+
70+
71+
72+

‎docs/user-guides/README.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ This guide will teach you how to perform data analysis in Kepler.gl by adding da
3737
* [H3](./c-types-of-layers/j-h3.md)
3838
* [Trip](./c-types-of-layers/k-trip.md)
3939
* [S2](./c-types-of-layers/l-s2.md)
40+
* [Vector](./c-types-of-layers/vector.md)
4041

4142
#### [Layer attributes](./d-layer-attributes.md)
4243

@@ -59,6 +60,9 @@ This guide will teach you how to perform data analysis in Kepler.gl by adding da
5960
* [Display legend](./m-map-settings.md#display-legend)
6061
* [Split maps](./m-map-settings.md#split-maps)
6162

63+
#### [SQL Data Explorer](./sql-data-explorer.md)
64+
65+
#### [AI Assistant](./ai-assistant.md)
6266

6367
#### [Time playback](./h-playback.md)
6468

‎docs/user-guides/ai-assistant.md

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# AI Assistant
2+
3+
> Note: This feature is currently undergoing development. Stay tuned for updates!
4+
5+
The AI assistant in Kepler.gl is not only a LLM based chatbot, it is engineered to help users with creating maps and analyzing their spatial data. The AI assistant provides a new way that allows users to interact with the data and the map in a more natural and creative way.
6+
7+
![AI Assistant](https://4sq-studio-public.s3.us-west-2.amazonaws.com/statics/keplergl/images/kepler-ai-assistant.png 'AI Assistant')
8+
9+
Your conversations can be advanced: `Create a geojson layer using population with quantile color scale and update its colors inspired by Van Gogh's Starry Night`. Or: `Check the correlation between temperature and precipitation in the dataset`.
10+
11+
12+
## Supported Providers
13+
14+
The following providers and models are currently supported.
15+
16+
> Note: we are working on feature to allow users specify their own providers, models and base URL.
17+
18+
| **Provider** | **Models** |
19+
|--------------|------------------------------------------------------------------------------------------------|
20+
| **OpenAI** | `gpt-4o`, `gpt-4o-mini`, `gpt-3.5-turbo`, `gpt-3.5-turbo-0125`, `o1-mini`, `o1-preview` |
21+
| **Google** | `gemini-2.0-flash-exp`, `gemini-1.5-flash`, `gemini-1.5-pro`, `gemini-1.0-pro` |
22+
| **Ollama** (local) | `deepseek-r1`, `phi4`, `phi3.5`, `qwen2.5-coder`, `qwen2`, `qawa`, `llava`, `mistral`, `gemma2`, `llama3.3`, `llama3.2`, `llama3.1`, `llama3.1:70b` |
23+
| **DeepSeek** | `deepseek-chat`, `deepseek-reasoner` |
24+
25+
## Parameters
26+
27+
Before initating the AI assistant, the following parameters are required. A temperature and Top P are selected for you; however, you will need to provide an API key for a remote model, and a base URL for local models.
28+
29+
| **Parameter** | **Description** |
30+
|---------------|-------------------------------------------------------------------------------------------------|
31+
| **Temperature** | Controls the randomness of the model's output. Range: `0-2`, Default: `1`. Lower values make responses more focused and deterministic. |
32+
| **Top P** | Controls the diversity of the output by limiting the cumulative probability of token selection. Range: `0-1`, Default: `0.8`. |
33+
| **API Key** | Required for OpenAI (`gpt` models) and Google (`gemini` models). |
34+
| **Base URL** | Required for Ollama (`localhost:11434` or another specified base URL). |
35+
36+
## Built-in Features
37+
38+
- Take screenshot to ask [[Demo]](https://geoda.ai/img/highlight-screenshot.mp4)
39+
- Talk to ask [[Demo]](https://geoda.ai/img/highlight-ai-talk.mp4)
40+
41+
### Take a Screenshot to Ask
42+
43+
This feature enables users to capture a screenshot anywhere within kepler.gl application and ask questions about the screenshot.
44+
45+
For example, users can take a screenshot of the map (or partial of the map) and ask questions about the map e.g. *`how many counties are in this screenshot`*, or take a screenshot of the layer configuration panel and ask questions about how to use it, e.g. *`How can I adjust the opacity`*. Users can even take a screenshot of the plots in the chat panel and ask questions about the plots e.g. *`Can you give me a summary of the plot?`*.
46+
47+
![Screenshot to ask](https://4sq-studio-public.s3.us-west-2.amazonaws.com/statics/keplergl/images/kepler-ai-assistant-screenshot.png 'Screenshot to ask')
48+
49+
#### How to use this feature?
50+
51+
1. Click the "Screenshot to Ask" button in the chat interface
52+
2. A semi-transparent overlay will appear
53+
3. Click and drag to select the area you want to capture
54+
4. Release to complete the capture
55+
5. The screenshot will be displayed in the chat interface
56+
6. You can click the x button on the top right corner of the screenshot to delete the screenshot
57+
58+
### Talk to Ask
59+
60+
This feature enables users to "talk" to the AI assistant. After clicking the "Talk to Ask" button, users can start talking using microphone. When clicking the same button again, the AI assistant will stop listening and send the transcript to the input box.
61+
62+
When using the voice-to-text feature for the first time, users will be prompted to grant microphone access. The browser will display a permission dialog that looks like this:
63+
64+
![Talk to ask](https://4sq-studio-public.s3.us-west-2.amazonaws.com/statics/keplergl/images/kepler-ai-assistant-talk-to-ask.png 'Talk to ask')
65+
66+
After granting access, users can start talking to the AI assistant.
67+
68+
> Note: for OpenAI, the whisper model is used to transcribe the audio. Google's gemini models are multimodal models, so the audio-to-text feature is supported by default.
69+
70+
## Map and Data Analysis Assistant
71+
72+
Using LLM function tools, kepler.gl's AI assistant can help transform users's prompt into actions that executed inside kepler.gl. This allows users to interact with kepler.gl in a more natural and creative way.
73+
74+
### Why use LLM function tools?
75+
76+
Function calling enables the AI Assistant to perform specialized tasks that LLMs cannot handle directly, such as complex calculations, data analysis, visualization generation, and integration with external services. This allows the assistant to execute specific operations within kepler.gl while maintaining natural language interaction with users.
77+
78+
### Is my data secure?
79+
80+
Yes, the data you used in kepler.gl stays within the browser, and will **never** be sent to the LLM. Using function tools, we can engineer the AI assistant to use only the meta data for function calling, e.g. the name of the dataset, the name of the layer, the name of the variables, etc. Here is a process diagram to show how the AI assistant works:
81+
82+
![AI Assistant Diagram](https://4sq-studio-public.s3.us-west-2.amazonaws.com/statics/keplergl/images/kepler-ai-assistant-diagram.png 'AI Assistant Diagram')
83+
84+
### Actions available to use
85+
86+
The current supported actions are:
87+
88+
- System:
89+
- Show dataset/layer/variable info.
90+
- Load data from url.
91+
- Change the basemap style.
92+
- Mapping and Data Analysis:
93+
- Create map layer from variable.
94+
- Query the data using SQL (coming soon)
95+
- Classify the data of a variable.
96+
- Quantile / Natural (Jenks) Breaks / Percentile / Box / Standard Deviation
97+
- Plots
98+
- Create histogram.
99+
- Create scatter plot with regression line.
100+
- Spatial Analysis:
101+
- Spatial join two datasets (e.g. count points and polygons).
102+
103+
> Note: to see our plan to add more actions to the AI assistant, please check out this [Kepler.gl RFC]([https://github.com/kepler-gl/kepler.gl/issues/4689](https://github.com/keplergl/kepler.gl/discussions/2843)) and the [integration of GeoDa with Kepler.gl]([text](https://github.com/GeoDaCenter/openassistant/wiki/Integration-Kepler.gl---GeoDaLib))
104+
105+
Users can simply describe what they want to accomplish in plain text, and the AI Assistant will invoke the appropriate function with the correct parameters that your application can execute. The LLM will identify if the question can be answered by using one or multiple function tools, and the LLM will ask the user to confirm the parameters of each function call.
106+
107+
> *Can you classify the data of the variable "population" using natural breaks and create a geojson layer using the breaks with colors inspired by Van Gogh's Starry Night.*
108+
109+
#### Plots
110+
111+
The plots created by the AI assistant are interactive, and can be used to explore the data.
112+
113+
In each plot, there is a small toolbar on the top right corner, which contains three buttons:
114+
115+
- **Box Select**: Select the data in the plot.
116+
- **Keep Selection**: Keep the selected data in the plot.
117+
- **Clear Selection**: Clear the selected data in the plot.
118+
119+
One can click the **Box Select** button first. Then, start selecting the data in the plot by left clicking the mouse and dragging the mouse to select the data. The selected data will be highlighted in the plot and also be highlighted in the map.
120+
121+
##### Scatter Plot
122+
123+
For scatter plot, the AI assistant will create a scatter plot with a regression line by default. If users select points in the plot, there will be 3 different regression lines created: one for all points, one for the selected points, and one for the unselected points.
124+
125+
If users click the 'expand' button on the top right corner of the plot, the plot will be expanded to a floating modal dialog with more details of the regressions shown in a tablt.
126+
127+
The regression details include:
128+
129+
- R-squared
130+
- Slope
131+
- Intercept
132+
- P-value
133+
- Standard Error
134+
- Chow test for selected and unselected regression lines
135+
136+
This scatter plot can help users to explore the relationship between two variables, and explore the heterogeneity of the data by selecting different points.
137+
138+
![Scatterplot](https://4sq-studio-public.s3.us-west-2.amazonaws.com/statics/keplergl/images/kepler-ai-assistant-scatterplot.png 'Scatterplot')
139+

‎docs/user-guides/c-types-of-layers/vector.md

Lines changed: 1 addition & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,7 @@
33

44
Vector layers use the three basic GIS features – lines, points, and polygons – to represent real-world features in digital format.
55

6-
7-
{% embed url="https://4sq-studio-public.s3.us-west-2.amazonaws.com/statics/keplergl/images/kepler-gl-vector-tiles-fsq.mp4" %}
8-
6+
![Vector layer](https://4sq-studio-public.s3.us-west-2.amazonaws.com/statics/keplergl/images/kepler-vector.gif 'Vector layer')
97

108
# Settings
119

@@ -66,16 +64,5 @@ Height settings for the Vector layer. Height is best viewed with the 3D viewing
6664
| Fixed Height | Applies height without additional modifications. |
6765

6866

69-
<!-- Remove after testing -->
70-
71-
## Video Alternative
72-
73-
<video controls autoplay loop>
74-
<source src="https://4sq-studio-public.s3.us-west-2.amazonaws.com/statics/keplergl/images/kepler-gl-vector-tiles-fsq.mp4" type="video/mp4">
75-
Your browser does not support the video tag.
76-
</video>
77-
78-
79-
8067

8168
[Back to table of contents](../README.md)

‎docs/user-guides/sql-data-explorer.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# SQL/DuckDB Data Explorer
2+
3+
> Note: This feature is currently undergoing development. Stay tuned for updates!
4+
5+
The new SQL data explorer provides a DucKDB instance where you can use SQL to transform and add data to the map.
6+
7+
![SQL Data Explorer](https://4sq-studio-public.s3.us-west-2.amazonaws.com/statics/keplergl/images/kepler-duck-db.png 'SQL Data Explorer')
8+
9+
You will need local data (i.e. data upload for your machine) or data accessible via a remote URL.
10+
11+
Any dataset already added to kepler can be accessed via SQL editor by selecting it via its name in kepler. For instance, if your dataset is named `world-cities.csv`, you can select the entire dataset by writing `SELECT * FROM 'world-cities.csv'`.
12+
13+
The data does not need to be pre-loaded to kepler -- you may also select data remotely via SQL. The following example loads earthquake data from our sample data repository:
14+
15+
```
16+
SELECT * FROM 'https://raw.githubusercontent.com/keplergl/kepler.gl-data/refs/heads/master/earthquakes/data.csv'
17+
```
18+
19+
20+
Once you have a data selection you are satisfied with, click **Add to Map**. Your new dataset will be added to kepler. If you have a column that contains recognizable geography data, (i.e. lat/lng columns or polygon geometries), layers will automatically be created.

0 commit comments

Comments
 (0)