ppessi / mapboxgl-jupyter

Use Mapbox GL JS to visualize data in a Python Jupyter notebook

Location Data Visualization library for Jupyter Notebooks

Create Mapbox GL JS data visualizations natively in Jupyter Notebooks with Python and Pandas. mapboxgl is a high-performance, interactive, WebGL-based data visualization tool that drops directly into Jupyter. mapboxgl is similar to Folium built on top of the raster Leaflet map library, but with much higher performance for large data sets using WebGL and Mapbox Vector Tiles.

Try out the interactive map example notebooks from the /examples directory in this repository

1. Categorical points
2. All visualization types
3. USGS Earthquakes

Installation

pip install mapboxgl

Documentation

Checkout the documentation for mapboxgl visuals and mapboxgl utilities.

Usage

The examples/ directory contains sample Jupyter notebooks demonstrating usage.

import pandas as pd
import os
from mapboxgl.utils import *
from mapboxgl.viz import *

# Load data from sample csv
data_url = 'https://raw.githubusercontent.com/mapbox/mapboxgl-jupyter/master/examples/points.csv'
df = pd.read_csv(data_url)

# Must be a public token, starting with `pk`
token = os.getenv('MAPBOX_ACCESS_TOKEN')

# Create a geojson file export from a Pandas dataframe
df_to_geojson(df, filename='points.geojson',
              properties=['Avg Medicare Payments', 'Avg Covered Charges', 'date'],
              lat='lat', lon='lon', precision=3)

# Generate data breaks and color stops from colorBrewer
color_breaks = [0,10,100,1000,10000]
color_stops = create_color_stops(color_breaks, colors='YlGnBu')

# Create the viz from the dataframe
viz = CircleViz('points.geojson',
                access_token=token,
                height='400px',
                color_property = "Avg Medicare Payments",
                color_stops = color_stops,
                center = (-95, 40),
                zoom = 3,
                below_layer = 'waterway-label'
              )
viz.show()

Development

Install the python library locally with pip:

pip install -e .

To run tests use pytest:

pip install pytest pytest

To run the Jupyter examples,

1. cd examples
2. pip install jupyter
3. jupyter notebook

Release process

• After merging all relevant PRs for the upcoming release, pull the master branch
  • git checkout master
  • git pull
• Update the version number in mapboxgl/__init__.py and push directly to master.
• Tag the release
  • git tag <version>
  • git push --tags
• Setup for pypi (one time only)
  • You'll need to pip install twine and set up your credentials in a ~/.pypirc file.
• Create the release files
  • rm dist/* # clean out old releases if they exist
  • python setup.py sdist bdist_wheel
• Upload the release files
  • twine upload dist/mapboxgl-*