The Defaults

Try the following:

map()

This should produce a default map of the world. To add axes and scale you can always type:

map.axes()
map.scale()

There are lots of other options. For example, the default map.scale() function draws a distance gauge (e.g. 100, 200, etc km) and a scale ratio (e.g. 1:4000000), but you can turn this into miles and suppress the ratio by specifying the options map.scale(metric=FALSE, ratio=FALSE).

Setting attributes

To get help on a function, e.g. map, type help(map) or ?map. The help screen gives a list of the attributes that can be specified for the function.

You'll often want to make maps of just part of the world. This is done by specifying xlim (limits on the x axis, i.e. longitude) and ylim (latitude). Longitude and latitude are always given in decimal degrees. The limits are written as R vectors, as follows c(MIN, MAX), where MIN is the lower value and MAX is the higher value:

map(xlim=c(140, 160), ylim=c(-20,10))

The default map used by the maps library is called "world". If you also use the mapdata library you'll have a high resolution map available (called "worldHires"). Compare the above to the following:

map("worldHires", xlim=c(140, 160), ylim=c(-20,10))

Working with spreadsheets

R is good at working with tabular data, so long as it is saved in a text-only format. A spreadsheet program like OpenOffice or Excel allows a spreadsheet to be saved as csv (comma separated values). I personally like to use tab delimited values rather than commas because they're easier to read and write (I often have fields that include commas or quotes, which can get very confusing if these are also used to show the edges of fields). The base function for reading tabular data is called read.table. Type ?read.table to see what options it has. Some important ones are header (first row is a header, TRUE or FALSE; sep (the separator character, e.g. "," or tab). There are some convenient wrapper functions for this that bundle up a bunch of settings:

read.csv()

comma-delimited, quoted fields, as produced by Excel

read.delim()

tab-delimited file (fields don't have to be quoted)

To read in data from a tab delimited file, simply call the function with the name of the data file as its argument. You can test this with the sample data file:

data = read.delim("language-data.txt")

Enter data to look at the data you've loaded, or try head(data) to just look at the first couple of rows.

If there is no header row, then use:

data = read.delim("language-data.txt", headers=FALSE)

With no header the columns will be labeled "VN", where N is the number of the column.

Read table and its kin return a data.frame object.

If the file "language_data.txt" contained the following (underscores represent a single tab space):

name__longitude_latitude
AAAA_________10_______10
BBBB________110_______25
CCCC________100_______15

Then data$name would return a list of all the names (strictly speaking, this is "vector" in R terms). The following would produce a simple scatterplot of longitude versus latitude:

plot(data$longitude, data$latitude)

The plot() function starts a new plot. If you have a map drawn with the map() function you can add points with the points() function, e.g.:

map()
points(data$longitude, data$latitude)

You could add labels with:

text(data$longitude, data$latitude, labels=data$name)

More map attributes

Here are a few routine tricks that will make mapping easier and/or prettier.

The range() and extendrange() functions.

The range() function returns the end points of a range, so from our sample spreadsheet range(data$longitude) returns the minimum and maximum, e.g. in this case the vector c(10, 100).

This is useful for setting the xlim and ylim attributes of a map:

map("world", xlim=range(data$longitude), ylim=range(data$latitude))

The extendrange() function is just the same, but it returns a little bit extra either side (by default 5%, but you can set this to a different figure, see ?extendrange)

Background colour

If you read the help on ?map there's a bit of advice on setting colours. A useful combination of attributes is fill=TRUE, col="white", bg="gray". This will produce white landmasses with gray seas.

Colouring items by value

R indexing is very powerful. Many attributes of functions can have vector of values, rather than a single value. For instance, instead of specifying col="blue", colours can be specified as a vector (e.g. col=c("red", "blue", "red", "yellow", ...). A simple way of getting such a vector is to add it to the same data frame that contains your data (in our example, data). Here's an example of how to do this (text from the # sign to the end of the line is a comment, and is ignored by R):

# add a new column to the data frame filled with the value "gray"
data$my.col = "gray"
# change the values of the $my.col column to "green" where the
# $group column is "Austronesian"
data$my.col[data$group == "Austronesian"] = "green"
# change the values of the $my.col column to "blue" where the
# $group column is "Trans New Guinea"
data$my.col[data$group == "Trans New Guinea"] = "blue"
# use the $my.col column of data as the values of the col attribute
points(data$longitude, data$latitude, col=data$my.col)

Add a legend

Uses the legend() function. Here's an example:

legend("bottomright",
  legend=c("Austronesian", "Papuan"),
  pch=19,
  col=c("red", "blue"),
  title="Language groups")

The first argument is the position of the legend. This function is quite clever: instead of specifying x-y (i.e. longitude and latitude) coordinates it is also possible to use the values bottomright, bottom, bottomleft, left, topleft, top, topright, right and center. If you use one of these then R will calculate the position itself. Read the help from ?legend for an explanation of the other arguments of this function.

Here is a basic example script using all these techniques to produce the map shown at the start of this document:

library(maps)                # only necessary if these libraries
library(mapdata)             # are not loaded already
data = read.delim("language-data.txt")
# trim the data so that we only have longitude less than 145°
data = data[data$longitude < 145,]
col.dict = data.frame(my.col=c("red", "blue", "green"),
  row.names=c("non-Trans New Guinea",
    "Trans New Guinea",
    "Austronesian"),
    stringsAsFactors=FALSE
  )
map("worldHires",            # higher resolution map than "world"
  xlim=extendrange(data$longitude),
  ylim=extendrange(data$latitude),
  fill=TRUE,
  col="white",
  bg="gray")
map.axes()
map.scale()
points(data$longitude,
  data$latitude,
  pch=19,                    # make the points solid dots
  cex=2,                     # make them double default size
  col=col.dict[data$group,]) # and draw them in nice colours
text(data$longitude,
  data$latitude,
  labels=data$name,
  pos=1)                     # put the text below the points

Note that functions can extend over multiple lines (so long as the parentheses match up). The help to ?points lists some of the other possible values for the point character (pch) attribute. Note also the use of col to set colour and cex to set the size ("character expansion").

Workflow

Running everything from a script.

If you save the instructions for drawing a map in a script, you can effortlessly regenerate your map after making small changes (e.g. when you notice some of you longitude-latitude pairs are wrong, or you want to switch from distinguishing points by colour to distinguishing them by shape)

• From the R application you can type source("my-script.r") to run the contents of a script as if you typed them in yourself

• From the command line you can type R --no-save < my-script.r (won't work for Windows)

You should archive your scripts for generating maps along with the ultimate, edited version that you use in publication. People are always asking "Do you have a colour version of that figure...?".

Comments

Write lots of comments in your scripts to help you interpret them later. Everything from a hash (#) to the end of a line is a comment, and will be ignored by the program. The example in the middle of the next paragraph is well commented.

Writing to pdf/eps/png etc

R writes graphics to a "device". If you are using R interactively (using the R console program, rather than running a script) the device is probably your computer screen. Whatever you do should be displayed immediately. But you can also use a graphics file as a device. This device has to be initialized using a function that creates the file in the right format (useful formats include pdf, postscript, png). Once the device is initialized all the R commands you run are composed in R's memory. Finally, you must close the device with dev.off(), and the combined graphics are written to the file Here is an example:

pdf("my_file.pdf", width=8, height=4) # initialize the file
map()              # compose some graphics (all in R's memory at this stage)
dev.off()          # write the accumulated graphics to the file

If you are doing this from a script, and the script has a bug so that it stops before getting to dev.off(), then the graphics file will not contain anything. This can be confusing...

When to stop

For publication quality maps you will probably find that you that there are some things that are too much trouble to do in R. For example, if you have lots of labelled points close together, then the labels will almost certainly overlap: it would be quite difficult to calculate the bounding box of each of these labels and to try and calculate visually acceptable, non-overlapping positions for them. When I get to this stage, I take a pdf drawn by R and edit it in a graphics program. Adobe Illustrator is a good choice, although expensive if you don't have it already. The program Inkscape is a good free alternative (I've only tried using it recently, but it seems perfectly adequate). Note that Photoshop is not suitable: Photoshop does not let you select vector objects, such as lines, points, text boxes, etc. Note also that if you want to tidy up a graphics file, it has to be in a vector format (pdf, postscript for illustrator, or svg for Inkscape).