search

mapbox / mapboxgl-jupyter

Use Mapbox GL JS to visualize data in a Python Jupyter notebook
MIT License
666 stars 137 forks source link

readme

========================================================= Location Data Visualization library for Jupyter Notebooks

.. image:: https://travis-ci.org/mapbox/mapboxgl-jupyter.svg?branch=master :target: https://travis-ci.org/mapbox/mapboxgl-jupyter :alt: Build Status

.. image:: https://coveralls.io/repos/github/mapbox/mapboxgl-jupyter/badge.svg?branch=master :target: https://coveralls.io/github/mapbox/mapboxgl-jupyter?branch=master :alt: Coverage Status

.. image:: https://badge.fury.io/py/mapboxgl.svg :target: https://badge.fury.io/py/mapboxgl :alt: PyPI version

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

Create Mapbox GL JS <https://www.mapbox.com/mapbox-gl-js/api/> 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 <https://github.com/python-visualization/folium> built on top of the raster Leaflet <http://leafletjs.com/>__ map library, but with much higher performance for large data sets using WebGL and Mapbox Vector Tiles.

.. image:: https://cl.ly/3a0K2m1o2j1A/download/Image%202018-02-22%20at%207.16.58%20PM.png

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

  1. Categorical points <https://nbviewer.jupyter.org/github/mapbox/mapboxgl-jupyter/blob/master/examples/notebooks/point-viz-categorical-example.ipynb>__
  2. All visualization types <https://nbviewer.jupyter.org/github/mapbox/mapboxgl-jupyter/blob/master/examples/notebooks/point-viz-types-example.ipynb>__
  3. Choropleth Visualization types <https://nbviewer.jupyter.org/github/mapbox/mapboxgl-jupyter/blob/master/examples/notebooks/choropleth-viz-example.ipynb>__
  4. Image Visualization types <https://nbviewer.jupyter.org/github/mapbox/mapboxgl-jupyter/blob/master/examples/notebooks/image-vis-type-example.ipynb>__
  5. Raster Tile Visualization types <https://nbviewer.jupyter.org/github/mapbox/mapboxgl-jupyter/blob/master/examples/notebooks/rastertile-viz-type-example.ipynb>__

Installation

.. code-block:: bash

$ 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.

.. code-block:: python

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:

.. code-block:: console

$ pip install -e .

To run tests use pytest:

.. code-block:: console

$ pip install mock pytest $ python -m pytest

To run the Jupyter examples,

.. code-block:: console

$ cd examples $ pip install jupyter $ jupyter notebook

We follow the PEP8 style guide for Python <http://www.python.org/dev/peps/pep-0008/>__ for all Python code.

Release process