Like many DH teachers, I have had to look for an alternative to Carto to introduce students to digital mapping now that they have fully gated their platform. What I need is something off the shelf that offers a range of map types, not just point maps, to allow some consideration of the variety of spatial visualizations. My current syllabus doesn’t allow time to teach students to make maps programmatically, but I’m beginning to think it may ultimately be necessary to make that shift. There are already several good mapping tutorials available, although they focus on a single map type. But for the moment I still think there is some value in highlighting off-the-shelf tools as an entry point, and as a short-cut to make it possible to cover a wider range of material in an introductory course.

This semester I’m going to use kepler.gl, a new open-source web app from Uber with a publicly available demo version. It offers the ability to easily make a variety of map types that I need, but it falls short of Carto in a number of ways. Most notably, it is a client-side app, meaning that users cannot embed interactive maps they create, only export images and data (as is the case with Palladio). kepler.gl also offers less functionality for customizing or styling maps, and requires extra steps to create category maps. At the same time, it offers an ability to link points with arcs and lines that offers some potential for network mapping.

Below I’m sharing the tutorial I wrote for my course. It uses a small dataset (which the course reuses across several tools to facilitate comparisons), so doesn’t show off kepler.gl’s functionality with larger datasets.

kepler.gl Tutorial

Kepler.gl is an open source tool developed by Uber. This tutorial uses the online demo version, which runs in your browser. You can export an image of maps you create in the demo or the data; since the app does not store any data or maps, you cannot embed an interactive map created in the demo in your website.

Note: I recommend you use Safari for this activity. In my testing, the Export function works best in Safari; it also works in Chrome, but requires some adjustment of settings (described below). I have not been able to get Export to work in Firefox. No one should be using Internet Explorer!

Getting Started

You will be using the a small dataset from the Library of Congress’ WPA Slave Narrative Collection.

Click these links to download the data and look at the different columns and categories of data in each dataset:

• http://drstephenrobertson.com/SlaveNarratives/Alabama_Interviews_CartoDB.csv
• http://drstephenrobertson.com/SlaveNarratives/Alabama_Combined.csv

How did we create this data?
We extracted it from the Project Gutenberg text files of the interviews. In the case of some volumes, such as Alabama, we had to consult the original documents for data not included in the transcriptions, such as the date of the interviews.
The latitude/longitude information for the locations [georeferencing] was obtained by entering them in this free georeferencing site: http://www.mapcoordinates.net/en.
For historical locations that did not return results, approximate locations were obtained from sources found by Google searches for the location.

To upload datasets

• Visit kepler.gl. Click on “GET STARTED” to open the demo version
• Find the Interviews file you downloaded and drag and drop it into the upload box: http://drstephenrobertson.com/SlaveNarratives/Alabama_Interviews_CartoDB.csv
  • Things to Note: Kepler.gl is able to make a map of this data because it included columns labeled latitude and longitude containing spatial data

Point Map

Things to Note: Multiple records/rows of data with the same location / latitude & longitude can’t be distinguished on a points map in Kepler.gl – they appear directly on top of each other, and only the top record will display

• Click on Point to rename the layer – replace Point with Interviews
• Click on the V on the right of the layer name to open the Layer Settings
• Adjust the color of the points by clicking on the box under color, which opens a color spectrum
• Adjust the size of the points using the slider under Radius – I suggest you make the dots a little larger
  • Things to Note: both color and radius can be set to reflect a range of values, but we do not have quantitative information in this dataset so we can’t use these options

Tool Tip

• You can adjust which information appear in pop-ups – roll your mouse over the points on the map to see the pop-ups
  • Things to Note: If you click directly on a point, it changes color and a pin appears in the pop-up to indicate that it is fixed and will remain visible even when you move your mouse away. To unfix the pop-up, click on the pin.
• Click on Interactions – the third icon under kepler.gl
  • Things to Note – you can slide the white square next to the ToolTip to turn off pop-ups on the map
• The information which appears in the pop-up is the columns from the spreadsheet that are in the box underneath the name of the spreadsheet you uploaded
• The data includes both ‘State Where Interviewed’ & ‘Where Interviewed’ – delete State Where Interviewed by clicking on the X next to the Column title
• Click in the box containing the columns to add another to the pop-up – add Place of Birth

Base map

• Click on Base Map – the fourth icon under kepler.gl
• Click on the box under Map Style to see the Map Options
• Kepler.gl offers 4 base map options – two degrees of dark, two of light. Choose the option you prefer (I find both dark options obscure information I need to make sense of the map)
  • Things to Note: You cannot add a custom (historical) basemap to Kepler.gl
• Map Layers can be toggled on and off
• Click on the eye icons to turn on Borders & Turn off Roads

Export

• Click on the export icon to the right of the kepler.gl icon
• There are 3 download options – image, data, and config
  • Things to Note: Downloading the Config with the Export Current Map file option checked creates a file you can upload to edit or continue working on a map
• BUG WARNING – I can only get the image download to work in Chrome by both emptying the Cache and checking Disable Cache in the Developer tools (that fix does not work for Firefox) – export works fine in Safari
• Click Export Image
• Select one of the three Ratio options for the size of the image
• Select a resolution for the image
• You can add the legend to the map, but in this case there is no needs as there is only one kind of data point
  • Things to note: You cannot give the map a title

Cluster Map

• In the Layers menu, click on the Interviews Data, and then on the Layer Type box, showing Point, to open the options
• Click on Cluster
  • Things to Note: Zooming the map in and out changes the clusters
• You can adjust the number of points in each cluster using the Cluster SIze slider (under Radius)
• You can adjust the size of the circles representing each cluster with the Radius Range slider (under Radius)

Heat Map

• In the Layers menu, click Add a Layer
  • Why are we doing this: we are creating the Heat Map in a separate layer so we can use the dual map view to compare Cluster Maps and Heat Maps
• Click on the Layer Type box and select Heatmap
• Click on the Lat box and select Latitude from the pull down menu
• Click on the Long box and select Longitude from the pull down menu
• The Cluster and Heatmaps are now on the same map. This overlapped view makes some comparison of the two map types; another way to compare them is to use the dual map
  • Click on dual map view (the top button on the right top of the window) – the screen will now split to display two maps
  • Click on the Layer Panel that appears under the dual map view to open a window that allows you to select which layers display on which map
  • On the left map, click on the switch next to Interviews to turn off the Cluster layer
  • On the right map, click on the switch next to new layer to turn off the Heat Map layer
  • BUG WARNING: In testing in Chrome, the right map did not display the Heatmap layer
• Return to the Layer menu in the left hand panel
• Under Radius, the slider adjusts the size of each grouping of points in the heatmap
• Note: the Dual map view does not export, so if you export the map in dual view the image is of the two overlapping map types. To export just one map type, close the dual view of the map you do not want to export

Compare the Cluster & Heat maps. Which map best represents the density of points? What do they tell you about the interviews? What do they tell you in comparison with the simple point map?

Time Map

• Delete the new layer you added for the Heatmap and change the Layer Type on Interviews to Point
• Click on Filter – the second icon under kepler.gl
• Click on Add Filter, then in the box that appears to select which column of data to filter
  • Note a filter applies to ALL layers from a dataset, so you cannot filter a single dataset to display different categories of information
• Click on time When Interview – a timeline will appear at the bottom of the map
  • Note: the bar graph displays the number of points at each time – kepler.gl calculates the span automatically

• To adjust what span of time appears on map, grab the white box on the right end of the timeline and drag it left to adjust the span of results that appear on the map
• The dates & times in the center top of the timeline are those that are on the map
• The results that appear on the map are indicated in blue on the timeline; those that do not appear are indicated in gray. You will also see the points disappear from the map
• When you press the play button the line moves across the timeline, revealing what appears within it and hiding what is outside it
• To adjust how fast the timeline plays, click on the options on the top right of the timeline
• To remove and add the timeline filter to the map display, click on the clock icon in the Filters menu on the
• left
• Note: An exported image of the map does not include the time filter

Evaluate the map. What does it tell you about the interviews? What does it tell you in comparison with the simple point map?

Category Map

As the filter applies to all layers in a dataset, to map different categories of data in the same dataset you have to upload the same data multiple times and filter each upload for a different category

• In the Layers menu on the left, click Add Data, and upload another copy of the Interviews spreadsheet
  • Note: each datasheet is assigned a color; each layer using that dataset is identified by the same color
• Rename the Interview layer from the original dataset to House
• Click on the new Point layer and rename it Field
• Click on Filter, Add Filter
• Select the Original (purple) dataset as the Data Source
• Click on Select a field and choose type of slave
• Click in Values and select House
• Click Add Filter
• Select the second (brown) dataset as the Data Source
• Click in Values and select Field

Evaluate the map. What do the category maps tell you about the interviews? What do they tell you in comparison with the point map, the animated map, and the heatmap?

Network map

• Delete the two datasets used in the last map and and upload Alabama_Combined.csv
• Open the Layer Settings, click on the Layer type, and select Arc
• Click on Lat0 and scroll down to Latitude-0 (after State Where Interviewed)
• Click on Lng0 and scroll down to Longitude-0 (after State Where Interviewed)
• Click on Lat1 and scroll down to Latitude (after Where Enslaved)
• Click on Lng1 and scroll down to Longitude (after Where Enslaved)
• Click on the Target Color and change it to a contrasting color – if you look carefully you will see that the arc line is one color at its source (where the interview took place) and the target color at the other end (where the interview subject was enslaved)
• Click on the 3D Map icon on the top right of the map to better display the Arc
  • OPTIONAL: Adding point layers can make this map easier to read:
  • Click Add Layer, Select Layer type point, and select Latitude & Longitude to add points for where the interview subjects were enslaved
  • Click Add Layer, Select Layer type point, and select Latitude & Longitude to add points for where the interview subjects were enslaved
• Kepler also links points with lines not arcs – Click on your first layer, and change the layer type from Arc to Line (and Disable the 3D map)

Compare and Evaluate the maps. Which map best represents the relationship between interview location and the location(s) in which the interview subject was enslaved? What do the maps tell you about the interviews? What do they tell you in comparison with the simple point map?