pydeck

0.9.1 · active · verified Sun Mar 29

pydeck is a Python binding for deck.gl, a WebGL-powered framework for large-scale interactive data visualization. It is optimized for Jupyter environments, enabling users to create powerful geospatial visualizations with a declarative Python API, largely obviating the need for extensive JavaScript knowledge. The current stable version is 0.9.1, which aligns with deck.gl v9.0, and new releases generally follow the major version updates of the underlying deck.gl library.

Warnings

breaking As of pydeck v0.9+, certain advanced Jupyter-specific features, such as binary data transportation, interactive data selection, and real-time data updates, are not currently supported. While `pydeck` still works in Jupyter, users relying on these interactive capabilities may experience a regression or need to adjust their workflows.
Fix: Review documentation for alternatives or consider rendering static HTML outputs for complex interactive scenarios. For basic interactivity (hover, click events), these are still supported, but might not be as deeply integrated as in previous versions.
gotcha pydeck does not always raise Python errors for incorrect or omitted layer arguments. If a visualization fails to render or behaves unexpectedly, users should typically inspect the browser's developer console for JavaScript errors, as `pydeck` translates Python objects to JavaScript for rendering.
Fix: Always check the browser's JavaScript console for errors when encountering rendering issues. Refer to the official deck.gl layer catalog for detailed argument specifications, and pydeck examples for Pythonic translations.
gotcha Dataframe column names used in `get_` accessors (e.g., `get_position`, `get_fill_color`) should ideally be sanitized to avoid hyphens or whitespace. The underlying JavaScript expression parser may interpret these as arithmetic operations (e.g., `datum.lng - datum.new` instead of `datum['lng-new']`), leading to rendering failures.
Fix: Rename dataframe columns to use snake_case or remove special characters before passing them to pydeck layers, for example, `df.columns = df.columns.str.replace('[^A-Za-z0-9_]+', '', regex=True)`.
gotcha If data values in a DataFrame column are integers and are used by `get_` accessors that expect floating-point numbers (e.g., for coordinates or elevations), it might lead to unexpected behavior or rendering issues.
Fix: Explicitly convert integer columns to float types (e.g., `df['column_name'] = df['column_name'].astype(float)`) if they are intended for graphical properties that might require floating-point precision.
gotcha While pydeck defaults to Carto basemaps, if you intend to use Mapbox or Google Maps, you will need to provide an API key. These keys can be passed directly to the `Deck` object or set as environment variables (`MAPBOX_API_KEY`, `GOOGLE_MAPS_API_KEY`).
Fix: Set `MAPBOX_API_KEY` or `GOOGLE_MAPS_API_KEY` as environment variables or pass them via the `api_keys` parameter in the `pydeck.Deck` constructor (e.g., `api_keys={'mapbox': 'YOUR_KEY'}`).

Install

pip install pydeck Basic Installation
pip install pydeck jupyter nbextension install --sys-prefix --symlink --overwrite --py pydeck jupyter nbextension enable --sys-prefix --py pydeck For Jupyter Notebook (post-install)

Imports

Deck
```
from pydeck import Deck
```
Layer
```
from pydeck import Layer
```
ViewState
```
from pydeck import ViewState
```
pdk
```
import pydeck as pdk
```
Commonly aliased as `pdk` for brevity and convention.

Quickstart

This quickstart demonstrates how to create a basic 3D heatmap using pydeck's HexagonLayer. It fetches data from a URL, defines a layer with visualization properties, sets an initial camera view, and then renders the map. The map can be displayed directly in a Jupyter environment or exported to a standalone HTML file. An optional Mapbox API key is included for base map rendering.

import pydeck as pdk
import pandas as pd
import os

# Sample data (e.g., 2014 locations of car accidents in the UK)
UK_ACCIDENTS_DATA = (
    'https://raw.githubusercontent.com/uber-common/'
    'deck.gl-data/master/examples/3d-heatmap/heatmap-data.csv'
)

# Define a layer to display on a map
layer = pdk.Layer(
    'HexagonLayer',
    data=UK_ACCIDENTS_DATA,
    get_position=['lng', 'lat'],
    auto_highlight=True,
    elevation_scale=50,
    pickable=True,
    elevation_range=[0, 3000],
    extruded=True,
    coverage=1
)

# Set the viewport location
view_state = pdk.ViewState(
    longitude=-1.415,
    latitude=52.2323,
    zoom=6,
    min_zoom=5,
    max_zoom=15,
    pitch=40.5,
    bearing=-27.36
)

# Render the map
r = pdk.Deck(
    layers=[layer],
    initial_view_state=view_state,
    api_keys={'mapbox': os.environ.get('MAPBOX_API_KEY', '')} # Or Google Maps API key
)

# To display in a Jupyter environment, use r.show().
# To save to an HTML file:
r.to_html('pydeck_quickstart.html')

view raw JSON →