gmplot in Jupyter: installation guide and package exploration

A couple of weeks ago I decided to analyse the GPS data of my latest running effort. I downloaded the GPS Exchange Format (GPX) file of my latest run from a running app named Strava, and started playing around with the data in Jupyter Notebook. Everything worked out nicely until I wanted to plot my route on Google Maps.

There are two general approaches to plotting graphics over Google Maps. The first, and probably most stable solution, is using the Google Maps API together with its Python library. While there is nothing wrong with this approach, it is relatively complicated and time-consuming for an one-off use case.

The second option is to use a ready-made Python package, and this is where gmplot comes into play. The idea is to download the package, pass your data as arguments into the functions and let the package create a neat html file for you. Sounds good? Let’s install gmplot!

If you only want to read how to properly install gmplot, scroll down to setup.py

conda install

The easiest way to install a Python package, if you’re running the Anaconda distribution, is installing the module using the Anaconda Prompt. Installing a package is usually as easy as opening a new prompt, look up the install command on Anaconda Cloud and execute the command. In gmplot its case I found:

conda install -c mlgill gmplot

Unfortunately, this return us a PackagesNotFoundError. A quick Google search doesn’t give us any thorough solutions, but points us into the direction of a pip install in the Anaconda Prompt. (pip is a package management system used to install and manage software packages in Python.)

Digging a little deeper into the error, it becomes clear that the problem is related to the OS. The package is only supported in OSX. We can verify this by searching the meta-information of gmplot.

anaconda search -t conda gmplot

pip install

First check if you have pip installed with conda list pip. If this returns you a pip version (e.g. 18.0), you can proceed with:

pip install gmplot

Unfortunately, luck is once again not on our side and we get the following bulky error message. Another query in our favorite search engine teaches us we can install packages by executing setup.py, a file provided by the author of the package.

setup.py

If you want to use this way of installing a package, it is required to download all the files in the package to your machine manually. You can go to gmplot its Github repository and downloads the package; or easier, just clone the repo using git (this requires you to have git installed):

git clone https://github.com/vgm64/gmplot

Then navigate to the folder where setup.py is located and:

python setup.py install

gmplot should be installed as a Python package in your distribution. Test this by opening a new Jupyter Notebook and make sure the import gmplot statement does not return any errors.

This way of installing gmplot seems the most solid one and the only one working on all operating systems.

Testing gmplot

Now lets try to draw the map of my run with gmplot. We will use actual gps data from Strava which I have saved in a pandas dataframe with four columns: longitude, latitude, altitude and time.

Only the first two columns are important to us, since we want to draw a 2d map. Let’s load the data in our Jupyter Notebook. (You can find the testdata here)

data = pd.read_csv('llatest.csv')

Before feeding the gps data to gmplot, you have to create a new GoogleMapPlotter object and pass the longitude and latitude of the center of your map and the desired zoom level as arguments.

If you want your data nicely spread over your map, it makes sense to pick the middle between the maximum longitude and minimum longitude and the middle between the maximum latitude and minimum latitude.

min_lat, max_lat, min_lon, max_lon = \
min(data['lat']), max(data['lat']), \
min(data['lon']), max(data['lon'])
## Create empty map with zoom level 16
mymap = gmplot.GoogleMapPlotter(
    min_lat + (max_lat - min_lat) / 2, 
    min_lon + (max_lon - min_lon) / 2, 
    16)

To plot the data as a continuous line (or a polygon), we can use the plot method. It has two self-explanatory optional arguments: color and edge width.

mymap.plot(data['lat'], data['lon'], 'blue', edge_width=1)

To create the actual html map, you invoke the draw method on the manipulated GoogleMapPlotter object and give the name as only argument. (Don’t forget to add the .html extension to your plot name.)

mymap.draw('my_gm_plot.html')

Open the html file and admire your work.

import os
os.system('my_gm_plot.html')

Although this plot function is by far the most interesting one, gmplot offers three more methods to draw on top of Google Maps. All of them follow the same workflow as our example above.

Scatter draws all the points fed into the function on the map. Optional arguments are the colour, the size and if a marker should be used.

mymap.scatter([data.iloc[50]['lat']], [data.iloc[50]['lon']], 
              'red', size=10, marker=False)

Marker draws a single marker on the canvas. Unfortunately, this functionality does not seem to work in Windows environments. This issue is known by the author of the package. More information about this issue can be found here.

Circle draws a circle with a radius (argument) around two longitude and latitude coordinates. Note that this is basically method is basically the same as scatter, except the size parameter is replaced radius. It would be a nice addition to the package if the transparency of the circle could be set.

mymap.circle([data.iloc[0]['lat']], [data.iloc[0]['lon']], 
             radius=500, color='yellow')

Heatmap creates a heatmap based on data points and some settings such as radius and treshhold. For a complete understanding of the arguments, take a look at the source code.

— Please feel free to bring any inconsistencies or mistakes to my attention in the comments or by leaving a private note. —