Why make maps with code?

All of the maps that we have created so far in this workshop have been created using graphical user interfaces (GUIs). However, there is an entirely different way to create maps using computer programming languages. Consider the example code below. These five lines of code create the map below of a encounters between American and French vessels during the Quasi War.1 For now, don’t get hung up on the details of the code.

quasi <- read.csv("data/quasi-wars.csv")
leaflet(quasi) %>% 
  addTiles() %>% 
  addCircles(popup = ~engagement_type)

There is a significant difference between the way we created this map and the way that we created maps using GUIs. In the GUIs, we had to point and click, and it is difficult to explain what we did and to reproduce or repeat it. Yet by making this map with code, we can in principle inspect and explain every step along the way, even if the language takes some getting used to. For example, we can read this code and observe that the line addTiles() adds the Open Street Map tiles to the map, and we can surmise that if we left that line out we would not get any tiles, and if we added some more information to the function that we could get different tiles. Or, we can observe that the addCircles() function adds small blue circles to the map, and we can surmise that we could use that function to add large red circles, or even that changing the function to something different might give us a different kind of marker altogether. The principle is that computer code lets us specify exactly what we want.2

Using computer code also opens the possibility that we can manipulate our data in much more powerful ways than our GUI tools allowed. Consider this example.

quasi %>% 
  filter(as.Date(date) < as.Date("1798-12-31"))
## Source: local data frame [38 x 13]
##          date   ship_1_name         ship_1_type ship_1_nationality
## 1  1798-09-28       America armed merchant ship                USA
## 2  1798-07-11      American armed merchant ship                USA
## 3  1798-09-27    Amphitrite armed merchant ship                USA
## 4  1798-05-09     Belvedere armed merchant ship                USA
## 5  1798-04-22 Boston Packet          armed brig                USA
## 6  1798-12-28       Camilla armed merchant ship                USA
## 7  1798-09-25    Carrollton armed merchant ship                USA
## 8  1798-09-27          Cato armed merchant ship                USA
## 9  1798-12-20        Chance      armed schooner                USA
## 10 1798-05-25         Diana armed merchant ship                USA
## ..        ...           ...                 ...                ...
## Variables not shown: ship_2_name (fctr), ship_2_nationality (fctr),
##   location (fctr), lat (dbl), long (dbl), outcome (fctr), source (fctr),
##   engagement_type (fctr), status (fctr)

These few lines of code might appear a little cryptic, but by looking at them we can figure out that we are taking our Quasi War data (in the variable called quasi) and keeping only the events that happened before the end of the year 1798.

You can certainly make all the maps that you need using the GUI tools that we have explored in this workshop, and that may be the right decision for you. But writing your own code gives you a powerful, flexible, and precise means of creating maps. The aim of this part of the workshop is to expose you to the possibilities of what you can do by learning the rudiments of a programming language.

Which language and libraries?

If you are going to use code to make maps, then you should almost certainly invest your time in learning a language that lets you make interactive maps for the web. All web pages are created using (at a minimum) HTML to structure the page, CSS to tell the browser what the page should look like, and JavaScript to add interactivity. Web maps like the one above use the popular Leaflet.js library, which uses JavaScript to create the map.3 You could certainly follow one of the many tutorials available for Leaflet in order to create a web map.

But for this workshop, we are going to use the R programming language. R is a language whose strength is data analysis, and it will let us create interactive maps that use JavaScript more easily than we could do in JavaScript itself. (The examples on this page above are in R.) At the workshop you will be provided with access to a server running R so that you do not need to install any software on your computer. But because R is open source, you can install all of the tools that we are using if you wish. You can find R itself here; I also recommend RStudio for use with R. You may wish to consult this book-in-progress about R.

  1. This data is courtesy of Abby Mullen, who also created a map and wrote a post about this data.

  2. This code can and will be rerun quite literally hundreds of times, and yet it will produce the same map each time.

  3. Another JavaScript library for mapping is D3.js.