seolhalee / mapboxgl-jupyter

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

Location Data Visualization library for Jupyter Notebooks

Library documentation at https://mapbox-mapboxgl-jupyter.readthedocs-hosted.com/en/latest/.

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. Choropleth Visualization types
4. Image Visualization types
5. Raster Tile Visualization types

Installation

$ pip install mapboxgl

Documentation

Documentation is on Read The Docs at https://mapbox-mapboxgl-jupyter.readthedocs-hosted.com/en/latest/.

Usage

The examples directory contains sample Jupyter notebooks demonstrating usage.

import os

import pandas as pd

from mapboxgl.utils import create_color_stops, df_to_geojson
from mapboxgl.viz import CircleViz


# Load data from sample csv
data_url = 'https://raw.githubusercontent.com/mapbox/mapboxgl-jupyter/master/examples/data/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 mock pytest
$ python -m pytest

To run the Jupyter examples,

$ cd examples
$ pip install jupyter
$ jupyter notebook

We follow the PEP8 style guide for Python for all Python code.

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-*