Instant Heat Maps in R How-to

Loading packages: The first eight lines preceding the ### loading data section will make sure that R loads the lattice and gplots package, which we need for the two heat map functions in this recipe: levelplot() and heatmap.2().

Loading the data set: R includes a package called data, which contains a variety of different data sets for testing and exploration purposes. More information on the different data sets that are contained in the data package can be found at http://stat.ethz.ch/ROmanual/ROpatched/library/datasets/.

For this recipe, we are loading the AirPassenger data set, which is a collection of the total count of air passengers (in thousands) for international airlines from 1949-1960 in a time-series format.

data(AirPassengers)

Converting the data set into a numeric matrix: Before we can use the heat map functions, we need to convert the AirPassenger time-series data into a numeric matrix first. Numeric matrices in R can have characters as row and column labels, but the content itself must consist of one single mode: numerical.

We use the matrix() function to create a numeric matrix consisting of 12 columns to which we pass the AirPassenger time-series data row-by-row. Using the argument dimnames = rowcolNames, we provide row and column names that we assigned previously to the variable rowColNames, which is a list of two vectors: a series of 12 strings representing the years 1949 to 1960, and a series of strings for the 12 three-letter abbreviations of the months from January to December, respectively.

rowcolNames <- list(as.character(1949:1960), month.abb)
air_data <- matrix(AirPassengers, 
  ncol = 12, 
  byrow = TRUE, 
  dimnames = rowcolNames)

A si mple heat map using levelplot(): Now that we have converted the AirPassenger data into a numeric matrix format and assigned it to the variable air_data, we can go ahead and construct our first heat map using the levelplot() function from the lattice package:

print(levelplot(air_data,
  col.regions=heat.colors, 
  xlab = "year",
  ylab = "month", 
  main = "Air Passengers #1"))

The levelplot() function creates a simple heat map with a color key to the right-hand side of the map. We can use the argument col.regions = heat.colors to change the default color transition to yellow and red. X and y axis labels are specified by the xlab and ylab parameters, respectively, and the main parameter gives our heat map its caption.

Creating enhanced heat maps with heatmap.2(): Next, we will use the heatmap.2() function to apply a clustering algorithm to the AirPassenger data and to add row and column dendrograms to our heat map:

heatmap.2(air_data, 
    trace = "none", 
    density.info = "none", 
  xlab = "month", 
  ylab = "year", 
  main = "Air Passengers #2")

Another neat feature of heatmap.2() is that you can display a histogram of the count of the individual values inside the color key by including the argument density.info = NULL in the function call. Alternatively, you can set density.info = "density" for displaying a density plot inside the color key.

By adding the argument keysize = 1.8, we are slightly increasing the size of the color key—the default value of keysize is 1.5:

heatmap.2(air_data, 
  trace = "none", 
  xlab = "month", 
  ylab = "year", 
  main = "Air Passengers #3",
density.info = "histogram",  
dendrogram = "column",
  keysize = 1.8) 

Did you notice the missing row dendrogram in the resulting heat map? This is due to the argument dendrogram = "column" that we passed to the heat map function. Similarly, you can type row instead of column to suppress the column dendrogram, or use neither to draw no dendrogram at all.

Inspecting gene_expression.txt: The first file that reads into R, gene_expression.txt, contains exemplary gene expression data obtained from two different conditions: control and treatment. The individual values in this data file resemble fold-differences of gene expression relative to a housekeeping gene that was used as a reference to normalize the data.

The data was saved as a .txt file and consists of 105 lines. The first two lines from the top are comments about the data and begin with a slash (/) as the first character. Followed by two blank lines, a header labels the two data columns of the expression data under the two conditions.

Notice that the data columns are separated by tab spaces as shown in the following screenshot of the gene_expression.txt data set:

Reading data from gene_expression.txt: Let's take a look at the arguments we need to provide in the read.table() function in order to read this data file as a data table into R:

gene_data <- read.table("gene_expression.txt",
  comment.char = "/", 
  blank.lines.skip = TRUE,
  header = TRUE,  
  sep = "\t", 
  nrows = 20)

When we use the read.table() function, R ignores every line in the data file that starts with a hash mark (#), which is the default comment character. However, the first character of the comment lines in our data file is a forward slash (/). Therefore, we have to pass it to the function as an additional argument for the comment.char parameter so R can interpret the first two lines in gene_expression.txt as comments and skip them. The second argument, blank.lines.skip = TRUE, ensures that R also skips the two blank lines after the comment section.

From here on, R will read every line that follows and will interpret it as data—skipping the comment and blank lines at the beginning.

There are two data columns in this text file, which are labeled as Control and Treatment. By setting the header parameter to TRUE, R will store these labels as a header for our data table. The header is followed by 100 rows of tab-delimited data (Gene1 to Gene100). We need to use the argument sep = "/t" to set the field separator character to a tab space, since the default data field separator is the white space, sep = "".

The data file is quite large with its 100 entries, and for this example, we just use the first 20 genes to create our heat map. We can tell R to stop reading data after the 20th entry by providing the argument nrows = 20 in the function call.

Converting the data table into a numerical matrix: As we remember from the Creating your first heat map in R recipe, we need to convert our data into a numeric matrix format before we can use it to create a heat map. Instead of using the relative expression measures deployed in the data file, we are interested in showing the fold-changes of the gene expression levels. To calculate those fold-changes of the Treatment column in relation to the Control column, we are using the outer() function. This function allows us to create a 20 x 20 matrix by dividing each gene from the Treatment column (third column in the data file) by each gene from the Control column (second column in the data file):

gene_data <- data.matrix(gene_data)
gene_ratio <- outer(gene_data[,"Treatment"],
  gene_data[,"Control"], 
  FUN = "/")

Reading data from runners.csv: The runners.csv file contains the fastest personal times of seven popular 100 meters sprinters for the years between 2003 and 2012.

If we want to read a data file with comma-separated values, it is most convenient to use the read.csv() function:

runner_data <- read.csv("runners.csv")

runner_data <- read.table("runners.csv",
header = TRUE,
sep = ",",…)

Dealing with missing values in runners.csv: The default constant for missing values in R is NA, which stands for Not Available. Therefore, if we read data from a file that contains empty fields, missing values will be replaced by NA when R creates the data table.

When we read in runner_data.csv, we see that our data table contains many 0.00 values, which means that no time was recorded for the runner in those years. However, it would make more sense to have those values denoted as missing data (NA) in our heat map.

So, if we want R to interpret values other than NA or empty fields as missing values, we do this by providing an argument for the na.strings parameter in our read.table() or read.csv() function:

runner_data <- read.csv("runners.csv", na.strings = 0.00)

runner_data[runner_data == 0.00] <- NA

By default, cells with NA values will be left blank and appear as white cells in our heat map. This can be very misleading, since the color palette that we are using converges into a very bright yellow. It would be very hard to distinguish those empty cells from values that are seeded very high in our color key.

To avoid this confusion, we can simply assign a different color to those cells that contain missing values. Here, we are coloring them in gray:

heatmap.2(runner_data, 
    dendrogram = "none", 
  Colv = NA,
  Rowv = NA,
  trace = "none", 
  na.color = "gray",
  main = "runners.csv",
  margin = c(8,10))

runner_data <- na.omit(runner_data)

Reading Apple's stock data from an Excel spreadsheet file: Now, let us take a look at Apple's daily stock market data from 1984 to 2013.

The following screenshot shows the apple_stock.xlsx data set opened in Microsoft Excel 2011:

R has no in-built function to read data from this proprietary format. But, we are lucky that someone developed the xlsx package especially for this case that is freely available on CRAN. Therefore, we can use the read.xlsx() function to conveniently get this data from apple_stock.xlsx into R.

stocks_table <- read.xlsx("apple_stocks.xlsx", 
  sheetIndex = 1, 
  rowIndex = c(1:28), 
  colIndex = c(1:5,7))

With sheetIndex, we have selected which sheet we want to read from the Excel spreadsheet file—apple_stock.xlsx only has data on sheet 1. The spreadsheet consists of 7168 rows of data, but we are interested only in the recent data stock data of 2013. So, to only read in those first 28 lines, we included the rowIndex = c(1:28) argument in the read.xlsx() function call above. Furthermore, we are not interested in the Volume column (column 6), so let's skip it via the argument colIndex = c(1:5,7).

In most cases, we will use the read.table() function to read our data into R. The following table summarizes the most important options:

Inspecting the arabidopsis_genes.csv data set: The arabidopsis_genes.csv file contains a compilation of gene expression data from the model plant Arabidopsis thaliana. I obtained the freely available data of 16 different genes as log 2 ratios of target and reference gene from the Arabidopsis eFP Browser (http://bar.utoronto.ca/efp_arabidopsis/). For each gene, expression data of 47 different areas of the plant is available in this data file.

Reading the data and converting it into a numeric matrix: As we already know from the previous recipe, we have to convert the data table into a numeric matrix first before we can construct our heat maps:

gene_data <- read.csv("arabidopsis_genes.csv")
row_names <- gene_data[,1]
gene_data <- data.matrix(gene_data[,2:ncol(gene_data)])
rownames(gene_data) <- row_names 

Creating a customized heatmap.2() function: To reduce typing efforts, we are defining our own version of the heatmap.2() function now, where we will include some arguments that we are planning to keep using throughout this recipe:

heat2 <- function(...) heatmap.2(gene_data, 
  tracecol = "black",
  dendrogram = "column", 
  Rowv = NA, 
  trace = "none", 
  margins = c(8,10), 
  density.info = "density", ...)

So, each time we call our newly defined heat2() function, it will behave similar to the heatmap.2() function, except for the additional arguments that we will pass along. We also include a new argument, black, for the tracecol parameter, to better distinguish the density plot in the color key from the background.

The built-in color palettes: In the previous recipes, we used the default color palette of heatmap.2(), heat.colors, which represents a color transition from yellow to red. There are four more color palettes available in the base R that we could use instead of the heat.colors palette: rainbow, terrain.colors, topo.colors, and cm.colors.

So let us make use of the terrain.colors color palette now, which will give us a nice color transition from green over yellow to rose:

heat2(col = terrain.colors(n = 1000), 
  main = "1.1) Terrain Colors")

If you recall the heat maps that we created in the previous two recipes, you might have noticed that the transition between the colors in the color key was not really smooth, but rather abrupt. The five color palettes mentioned previously allow us to define the number of different color shades that we can use. Therefore every number for the parameter n that is larger than the default value 12 will add additional colors, which will make the transition smoother. A value of 1000 for the n parameter should be more than sufficient to make the transition between the individual colors indistinguishable to the human eye.

The following image shows a side-by-side comparison of the heat.colors and terrain.colors color palettes using a different number of color shades:

rev_heat.colors <- function(x) rev(heat.colors(x))
heat2(col = rev_heat.colors(500))

RColorBrewer palettes: A lot of color palettes are available from the RColorBrewer package. To see how they look like, you can type display.brewer.all() into the R command-line after loading the RColorBrewer package. However, in contrast to the dynamic range color palettes that we have seen previously, the RColorBrewer palettes have a distinct number of different colors. So to select all nine colors from the YlOrRd palette, a gradient from yellow to red, we use the following command:

heat2(col = brewer.pal(n = 9, "YlOrRd"),
  main = "1.2) Brewer Palette")

The following image gives you a good overview of all the different color palettes that are available from the RColorBrewer package:

Creating our own color palettes: Next, we will see how we can create our own color palettes. A whole bunch of different colors are already defined in R. An overview of those colors can be seen by typing colors() into the command line of R.

The most convenient way to assign new colors to a color palette is using hex colors (hexadecimal colors). Many different online tools are freely available that allow us to obtain the necessary hex codes. A great example is color picker (http://www.colorpicker.com), which allows us to choose from a rich color table and provides us with the corresponding hex codes.

Once we gather all the hexadecimal codes for the colors that we want to use for our color palette, we can assign them to a variable as we have done before with the explicit color names:

my_colors <- c(y1 = "#F7F7D0", 
  y2 = "#FCFC3A", 
  y3 = "#D4D40D", 
  b1 = "#40EDEA",
  b2 = "#18B3F0", 
  b3 = "#186BF0", 
  r1 = "#FA8E8E",
  r2 = "#F26666", 
  r1 = "#C70404")
heat2(col = my_colors, 
  main = "1.3) Own Color Palette")

This is a very handy approach for creating a color key with very distinct colors. However, the downside of this method is that we have to provide a lot of different colors if we want to create a smooth color gradient; we have used 1000 different colors for the terrain.color() palette to get a smooth transition in the color key!

Using colorRampPalette for smoother color gradients: A convenient approach to create a smoother color gradient is to use the colorRampPalette() function, so we don't have to insert all the different colors manually. The function takes a vector of different colors as an argument. Here, we provide three colors: blue for the lower end of the color key, yellow for the middle range, and red for the higher end. As we did it for the in-built color palettes, such as heat.color, we assign the value 1000 to the n parameter:

my_palette <- colorRampPalette(c("blue", "yellow", "red"))(n = 1000)
heat2(col = my_palette, main = "1.3) ColorRampPalette")

Grayscales: It might happen that the medium or device that we use to display our heat maps does not support colors. Under these circumstances, we can use the gray palette to create a heat map that is optimized for those conditions.

The level parameter of the gray() function takes a vector with values between 0 and 1 as an argument, where 0 represents black and 1 represents white, respectively. For a smooth gradient, we use a vector with 100 equally spaced shades of gray ranging from 0 to 1.

heat2(col = gray(level = (0:200)/200),
  main ="1.4) Gray Scale")

Adding cell notes to our heat map: Sometimes, we want to show a data set along with our heat map. A neat way is to use so-called cell notes to display data values inside the individual heat map cells. The underlying data matrix for the cell notes does not necessarily have to be the same numeric matrix we used to construct our heat map, as long as it has the same number of rows and columns.

As we recall, the data we read from arabidopsis_genes.csv resembles log 2 ratios of sample and reference gene expression levels. Let us calculate the fold changes of the gene expression levels now and display them—rounded to two digits after the decimal point—as cell notes on our heat map:

fold_change <- 2^gene_data
rounded_fold_changes <- round(fold_change, 2)
heat2(cellnote = rounded_fold_changes, 
  notecex = 0.5, 
  notecol = "black", 
  col = rev_heat.colors,
  main = "Cell Notes")

The notecex parameter controls the size of the cell notes. Its default size is 1, and every argument between 0 and 1 will make the font smaller, whereas values larger than 1 will make the font larger. Here, we decreased the font size of the cell notes by 50 percent to fit it into the cell boundaries. Also, we want to display the cell notes in black to have a nice contrast to the colored background; this is controlled by the notecol parameter.

Row and column side colors: Another approach to pronounce certain regions, that is, rows or columns on the heat map is to make use of row and column side colors. The ColSideColors argument will place a colored box between the dendrogram and heat map that can be used to annotate certain columns. We pass our vector with colors to ColSideColors, where its length must be equal to the number of columns of the heat map. Here, we want to color the first and third column red, the second one gray, and all the remaining 13 columns green:

heat2(ColSideColors = c("red", "gray", "red", rep("green", 13)),
  main = "ColSideColors")

You can see in the following image how the column side colors look like when we include the ColSideColors argument as shown previously:

Attentive readers may have noticed that the order of colors in the column color box slightly differs from the order of colors we passed as a vector to ColSideColors. We see red two times next to each other, followed by a green and a gray box. This is due to the fact that the columns of our heat map have been reordered by the hierarchical clustering algorithm.

Annual average temperatures of the United States: The first data file, usa_temp.csv, contains the annual average temperatures of the USA from 1971 to 2001. The data was made available by the National Climatic Data Center of the United States, National Oceanic and Atmospheric Administration, and has been compiled by current results.

Reading in map and temperature data: First, we use the read.csv() function, known from the Reading data from different file formats recipe, to read our data and assign it to the variable usa_temp. Next, we use the map_data() function from the ggplot2 package to read in the United States map from maps as a data frame.

Note that in contrast to the heat map functions that we have been using in the previous recipes, the gplot() function takes a data frame as input instead of data in a numerical matrix format. And as we remember from the Reading data from different file formats recipe, data that we read via read.csv() is converted into a data frame automatically.

Merging and sorting the data frames: Now we will merge the map and temperature data:

usa_data <- merge(usa_temp, usa_map, 
by.x = "state", by.y = "region") 
usa_sorted <- usa_data[order(usa_data["order"]),]

The following flowchart illustrates this process and shows how the data looks like before and after the merging and conversion:

As we can see in the preceding chart, the map data in the usa_map data frame contains multiple longitudinal (long) and latitudinal (lat) coordinates for each state in the column labeled with region. The numbers in the order column specify the order in which the single dots are connected when we draw the map as a polygon.

After we merged both map data and temperature data, we can see that the values in the order column have been shuffled. This would result in quite a mess when we wanted to construct the choropleth map from this data frame. Therefore, we use the order() function to restore the original order before we merged the data sets.

Constructing our first choropleth map: Now that we have our data ready in a nice format, we can proceed to the main plotting functions to create our first choropleth map:

usa_map1 <- ggplot(data = usa_sorted) + 
  geom_polygon(aes(x = long, y = lat, group = group, 
fill = fahrenheit)) + 
  ggtitle("USA Map 1")

Basically, how the ggplot2 package works is that we have to create our plots incrementally. First, we use the ggplot() function to assign our data to a new plot object, and then we can add further layers to it. The basic shape of ggplot2 plots is determined by so-called geoms, or geometric objects. Here, we are using geom_polygon(), which will connect our coordinate points to a map. The aes() function nested inside is there for aesthetics and defines the visual properties of the geoms. We provide the variable fahrenheit as an argument for the fill parameter so that we can shade the areas of our choropleth maps according to the Fahrenheit temperatures in our data set.

Customizing choropleth maps: One of the advantages of ggplot2 is that we do not have to retype the whole heat map function with its arguments each time we want to modify the map, since we store our plots as objects. So if we want to convert our map into a polyconic projection, we can simple reuse our old graphic object and make a small modification:

 usa_map2 <- usa_map1 + coord_map("polyconic") + 
  ggtitle("USA Map 2 - polyconic")

Now, let us add another geometric object so that the state borders will be drawn as black lines:

usa_map3 <- usa_map2 + 
  geom_path(aes(x = long, y = lat, group = group), 
color = "black") + 
  ggtitle("USA Map 3 - black contours")

Since we are showing temperatures on our United States map, it would be more appropriate to replace the blue default color gradient by a color gradient from yellow to red. We can modify the color gradient by adding the scale_fill_gradient() function with two color arguments for our previous graphic object:

usa_map4 <- usa_map3 + 
  scale_fill_gradient(low = "yellow", high = "red") + 
  ggtitle("USA Map 4 - gradient 1")

If we want to add a third color to our gradient, we can use the scale_fill_gradient2() function instead. For this function, we need an additional argument that specifies the position (mid-point) of the second color. We can simply use the temperature mean such as a midpoint measure:

usa_map5 <- usa_map3 + 
scale_fill_gradient2(low = "steelblue", mid = "yellow",
high = "red",  midpoint =   
colMeans(usa_sorted["fahrenheit"])) + 
  ggtitle("USA Map 5 - gradient 2")

Extracting regions from the world map: Now that we have seen how we can use ggplot2 to create simple choropleth maps, let us explore some advanced features.

As you can see in the table at the end of this section, the number of maps in the maps and mapdata packages is quite limited. However, we are able to extract individual countries from the world map.

Our second data set, south_am_pop.csv, contains recent population counts of all the countries of South America. Unfortunately, neither maps nor mapdata contains a map of this continent, so we extract all the South American countries from the high resolution world map of mapdata.

south_am_map <- map_data("worldHires", region = c("Argentina",
"Bolivia", "Brazil","Chile", "Colombia", "Ecuador", 
"Falkland Islands", "French Guiana", "Guyana", 
"Paraguay", "Peru", "Suriname", "Uruguay", "Venezuela"))

After we read the data from south_am_pop.csv and merge and sort the data frames, we can create the choropleth map:

south_am_map1 <- ggplot(data = south_am_sorted) + 
  geom_polygon(aes(x = long, y = lat, 
group = group, fill = population)) +
  geom_path(aes(x = long, y = lat, group = group), 
color = "black") + 
  coord_map("polyconic") + 
scale_fill_gradient(low = "lightyellow",
  high = "red", guide = "legend")

As we have seen it for the USA map before, we use the ggplot() function to create a new plot object and geom_polygon to construct the map graphic. With the color parameter in geom_path, we add a black border around the individual countries, and with the coord_map function, we convert our map into a polyconic projection. We also change the color gradient from light-yellow to red and make the legend categorical by providing the argument legend for the guide parameter.

By default, ggplot2 creates plots on a gray background with a white grid. To get a nicer layout, let us create a map on a clean, white background and remove axes tick marks, labels, and titles altogether:

south_am_map2 = south_am_map1 + 
  theme(panel.background = element_blank(),
  axis.text = element_blank(), 
  axis.title = element_blank(), 
  axis.ticks = element_blank())

In the following image, you can see the resulting choropleth map of South America's population count on a white background:

Volcano contour plot: As mentioned in the introduction of this recipe, we want to take a look at another type of map representation, contour plots:

data(volcano)
image.plot(volcano)

Using the image.plot() function from the fields library, we construct a color grid with the topographical data of a volcano from R's data package. We could also use the image() base function in R, but the image.plot() function has some nice additional features, such as placing a legend for the color grid to the right of the plot.

After we created the underlying color grid, we use the contour() function to place the contour lines on top of the color grid.

contour(volcano, add = TRUE)

The following image shows the final contour plot that we have created from the volcano data set:

Reading data: For this recipe, we will use the co2 data set from the data package in R. This co2 data set is a time-series that consists of 468 monthly measurements of carbon dioxide (CO2) concentrations in parts per million (ppm) from 1959 to 1997.

We know from the Creating your first heat map in R recipe how to convert data from a time-series format into a numeric matrix, which is the only format that is compatible with the heatmap2.() function.

Setting up our own heatmap.2() function: Like we did in the Customizing heat maps recipe, we create our own derivative of the heatmap.2() function with some default arguments that we want to use for all our heat maps in this recipe to avoid repetitive typing efforts:

heat2 <- function(...) 
  heatmap.2(co2_data,
trace = "none", 
  density.info = "none", 
  dendrogram = "none",
  Colv = FALSE,
  Rowv = FALSE,
  col = colorRampPalette(c("blue", "yellow", "red")),
(n = 100),
  margin = c(5,8),
  lhei = c(0.25,1.25),
   ...)

We use a new parameter lhei that we have not encountered so far. With this parameter, we can control the height of the different plot elements. The arguments we provide here will make our legend thinner.

Before we proceed with the graphic devices, let us briefly take a look at the general paradigm of creating image files in R, which consists of three basic steps as follows:

Creating image files: First, let us create a PNG file using the png() function with its default parameters:

png("1_PNG_default.png")
heat2(main = "PNG default")
dev.off()

The first argument that the graphics device takes is the name of the output file. After we open the graphics device, we create the heat map using our heat2() function, and lastly, we close the graphic device with the dev.off() function.

Because the resolution of the PNG image is very low (75 ppi) when we use png() with its default parameters, we create another PNG file with a resolution of 300 ppi, which should provide reasonable quality for a print out on a letter-sized piece of paper. The default size of png() is measured in pixels, and here we are creating a 5 x 5 inches output by taking the number of pixels per inch and multiplying it by 5 inches. Further, we decrease the text size slightly from 12 to 8 bp (1 bp equals 1/72 inches) in the pointsize parameter:

png("2_PNG_highres.png", 
  width = 5*300, 
  height = 5*300, 
  res = 300, 
  pointsize = 8)
heat2(main = "PNG High Resolution")
dev.off()

Next, we create a JPEG, BMB, SVG, and PDF file with the same parameters so we can compare them to each other. Note that the height and width of the SVG and PDF files are measured in inches.

When we compare those different image files to each other, we see that they all show the same heat map, but if we zoom in, we notice that the quality differs tremendously.

In the following image, you can see the tremendous difference in the image quality between the different file formats. This is something you should consider, especially if you are preparing your graphics for an on-screen presentation.

When we view the BMP, PNG, and JPEG images, the quality seems to be quite reasonable. But as soon as we zoom in on the image, we can barely read the text of the PNG file with the 75 ppi default. In contrast to the 300 ppi BMP, PNG and JPEG files do not have any jagged edges in the PDF and SVG files, no matter how far we zoom in.

More options: So if we have the choice between the different raster graphics formats, I recommend using PNG, since the files are way smaller then BMP files due to the lossless compression. Using JPEG over PNG should only be considered if file size really matters to you.

In contrast to JPEG files, BMP and PNG files support transparent backgrounds. This is particularly useful if we want to place the heat map on a patterned background, on a poster, or a presentation slide for example. This can be specified by providing the argument transparent for the bg (background) parameter.

png("test/8_PNG_transp.png", 
  width = 5*300, 
  height = 5*300, 
  res = 300, 
  pointsize = 8,
  bg = "transparent")
heat2(main = "PNG Transparent Background")
dev.off()

The PDF format has the further advantage wherein we can choose a different font family if we like. We can choose from AvantGarde, Bookman, Courier, Helvetica, Helvetica-Narrow, NewCenturySchoolbook, Palatino, and Times. Also, we can specify the paper format, such as a4 for DIN A4, letter for the American Standard Letter format, or a4r and USr for the respective rotated landscape formats:

pdf("9_PDF_mono.pdf",
  family = "Courier",
  paper = "USr")
heat2(main = "PDF Monospace Font")
dev.off()

Creating a heat map SVG file in R: First, we create our heat map by running the R script 5644OS_06_01.r. By now, the contents of the script should look very familiar to us, but let us go over it briefly.

We create our heat map from the mtcars data set from the R data package. The data set contains information about 32 car models from 1973-1974. The data columns from 1 to 7 contain information on miles per gallon, number of cylinders, displacement in cubic inches, horsepower, rear axle ratio, weight (lb/1000), and one fourth mile time.

data(mtcars)
car_data <- mtcars[,1:7]
write.matrix(car_data, "car_data.csv", sep = ",")

Using the write.matrix() function, we add the mtcars data in a CSV file. We will need this data file later to add tool tips to our heat map.

We use the scale() function to normalize the data, so we can compare the different variables of mtcars to each other in the heat map. Note that mtcars is in a data frame format, but scale() will automatically convert it into a numerical matrix. Finally, we open a new graphic device to save our heat map to an SVG file.

norm_cars <- scale(car_data) 

# Creating heat map
svg("car_heatmap.svg")
heatmap.2(norm_cars, 
  density.info = "none",
  trace = "none",
  dendrogram = "none",
  Rowv = FALSE, 
  Colv = FALSE,
  margin = c(5,10))

dev.off()

HeatModSVG options overview: Now that we have created an SVG file of our heat map, we can use the HeatModSVG program to add some interactivity to it. Let us take a look at the execution of the program before we discuss how it modifies the SVG file in more detail.

First, the program asks us whether we want to add Tool Tips or Zoom and Panning or both. When we choose both, the program will insert tool tip labels from an external data file that will be displayed in the individual heat map cells when we hover over it with the mouse pointer. Further, the program will embed a reference to Andrea Leofreddi's SVGPan JavaScript library, which will add features like zooming, dragging, and panning to our heat map.

Reading a data file into HeatModSVG: To add tool tips to our heat map, the HeatModSVG program will prompt us for a data file in addition to the SVG file that we want to modify.

This tool tip label data can stem from the same data file that we used to create our heat map, or it can be another text file that contains data with the same dimensions (a similar number of rows and columns like the heat map data file).

In our case, we want to show the original values of the mtcars columns from 1 to 7 that we saved to car_data.csv before we normalize the data to create the heat map.

The following screenshot highlights the important formatting features of the car_data.csv file that we have to feed into the HeatModSVG program:

The HeatModSVG program will ask us for the format of the comment characters in the data file, so it can ignore those lines when it reads the data. We entered #, but in the case of car_data.csv, it does not really matter, since car_data.csv does not contain any comments.

Next, we chose c (comma) as the column separator, since we created car_data.csv as a Comma Separated Value file in R. When HeatModSVG asks us for row labels, we choose no, and for column names, we choose yes, since car_data.csv only has a header and no row labels.

After we have specified all these options HeatModSVG prompted us to make, the contents of the data file will be printed to the screen based on how it was read in by HeatModSVG. This is the point where we should double-check whether we provided the correct options to HeatModSVG for reading in the data file—we should only see the matrix values here and no row and column labels.

Finally, the program will ask us if we want to add a label that will be placed in front of our tool tips. If we would have chosen yes, we would have been prompted to enter a character or character string that will appear as a global label in front of our tool tip values, and the tool tips would then be displayed in the following format: <Label:> <value>.

Just before the program finishes, it will notify us about the changes that it made to the original SVG file:

... inserted CSS <style> tag after line 2

... inserted link to svgPan.js after CSS <style> tag

... added viewport ID in line 286

... IDs and tool tip <title> tags were inserted in lines 289 
    to 512

Saving . . . . . . . . 

==> Created /Users/sebastian/Desktop/NEW_car_heatmap.svg

Modification to the SVG file: Let us take a look at the changes made by HeatModSVG step-by-step to understand how the interactivity effect works:

... inserted CSS <style> tag after line 2

When we open the new SVG file, NEW_car_heatmap.svg, we see that the program inserted a CSS style tag just after line 2:

<style>
#hoverItem:hover{opacity: 0.3;}
</style>

This CSS style tag adds a mouse-over or hover effect to each element in the XML file that we label with the CSS ID hoverItem.

Next, a link to the SVGPan.js JavaScript file was inserted at the top of the SVG file, right after the previously inserted CSS style tag:

... inserted link to svgPan.js after CSS <style> tag

The link to the JavaScript file looks like this:

<script xlink:href="SVGPan.js"/>

In order for svgpan to work, it has to be in the same folder as the SVG file, or else we have to add the path in front of it.

<script> SVGPan.js contents </script>

In order for the SVGPan effects to work, we have to add the ID viewport to the heat map elements:

... added viewport ID in line 286

Note that the number 286 refers to the location in the original SVG file; since we inserted four lines already, we will find the viewport ID opening tag in line 290 of the new SVG file:

<g id="viewport">. 

In fact, viewport replaced another ID, surface61; this is the ID that determines the start of the visual elements of our heat map.

At this point, you may ask why we need an extra program to make those tiny changes to the XML code. In fact, we could have done everything manually in no time, but stay tuned, because now comes the laborious part:

... IDs and tool tip <title> tags were inserted in lines 289 to 512

At the beginning, we saw the CSS style tag that contained the hover action added in line number 3. Now, we have to assign it to each individual cell of the heat map by adding the hoverItem ID. Further, we want to add the tool tip label from the car_data.csv file to these cells too, so that a value appears if we hover over a particular cell in the heat map.

Without a program to automate this process, we would have to repeat this process 224 times to add the hoverItem ID and tool tip label to each cell of the 32 x 7 heat map.

The following screenshot shows an XML that shows how an exemplary heat map cell looks like before and after the conversion: