In [1]:
%matplotlib inline
import numpy as np
import matplotlib.pyplot as plt
import random

import pysal as ps
from pysal.contrib.viz import mapping as maps

Guide for the mapping module in PySAL


This document describes the main structure, components and usage of the mapping module in PySAL. The is organized around three main layers:

  • A lower-level layer that reads polygon, line and point shapefiles and returns a Matplotlib collection.
  • A medium-level layer that performs some usual transformations on a Matplotlib object (e.g. color code polygons according to a vector of values).
  • A higher-level layer intended for end-users for particularly useful cases and style preferences pre-defined (e.g. Create a choropleth).

Lower-level component

This includes basic functionality to read spatial data from a file (currently only shapefiles supported) and produce rudimentary Matplotlib objects. The main methods are:

  • map_poly_shape: to read in polygon shapefiles
  • map_line_shape: to read in line shapefiles
  • map_point_shape: to read in point shapefiles

These methods all support an option to subset the observations to be plotted (very useful when missing values are present). They can also be overlaid and combined by using the setup_ax function. the resulting object is very basic but also very flexible so, for minds used to matplotlib this should be good news as it allows to modify pretty much any property and attribute.


In [5]:
shp_link = ps.examples.get_path('columbus.shp')
shp =
some = [bool(random.getrandbits(1)) for i in]

fig = plt.figure()

base = maps.map_poly_shp(shp)
some = maps.map_poly_shp(shp, which=some)
cents = np.array([poly.centroid for poly in])
pts = plt.scatter(cents[:, 0], cents[:, 1])

ax = maps.setup_ax([base, some, pts], [shp.bbox, shp.bbox, shp.bbox])
/Users/steffie/anaconda3/envs/py27/lib/python2.7/site-packages/matplotlib/cbook/ MatplotlibDeprecationWarning: Adding an axes using the same arguments as a previous axes currently reuses the earlier instance.  In a future version, a new instance will always be created and returned.  Meanwhile, this warning can be suppressed, and the future behavior ensured, by passing a unique label to each axes instance.
  warnings.warn(message, mplDeprecation, stacklevel=1)

Medium-level component

This layer comprises functions that perform usual transformations on matplotlib objects, such as color coding objects (points, polygons, etc.) according to a series of values. This includes the following methods:

  • base_choropleth_classless
  • base_choropleth_unique


In [7]:
net_link = ps.examples.get_path('eberly_net.shp')
net =
values = np.array('.shp', '.dbf')).by_col('TNODE'))

pts_link = ps.examples.get_path('eberly_net_pts_onnetwork.shp')
pts =

fig = plt.figure()

netm = maps.map_line_shp(net)
netc = maps.base_choropleth_unique(netm, values)

ptsm = maps.map_point_shp(pts)
ptsm = maps.base_choropleth_classif(ptsm, values)

ax = maps.setup_ax([netc, ptsm], [net.bbox, net.bbox])
  • base_choropleth_classif

Higher-level component

This currently includes the following end-user functions:

  • plot_poly_lines: very quick shapefile plotting.
In [8]:
  • plot_choropleth: for quick plotting of several types of choropleths.
In [9]:
shp_link = ps.examples.get_path('columbus.shp')
values = np.array('columbus.dbf')).by_col('HOVAL'))

types = ['classless', 'unique_values', 'quantiles', 'equal_interval', 'fisher_jenks']
for typ in types:
    maps.plot_choropleth(shp_link, values, typ, title=typ)

To-Do list

General concepts and specific ideas to implement over time, with enough description so they can be brought to life.

  • Support for points in medium and higher layer
  • LISA cluster maps

Caution note on plotting points

Support for points (dots) is still not quite polished. Ideally, one would like to create a PathCollection from scratch so it is analogue to the creation of a PolyCollection or LineCollection. However, for the time being, we are relying on the wrapper plt.scatter, which makes it harder to extract the collection and plug it in a different figure. For that reason, it is recommended that, for the time being, one creates the line and/or polygon map as shown in this notebook and then grabs the output axis and uses ax.scatter to overlay the points.

NOTE: the PathCollection created by plt.scatter is detailed on line 3142 of Maybe we can take some inspiration from there to create our own PathCollection for points so they live at the same level as polygons.