The way we view graphical representations of data has significantly changed in recent years. For example, viewers expect to interact with a graphic on the Web by clicking on it to get more information, to produce a different view, or control an animation. These capabilities are available in Scalable Vector Graphics (SVG) [1, W3 Schools SVG Tutorial], and in this article, we describe an approach within R [2] to creating stand-alone interactive graphics and animations using SVG. SVG offers interactivity and animation through a rich set of elements that allow the graphics objects to be grouped, styled, transformed, composed with other rendered objects, clipped, masked, and filtered. SVG may not be the most ideal approach to interactive graphics, but it has advantages that come from its simplicity and increasing use on the Web and publishing generally. The approach presented here uses R's high-level plotting functions, R's SVG graphics device engine and the third-party cairo rendering engine [18] to create high-quality plots in SVG. Our tools then allow users to post-process the SVG documents/plots to provide the additional annotations to make the document interactive, e.g. users can add hyperlinks, tool tips, linked plots, controls (sliders and buttons), and animation to these displays to create potentially rich, compelling graphical displays that can be viewed outside of the R environment.

The SVGAnnotation package [17] contains a suite of tools to facilitate the programmer in this process. The package uses the XML [ Open XML] parsing and writing facilities in the XML package [16] to provide “high-level” facilities for augmenting the SVG output from the standard plotting functions in R, including lattice [20] and the traditional grz-model plotting functions in R. In addition to providing useful higher-levels facilities for modifying the more common R plots, the SVGAnnotation package also provides many utilities to handle other types of plots, e.g. maps and graphs. Of course, it is possible to generate interactive graphics from “scratch” by taking charge of all drawing, e.g. determining the coordinate system and drawing the axes, tick marks, labels, etc. However for complex data plots, we are much better off using this post-processing approach and leveraging R's excellent existing graphics facilities.

We do not want to suggest that the approach presented here is the definitive or dominant solution to the quest for general interactive graphics for R or statistics generally. Our focus is on making graphical displays created in R available in new ways to different audiences outside of R and within modern multi-media environments. This approach works well in many cases, and the XML tools in XML make it an alternative that we believe is worth exploring. While the popularity or uptake of this approach may be debatable due to prospects of SVG or implementations of the complete SVG specification in widely used browsers, what we have implemented can be readily adapated to other formats such as Flash or the JavaScript canvas. Hence this paper also provides ideas for future work with other similar graphical formats such as Flash and Flex MXML [28] and the JavaScript canvas. The essential idea is to post-process regular R graphics output and identify and combine the low-level graphical objects (e.g. lines and text) into higher-level components within the plot (e.g. axes and labels). Given this association, we can then annotate components to create interactive, dynamic and animated plots in various formats.

The remainder of the paper is organized as follows. We start by explaining reasons why SVG is a valuable format. We then give a brief introduction to several examples that we use throughout the document. These illustrate different features of SVG and how they might be used for displaying statistical results. We then introduce the common elements of SVG and examine the typical SVG document produced when plotting in R. From there we move on to explore general facilities that one may use to add to an SVG plot generated within R. The examples serve as the context for the discussion of these functions and the general approach. The facilities include adding tool tips and hyperlinks to elements of a display and more advanced features that deal with non-standard R displays and animation. We also show how one can add GUI components directly in SVG and alternatively use HTML forms with SVG. Additionally, we illustrate aspects of integrating JavaScript and SVG. We conclude the paper by discussing different directions we are exploring in this general area of stand-alone, interactive, animated graphics that can be displayed on the Web.

We discuss several technologies in this paper which may be new to readers. We provide an introduction to XML and also to JavaScript in two appendices. It may be useful for some readers to review these before reading the rest of this paper.

We also note that this paper can be viewed as an HTML document (at http://www.omegahat.org/SVGAnnotation/JSSPaper.html) and the SVG displays within it are "live", i.e. interactive and/or animated. That is a better medium for understanding the material than the printed, static medium.

Scalable Vector Graphics (SVG) is an XML format for describing two dimensional (2-D) graphical displays that also supports interactivity, animation, and filters for special effects on the different elements within the display. SVG is a vector-based system that describes an image as a series of geometric shapes. Compare this to a raster representation that uses a rectangular array of pixels (picture elements) to represent what appears at each location in the display. An SVG document includes the commands to draw shapes at specific sets of coordinates. These shapes are infinitely scalable because they are vector descriptions, i.e. the viewer can adjust and change the display (for example, to zoom in and refocus) and maintain a clear picture.

SVG is a graphics format similar to PNG, JPEG, and PDF. Many commonly used Web browsers directly support SVG (Firefox, Opera, Safari) and there is a plug-in for Internet Explorer. For example, Firefox can act as a rendering engine that interprets the vector description and draws the objects in the display within the page on the screen. There are also other non-Web-browser viewers for SVG such as Inkscape (http://www.inkscape.org/) and Squiggle (based on Apache's Batik) (http://xmlgraphics.apache.org/batik/tools/browser.html). In addition, SVG can, as we will see, be included in HTML documents, like JPEG and PNG, or in-lined within HTML content. However, quite differently from other image formats, SVG graphics, and their sub-elements, remain interactive when displayed within an HTML document and can participate as components in rich applications that interact with other graphics and HTML components. SVG graphics can also be included in PDF documents using an XML-based page description language named Formatting Objects (FO) [29], which is used for high-quality typesetting of XML documents. In summary, SVG is a viable alternative to PNG and JPEG formats, and it is also capable of fine-grained scaling and allows for interactivity and animation of individual objects in the display.

The size of SVG files can be both significantly smaller or larger than the corresponding raster displays, e.g. PNG and JPEG. This is very similar to PDF and Postscript formats. For simple displays with few elements, an SVG document will have entries for just those elements and so be quite small. Bitmap formats however will have the same size regardless of the content as it is the dimensions of the canvas that determines the content of the file. As a result, for complex displays with many elements, an SVG file may be much larger than a bitmap format. Furthermore, SVG is an XML vocabulary and so suffers from the verbosity of that format. However, SVG is also a regular text format and so can be greatly compressed using standard compression algorithms (e.g. GNU zip). Of course, we cannot simply compare the size of compressed SVG files to uncompressed bitmap formats as we should compare sizes when both formats are compressed. JPEG files, for example, are already compressed and so direct comparisons are meaningful. Most importantly, we should compare the size of files that are directly usable. SVG viewer applications (e.g. Web browsers, Inkscape) can directly read compressed SVG (.svgz) files, but they typically do not read compressed bitmap formats. As a result, the regular SVG files can be significantly smaller than comparable bitmap graphics and so faster to download and utilizing less bandwidth. Of course, the receiving application has to dynamically un-compress the content.

As just mentioned, an SVG file is a plain-text document. Since it is a grammar of XML, it is also highly structured. Being plain text means that it is relatively easy to create, view and edit using a text editor, and the highly structured nature of SVG makes it easy to modify programmatically. These features are essential to the approach described here: R is used to create the initial plot, we programmatically identify the elements in the SVG document that correspond to the components of the plot, and then augment the SVG document with additional information to create the interactivity and/or animation.

As a grammar of XML, SVG separates content and structure from presentation, e.g. the physical appearance of components in the presentation can be modified with a Cascading StyleSheet [7] without the need of changing or re-plotting the graphic. For example, someone who does not know R or even have the original data can change the contents of the CSS file that the SVG document uses, or substitute a different CSS file in order to, for example, change the color of points in the data region or the size of the line strokes for the axes labels. An additional feature of SVG is that elements of a plot can be grouped together and operated on as a single object. This makes it relatively easy to reuse visual objects and also to apply operations to them both programmatically and interactively. This is quite different from the style of programming available in traditional (grz) R graphics which draws on the canvas and does not work with graphical objects.

The SVG vocabulary provides support for adding interaction and animation declarations that are used when the SVG is displayed. However, one of the powerful aspects of SVG is that we can also combine SVG with JavaScript (also known as ECMAScript) [3]. This allows us to provide interaction and animation programmatically during the rendering of the SVG rather than declaratively through SVG elements. Both approaches work well in different circumstances. Several JavaScript functions are provided in the SVGAnnotation package to handle common cases of interaction and animation. For more specialized graphical displays, the creator of the annotated SVG document may need to write JavaScript code too and so work in a second language. For some users, this will be problematic, but the package does provide some facilities to aid in this step, e.g. making objects in R available to the JavaScript code. While switching between languages can be difficult, we should recognize that the plots are being displayed in a very different medium and use a language (JavaScript) that is very widely used for Web content.

The interactivity and animation described here are very different from what is available in more commonly used statistical graphics systems such as GGobi [GGobi], iPlots [34], or Mondrian [30]. Each of these provide an interactive environment for the purpose of exploratory visualization and are intended primarily for use in the data analysis phase. While one could in theory build similar systems in SVG, this would be quite unnatural. Instead, SVG is mostly used for creating both simple and very rich interactive presentation graphics that typically come at the end of the data analysis stage. Rather than providing general interactive features for data exploration, with SVG graphics, we create application-specific interactivity and often include graphical interfaces for that display, and even combine different media.

To get a sense of the possibilities for interactivity with SVG, we provide a relatively comprehensive set of examples that we have created using the facilities in SVGAnnotation. We begin with very simple examples that use high-level facilities in the package and proceed to more complex cases built using the utility functions also in the package. Some of these more advanced displays require a deeper understanding of how particular plots created in R are represented in SVG and an ability to write JavaScript.

The examples are intended to introduce the reader to the capabilities of SVG. They are also arranged to gradually move from high-level facilities to more technical details, i.e. they increase in complexity. The aim is to provide readers with sufficient concrete examples and accompanying code to develop SVG-based interactive displays themselves. When readers have worked through these examples, they will hopefully have the facilities to create SVG and their own customized displays.

Tool tips and hyperlinks are very simple, but effective, forms of interactivity. With hyperlinks, the user interacts with a plot by clicking on an active region, say an axis label or a point, and in response, the browser opens the referenced Web page. An example of this is shown in the scatter plot in Figure 1, “Hyperlinks on titles”. The mouse is over the title of the map, and the status bar at the bottom of the screen shows the URL of the USGS map of the South Pacific that will be loaded with a mouse click.

• Static
• Dynamic

This scatter plot was produced by a call to the plot() function in R. After the plot was created, a hyperlink was added to the title of the plot using the addLink() function in SVGAnnotation. When viewed in a browser, a mouse click on the title will lead to the browser opening up the url shown in the status bar of the screen shot. (This plot is adapted from [35].)

With tool tips, the user interacts with a plot by pausing the pointer over a portion of the plot, say an axis label or a point. This mouse-over action causes a small window to pop up with additional information. Figure 2, “ Tool tips on a hexbin plot ” shows an example where the mouse has been placed on an hexagonal bin in the plot and a tool tip consequently appeared to provide a count of the number of observations in that bin. Note that these forms of interactivity do not require R or JavaScript within the browser, but merely any SVG-compliant browser.

• Static
• Dynamic

The hexagonal-bin plot shown here was generated by a call to the hexbin() function. After the plot was created, the SVG file was then post-processed to add a tool tip to each of the shaded hexagonal regions so that when the mouse hovers over a hexagon, the number of observations in that bin appears in the tool tip.

It is also possible to link observations across sub-plots. For example, Figure 3, “Linked scatter plots” shows the mouse over a point in one of the plots. This mouse-over action causes that point and the corresponding point in the second plot to be colored red. When the mouse moves off the point, both points return to their original color(s). Another example found later in this paper demonstrates how to link across conditional plots, where the mouse-over action on a plot legend causes the corresponding groups of points to be highlighted in each of the panels (Figure 11, “ Linking a legend to a group of points in a conditional plot ”). This linking of points across plots uses reasonably generic JavaScript that is provided in the SVGAnnotation package.

SVG provides basic animation capabilities that can be used to animate R graphics. For example, it is possible to create animations similar in spirit to the well-known GapMinder animation (http://gapminder.org/world), where points move across a canvas. See Figure 4, “Scatter plot animation”. These simple animations are possible by simply adding SVG elements/commands to the SVG content generated by R. In other words, no JavaScript is needed to create the animation effects.

• Static
• Dynamic

This screen shot shows the scatter plot at the end of the animation. Each circle represents one country. Time is represented through the movement of the points from one decade to the next. The location of the circle corresponds to the pair (income, life expectancy) and the area of the circle is proportional to the size of the population. The animate() function in SVGAnnotation provides the basic functionality for this scatter plot animation. (Reloading the page will restart the animation).

The Carto:Net project [CartoNet] has made available a Graphical User Interface (GUI) library for SVG. For convenience, this library is distributed as part of the SVGAnnotation package. It can be used to add controls such as sliders, radio boxes, and choice menus to an SVG plot. These controls provide an interface for the viewer to have more complex interactions with the graphic. For example, in Figure 5, “A slider for choosing parameter values” the slider specifies the bandwidth used to smooth the data in the scatter plot on the left. When the viewer moves the slider, the corresponding smoothed curve is displayed in the left-hand plot, and the right-hand plot is updated to display the residuals from the newly selected fit. The interactivity of the GUI controls are provided via JavaScript functionality in Carto:Net. Additional JavaScript is required to perform the plot-specific functionality, i.e. to display the correct curve and residuals in the figure. We should note that R is not involved when the plot is being viewed and the different curves are being displayed. This is done entirely via SVG and JavaScript with fitted values precomputed within R and serialized to the JavaScript code.

An alternative to SVG GUI controls is to embed the SVG graphic in an (X)HTML page and use controls provided by an HTML form to control the plot. Again, JavaScript is required to respond to the user input via the HTML controls. The basic set of HTML UI controls is quite limited, so the author must either use JavaScript to provide the slider (e.g. using the YUI toolkit from Yahoo http://developer.yahoo.com/yui/) or change the interface to use one of the simpler controls.

A complication from embedding an SVG document within an (X)HTML document stems from the JavaScript code within the HTML code being separate from the code and objects within the SVG document. In this case, a simple extra step is necessary to access the SVG elements from the JavaScript code within the HTML document. An example is shown in Figure 6, “ SVG embedded within HTML links regions in a map to HTML tables. ”. The map of the United States presidential election results is embedded in an HTML <div> tag. When the viewer clicks on a state in the map, JavaScript located in the HTML document pulls up the state's summary information and dynamically places it in a table in the <div> above the map.

• Static
• Dynamic

This screen shot shows a canonical red-blue map of the results of US presidential election embedded within a <div> tag in an HTML page. Interactivity within the map is controlled via JavaScript located in the HTML page. When the viewer clicks on a state, the table displaying the summary of votes in the state is rendered within the light-grey <div> element above the map. Also, the individual county results are available below the map (not shown in this screen shot).

These six figures show the variety of interactivity possible with SVG. In the following sections we introduce the functionality available within SVGAnnotation to create these and other interactive graphics. The examples are chosen to demonstrate our philosophy behind creating interactivity with R and SVG. The package offers the R programmer a new mode of displaying R graphics in an interactive, dynamic manner on the Web.

Having seen the different capabilities of SVG, we now turn our attention to how a user can create these displays in R. In this section, we introduce several high-level functions from the SVGAnnotation package that make it easy to add interactivity to SVG plots. We briefly describe the main functions in Table 1, “ High-level functions for adding interactivity to SVG plots ” and explain the basic approach we take to create these graphical displays. In addition, we demonstrate how to use some of these functions with a few examples.

In order to produce SVG graphics in R (using the built-in graphics device), libcairo [18] must be installed when R is built. You can determine whether an R installation supports SVG with the expression capabilities()["cairo"]. If this yields TRUE, then the libcairo-based SVG support is present. Assuming this is the case, we create/open an SVG graphics device with a call to the svg() function and then issue R plotting commands to the SVG device as with any other graphics devices. We must remember to close the device with a call to dev.off() when the commands to generate the display are complete. For example,

svg("foo.svg")
plot(density(rnorm(100)), type = "l")
abline(v = 0, lty = 2, col = "red")
curve(dnorm(x), -3, 3, add = TRUE, col = "blue")
dev.off()

creates the file named foo.svg that contains the SVG that renders a smoothed density of 100 random normal observations.

The SVGAnnotation package provides a convenience layer to this process. The svgPlot() function opens the device, evaluates the code to create the plot(s), and then closes the device, all in a single function call. For example,

svgPlot({
         plot(density(rnorm(100)), type = "l")
         abline(v = 0, lty = 2, col = "red")
         curve(dnorm(x), -3, 3, add = TRUE, col = "blue")
        },
          "foo.svg")

performs the same function calls as in the above example. We recommend using svgPlot() when all the commands to generate the display are available as a single unit because svgPlot() also inserts the R code that generated the plot as meta-data into the SVG file and provides provenance and reflection information. This can be convenient for the programmer post-processing the resulting SVG. Even more important is the additional information it adds for lattice plots such as the number of panels, strips, conditioning variables, and levels, and details about the legend. These allow us to more easily and reliably identify the different SVG elements corresponding to the components of the R plot(s) we want to annotate.

An additional reason for using the svgPlot() function is that it can hide the use of a file. As shown below, often we want the SVG document generated by R's graphics commands as an XML tree and not written to a file. svgPlot() will return this tree if no file name is specified by the caller, e.g.

doc = svgPlot({
                plot(density(rnorm(100)), type = "l")
                abline(v = 0, lty = 2, col = "red")
                curve(dnorm(x), -3, 3, add = TRUE, col = "blue")
              })

The higher-level facilities in SVGAnnotation make it quite easy to add simple forms of interactivity to an SVG display. To add interactivity, we follow a three-step process.

Simple Interactivity: Tool tips and links

In this section we provide simple examples of how to use the high-level functions to add tool tips (Example 1, “Adding Tool Tips to Points and Labels” and hyperlinks (Example 2, “Adding Hyperlinks to a Plot Title”) to plots. The R user does not need to understand SVG to add these simple features to plots.

Example 1. Adding Tool Tips to Points and Labels

In this example, we demonstrate how to add tool tips to the SVG plot shown in Figure 7, “Tool tips for points in a scatter plot”. The figure shows one of the effects that we are attempting to create: when the mouse is over a point then a tool tip with additional information about that point appears.

• Static
• Dynamic

This screen shot shows a scatter plot where each point has a tool tip on it. The tool tips were added using the addToolTips() function in SVGAnnotation. When viewed in a browser, as the mouse passes over the point, information about the values of each variable for that observation is provided in a pop-up window. (Another screen shot of this plot is shown in Figure 1, “Hyperlinks on titles”.)

The first step is to make the plot using the SVG graphics device.

depth.col = gray.colors(100)[cut(quakes$depth, 100, label=FALSE)]
depth.ord = rev(order(quakes$depth))

doc = svgPlot(
 plot(lat ~ long, data = quakes[depth.ord, ],
      pch = 19, col = depth.col[depth.ord],
      xlab = "Longitude", ylab="Latitude",
      main = "Fiji Region Earthquakes") )

As noted earlier, the function svgPlot() is a wrapper for R's own svg() function. We did not specify a value for the file parameter for svgPlot() and as a result, the function returns the parsed XML/SVG tree, which we can then post-process and enhance. (This code is adapted from [35].)

The default operation for addToolTips() is to add tool tips on each of the points in a scatter plot. We simply pass the SVG document to addToolTips() along with the text to be displayed. For example, using the row names from the data frame is as simple as

addToolTips(doc, rownames(quakes[depth.ord, ]), addArea = 2)

If we wanted the tool tip to provide information about the value of each of the variables for that observation, we could do this with

addToolTips(doc, apply(quakes[depth.ord, ], 1, 
                        function(x)
                           paste(names(quakes), x, sep = " = ", 
                             collapse = ", ")), addArea = 2)

We can also use addToolTips() to provide tool tips on the axes labels. This time, since it is not the default operation, we need to pass the particular axes label nodes to be annotated, rather than the entire SVG document. We find these axes label nodes using another high-level function in SVGAnnotation, getAxesLabelNodes() . This function locates the nodes in the SVG document that correspond to the title and axes labels:

ax = getAxesLabelNodes(doc)

The first element returned is the title. We discard the title node, and call addToolTips() to place tool tips on just the axis nodes:

addToolTips(ax[-1], 
   c("Degrees east of the prime meridean", "Degrees south of the equator"), 
   addArea = 2)

The addToolTips() function will operate on any SVG element passed to it via the function's first argument.

Now that the SVG has been annotated, we save the modified document:

saveXML(doc, "quakes_tips.svg")

This document can now be opened in an SVG viewer (e.g. a Web browser) and the viewer can interact with it by mousing over the points and axes labels to read the tool tips that we have provided.

Example 2. Adding Hyperlinks to a Plot Title

We sometimes want to allow the viewer of a graphical display to click on a phrase or an individual point and jump to a different view or a Web page. SVG supports hyperlinks on elements so we can readily add this feature to R plots.

We continue with the plot that we annotated in Example 1, “Adding Tool Tips to Points and Labels” and add a hyper-link to the title. We add a feature to the plot that will allow viewers to click on the phrase “Fiji Region Earthquakes"” and have their Web browser display the USGS web page containing a map of recent earthquakes in the South Pacific. We have already seen that the title of the plot is in the first element of the return value from the call to getAxesLabelNodes() , which was saved in the R variable ax (see note below). We simply associate the target URL with this element via a call to addLink() as follows:

addAxesLinks(ax[[1]],
  "http://earthquake.usgs.gov/eqcenter/recenteqsww/Maps/
                                        region/S_Pacific.php")

Now, when the viewer clicks on the rectangular bounding box that encloses the title, the browser will open the USGS website.

Note

The parsed SVG document is a C-level structure, and the return value from xmlParse() is a reference to this structure. Further, the functions, such as getAxesLabelNodes() , return pointers to the nodes in this C-level structure. The consequence of this is that when we assign the return value from say getAxesLabelNodes() to an R object, we are not getting a new copy of the nodes. Hence, any modification to the returned value modifies the original parsed document. For example, in Example 2, “Adding Hyperlinks to a Plot Title” an assignment to the R variable ax modifies the axes label nodes in the C-level structure. This is an important distinction from the usual way R handles assignments. The call to saveXML() will save the modified, parsed document as an XML file.

	Note
	Currently, not all common plots in R are handled at a high-level as described in this section. Some may require low-level manipulation of the XML in the same manner we have illustrated and implemented within the examples in the next sections of this paper and in the SVGAnnotation package.

In this section we provide a brief overview of the commonly used XML elements/nodes in SVG and the basics of the drawing model. For more detailed information on SVG, readers should consult [1], and readers unfamiliar with XML should read the section called “Appendix: Basics of XML” or [5]. We also explore the basic layout of an SVG document created by the SVG device in R. In particular, we examine the SVG document produced from a simple call to plot() with two numeric vectors. If we wish to annotate other types of plots, i.e. one that is not covered by the high-level functions in SVGAnnotation, such as a ternary plot, then we will need to understand the structure of documents produced by the SVG device.

We include here a sample SVG file that will make our description of the SVG elements more concrete. This document was created manually (not with R) and is rendered in Figure 8, “Sample SVG”.

<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns = "http://www.w3.org/2000/svg" 
     xmlns:xlink = "http://www.w3.org/1999/xlink" 
     width = "300pt" height = "300pt" 
     viewBox = "0 0 300 300" version = "1.1">
 <defs>
  <g id="circles">
    <circle id = "greencirc" cx = "15" cy="15" r = "15" 
            fill = "lightgreen"/>
    <circle id = "pinkcirc" cx= "50" cy="50"  r = "15" fill = "pink"/>
  </g>
  <style type="text/css">  
   < ![CDATA[
   .recs {fill: rgb(50%,50%,50%); fill-opacity: 1; stroke: red;}
   ]] >
  </style> 
 </defs>
 <g id = "main">
    <rect x = "10" y = "20" width = "50" height = "100" 
          class = "recs"/>
    <use  x = "100" y = "100" xlink:href = "#circles"/>
    <use  x = "200" y = "50" xlink:href = "#circles" />
    <image xlink:href = "examples/pointer.jpg" 
           x = "70" y = "50" width = "10" height = "10"/>
    <path style = "fill: rgb(100, 149, 237);                    
            fill-opacity: 0.5;stroke-width: 0.75; 
            stroke-linecap: round; stroke-linejoin: round;             
            stroke: rgb(0%,0%,0%); stroke-opacity: 1;" 
        d = "M 102.8 174.6 L 102.8 174.6
             L 106.1 178.0 L 100.9 189.3 L 102.8 191.2 L 102.1 195.1 
             L 102.1 209.9 L 53.9 209.9 L 51.5 210.0 L 50.0 206.0 
             L 49.3 202.9 L 52.0 191.5 L 52.7 185.0 L 52.9 184.1 
             L 53.4 179.0 L 53.3 173.0 L 54.5 173.1 L 55.1 173.1 
             L 56.0 172.8 L 60.5 174.0 L 61.4 177.2 L 63.5 178.4 
             L 67.7 177.5 L 72.5 177.7 L 88.5 174.6 L 102.8 174.6
             Z" 
          id = "oregon"/>
    <text x = "110" y = "200" fill = "navy" font-size = "15">
        Oregon
    </text>
 </g>
</svg>

The image makes use of the most commonly used tags in SVG, which we describe below.

doc = svgPlot(
 plot(lat ~ long, data = quakes[depth.ord, ],
      pch = 19, col = depth.col[depth.ord],
      xlab = "Longitude", ylab="Latitude",
      main = "Fiji Region Earthquakes") )

root = xmlRoot(doc)

xmlSize(root)

[1] 3

xmlApply(root, xmlName)

$display
[1] "display"

$defs
[1] "defs"

$g
[1] "g"

names(root)

[1] "display"        "defs"           "g"

xmlValue(root[[2]])
[1] "plot(lat ~ long, data = quakes[depth.ord, ], pch = 19, 
 col = depth.col[depth.ord], \n    xlab = \"Longitude\",
 ylab = \"Latitude\", main = \"Fiji Region Earthquakes\")"

"/x:svg/x:g/*

kids = getNodeSet(doc, "/x:svg/x:g/*", "x") 
sapply(kids, xmlName)

[1] "rect" "g"    "g"    "g"

kids[[1]]

<rect x="0" y="0" width="504" height="504" 
  style="fill: rgb(100%,100%,100%); fill-opacity: 1; stroke: none;"/> 

root[[3]][[1]]
root[["g"]][["rect"]]
getNodeSet(doc, "/x:svg/x:g/x:rect", "x")

sapply(kids, xmlSize)

[1]    0 1000   25    3

dim(quakes)

[1] 1000  5

<path style="fill-rule: nonzero; 
   fill: rgb(90.196078%,90.196078%,90.196078%); 
   fill-opacity: 1;stroke-width: 0.75; stroke-linecap: round; 
   stroke-linejoin: round; stroke: rgb(90.196078%,90.196078%,90.196078%);
   stroke-opacity: 1;stroke-miterlimit: 10; "
   d="M 337.144531 191.292969 C 337.144531 194.894531 
        331.746094 194.894531 ...  " /> 

getNodeSet(doc, "/x:svg/x:g/x:g[3]/*[last()]", "x")

[[1]]
<g style="fill: rgb(0%,0%,0%); fill-opacity: 1;" type="axis-label">
  <use xlink:href="#glyph1-7" x="14.398438" y="266.152344"/>
  <use xlink:href="#glyph1-8" x="14.398438" y="259.478516"/>
  <use xlink:href="#glyph1-9" x="14.398438" y="252.804688"/>
  <use xlink:href="#glyph1-10" x="14.398438" y="249.470703"/>
  <use xlink:href="#glyph1-9" x="14.398438" y="246.804688"/>
  <use xlink:href="#glyph1-11" x="14.398438" y="243.470703"/>
  <use xlink:href="#glyph1-12" x="14.398438" y="236.796875"/>
  <use xlink:href="#glyph1-13" x="14.398438" y="230.123047"/>
</g> 

attr(,"class")
[1] "XMLNodeSet"

<symbol overflow="visible" id="glyph1-8">
<path style="stroke: none;" d="M -1.253906 -1.1875 
C -1.023438 -1.1875 -0.84375 -1.269531 -0.710938 -1.4375 
C -0.578125 -1.605469 -0.515625 -1.800781 -0.515625 -2.03125 
C -0.515625 -2.308594 -0.578125 -2.578125 -0.707031 -2.839844 
...
C -2.492188 -1.042969 -2.636719 -1.398438 -2.695312 -1.839844 
Z M -4.820312 -2.449219 "/>
</symbol>

addToolTips(doc, apply(quakes[depth.ord, ], 1, function(x)
            paste(names(quakes), x, sep = " = ", collapse = ", ")),
            addArea = 2)

<path style="fill-rule: nonzero; 
   fill: rgb(90.196078%,90.196078%,90.196078%); 
   fill-opacity: 1;stroke-width: 0.75; stroke-linecap: round; 
   stroke-linejoin: round; stroke: rgb(90.196078%,90.196078%,90.196078%);
   stroke-opacity: 1;stroke-miterlimit: 10; "
   d="M 337.144531 191.292969 C 337.144531 194.894531 
        331.746094 194.894531 ...  " 
   type="plot-point">
 <title>lat = -20.32, long = 180.88, depth = 680, mag = 4.2, 
         stations = 22
 </title>
</path> 

The SVGAnnotation package provides facilities for identifying elements of the SVG document that correspond to particular parts of plots. These assist developers in creating new high-level functions for annotating the output from “non-standard” plotting functions in R. We demonstrate how one might add hypertext references to polygons in a map (Example 3, “Adding Hyperlinks to Polygons”), and explore how to add tool tips to the hexagonal regions in a hexbin plot (Example 4, “Interactive Hexagonal Bin Plots”) used for displaying a scatter plot with many observations that would ordinarily overlap [21]. These examples demonstrate the use of some of the functions that are briefly described in Table 2, “ Intermediate-level functions for working with SVG elements ”.

In the section called “The SVG Grammar”, we determined the structure of an SVG document generated via libcairo from a call to the plot() function in R. To do this, we used information about the data being plotted. For example, knowing the number of observations helped us find the SVG nodes corresponding to the points. We matched the number of rows in the data frame against the number of elements in various parts of the SVG document. In this section, we continue with this approach of discovering which elements in the generated SVG correspond to particular components of a map and a hexbin plot. In addition to examining the R variable that is being plotted, we also examine the graphics object returned from the call to the R plotting function in order to uncover the structure in the corresponding SVG image. In the following example, we match the length of the vector of polygon names returned from a call to map() against the number of elements in the SVG rendition of the map to find the elements corresponding to the conceptual regions of the map, i.e. the polygons. This is a deterministic process that need only be done once because the SVG output for a particular type of plot has a very regular structure. Although regular, the structure is not a formal one that allows us to immediately identify the SVG elements corresponding to R components. The SVGAnnotation package does most of this automatically. We are describing it here to illustrate the underlying mechanism and approach so it is clearly understood and can be adapted for new types of plots.

Example 3. Adding Hyperlinks to Polygons

In this example, we create a popular map of the USA where we color the states red or blue according to whether McCain or Obama received the majority of votes cast in the 2008 presidential election (see Figure 10, “Hyperlinks on regions of a map.”. These data were “scraped” from the New York Times Web Site http://elections.nytimes.com/2008/results/president/map.html.

• Static
• Dynamic

The map in the screen shot shown here was produced by the map() function in the maps package [19]. The SVG file was then post-processed to add hyperlinks to the state regions using the addLink() function in SVGAnnotation. When the viewer clicks on a state, the browser links to the corresponding state's Web page of election results on the New York Times site, e.g. http://elections.nytimes.com/2008/results/states/california. We might also add a hyperlink for the title of the R plot, "Election 2008". We could similarly add links on axes labels on regular plots.

We use the maps package to draw the map.

doc = svgPlot({
                map('state', fill = TRUE, col = stateColors)
                title("Election 2008")
              })

We need to determine where the polygon regions for the states are located in the SVG document so that we can add hyperlinks to them. While getPlotPoints() will find the SVG polygon elements for us, we will explore how we can find them manually. We use an XPath expression, to find all the <path> nodes in the document. As explained in the section called “The SVG display for an R plot”, the paths will be located within a <g> element two layers beneath the root node. The following XPath expression locates any <path> that has two consecutive <g> ancestors within the hierarchy from the node to the root.

polygonsPaths = getNodeSet(doc, "/svg:svg/svg:g/svg:g//svg:path", "svg")

We found 63 <path> elements,

length(polygonPaths)

[1] 63

which is the same number of polygons that map() uses in drawing the state map for the United States:

mapStateNames = map("state", namesonly = TRUE, plot = FALSE)
length(mapStateNames)

[1] 63

Note that we made this comparison by examining the value returned by the call to map() . The order here corresponds to the order in which the polygons were plotted in R.

Now that we have found the state polygons in the SVG file, we are ready to add links to them. As in Example 2, “Adding Hyperlinks to a Plot Title”, we use the function addLink() , passing it the XML elements corresponding to the polygons. We create the vector of target URLs on the New York Times web site as follows, stripping the names returned by map() to get just the state part and appending these to the relevant base URL and replacing any blank in a state name with a hyphen:

mapStateNames = gsub(":.*$", "", mapStateNames)
mapStateNames = gsub("[[:blank:]]", "-", mapStateNames)
urls = paste("http://elections.nytimes.com/2008/results/states/",
              mapStateNames, ".html", sep = "")

Then we add the links:

addLink(polygonPaths, urls, css = character())

When the saved document is viewed in a Web browser, or a dedicated SVG viewer such as batik [23], a mouse click on a state will display the state's page on the New York Times Website in the browser.

We should note that, if we had not filled the polygons with color, then the interiors would not be explicitly drawn and therefore, only the boundaries (i.e. the paths) would be active. This means that the interiors of the states would not respond to a mouse click. Also, the map function draws (and returns) a different number of polygons if we fill the polygons or not. As a result, the computations would be very slightly different.

Although we have completed the task of adding links to the polygon paths, let's see how we can use the function getPlotPoints() , one of the intermediate-level facilities in the package for handling SVG nodes, to find the polygons:

ptz = getPlotPoints(doc)
length(ptz)

[1] 63

all(sapply(ptz, xmlName) == "path")

[1] TRUE

We see that getPlotPoints() retrieves as many “points” as there are polygons. We can infer that this function does indeed locate the regions in an SVG map. Indeed, these high-level functions in SVGAnnotation are intelligent enough to handle many diverse types of plots and should be used in preference to low-level processing of nodes with getNodeSet() when possible.

We next look at another slightly non-standard plot where we examine the R graphics object returned from the call to hexbin() to infer the structure of the SVG document for a hexbin plot. Specifically, we determine the location of the elements in the SVG file that correspond to the hexagonal bins in the display.

library(hexbin)
hbin = hexbin(Occupancy, Flow)

length(hbin@count)

[1] 281

doc = svgPlot(plot(hbin, main = "Loop Detector on I-5"))

reg = getPlotRegionNodes(doc)
sapply(reg, xmlSize)

[1] 281

hexbins = xmlChildren(reg[[1]])
sapply(seq(along = hexbins),
       function(i) {
         addToolTips(hexbins[[i]], 
                     paste("Count: ", hbin@count[i]), addArea = 2)
       })

So far in this paper, we have added SVG in the post-processing stage to create interactive effects with tooltips and hyperlinks. Here, with the help of JavaScript, we can create plots with more complex interactivity. JavaScript can be added to an SVG display so that we can programmatically change the value of an attribute of an element while viewing it. (For a brief introduction to JavaScript see the section called “Appendix: Basics of JavaScript”). In particular, we show how to change the attribute of an element in response to a mouse event, e.g. we can change an element's color, whether it is visible or hidden, its location, or its size. A mouse action can initiate the changing of SVG “on the fly”, or dynamically, to allow a rich set of user interactions with the plot.

In our first example we create a display that uses color to link points across multiple plots, i.e. when the mouse moves over a point in one plot, then the color changes for that point and the points for the corresponding observations in the other plots. This functionality is provided via the high-level function linkPlots() . In addition to providing an example of how to use the high-level functionality, we demonstrate the lower-level details of how to post-process the SVG document to add both annotations and JavaScript in order to enable this sort of interactivity. An important part of the post-processing stage involves adding unique identifiers to all the nodes that the JavaScript code might access and modify. These identifiers allow JavaScript to access the nodes by name rather than contextual position. The post-processing also frequently includes adding additional attributes to elements to store original values of attributes that may be dynamically modified so that we can revert these temporary changes. We use this approach in our example that demonstrates how to create a display that links observations across panels in a lattice plot.

doc = svgPlot({par(mfrow = c(1,2))
    plot(Murder ~ UrbanPop, USArrests, main="", cex = 1.4)
    plot(Rape ~ UrbanPop, USArrests, main = "", cex = 1.4)
    }, 
  width = 14, height = 7)

linkPlots(doc)
saveXML(doc, "USArrests_linked.svg")

<path style="stroke-width:0.75; ... " 
   d="M 260.417969 72.800781 C 260.417969 77.839844 252.855469 ..." 
   id="plot1-10" 
   onmouseover="color_point(evt, 10 , 2 , 'red' )" 
   onmouseout="reset_color(evt, 10 , 2 )" 
   fill="none" originalFill="none"/>

groups = sort(unique(mtcars$gear))
labels = paste(groups, "gears", sep = " ")

doc = svgPlot(xyplot(mpg ~ disp| am, groups = cyl, data = cars,
              key = simpleKey(text = labels, 
                              columns= length(labels), 
                              points= FALSE)))

panels = getPlotRegionNodes(doc)
points = unlist(lapply(panels, xmlChildren), recursive = FALSE)

ids = by(cars, list(cars$gear, cars$am),
         function(x) paste(as.integer(x$am), x$gear,
                           1:nrow(x), sep = "-"))

uids = unlist(ids)
mapply(function(node, id)
        addAttributes(node, id = id),
        points, uids)

nodes = getNodeSet(doc, "/x:svg/x:g/x:g", "x")
nodes = nodes[-(1:(length(nodes) - length(unique(cars$gear))))]

counts = table(cars$am, cars$gear)
counts

       
           3  4  5
automatic 15  4  0
manual     0  8  5

sapply(seq(along = 1:ncol(counts)),
       function(i) {
        cts = paste("[", paste(counts[,i], collapse = ", "), "]", 
                      sep = "")
        addAttributes(nodes[[i]],
             onmouseover = paste("highlight(", groups[i], ",", 
                                 cts, ", true)"),
             onmouseout =  paste("highlight(", groups[i], ",", 
                                 cts, ", false)")
           )
       })

addECMAScripts(doc, "multiLegend.js")
saveXML(doc, "mt_lattice.svg")

function highlight(group, pointCounts, status)
{
    var el;
    var i, numPanels = pointCounts.length;

     for(panel = 1; panel <= numPanels; panel++) {
        for(i = 1; i <= pointCounts[panel-1]; i++) {
            var id = panel + "-"+ group + "-" + i;
            el = document.getElementById(id);
            if(el == null) {
                alert("can't find element " + id)
                return(1);
            }
            highlightPoint(el, status);
        }
    }
 }

function highlightPoint(el, status)
{
  var old = el.getAttribute('original-style');

  if(status && old == null)
      el.setAttribute('original-style', el.getAttribute('style'));

  if(status) {
      var cur = el.getAttribute('style');
      var tmp = cur.replace(/fill: [^;]+/, "fill: black");
      var tmp = tmp.replace(/stroke-width: [^;]+/, "stroke-width: 2");
      el.setAttribute('style', tmp);
  }
  else 
      el.setAttribute('style', old);
}

In this section, we use a different approach to creating interactivity with JavaScript. In the section called “Mouse events and JavaScript” we used JavaScript to simply alter the attributes of existing elements. That is, all of the computations on the data were done in advance, in R, in either the plotting stage or the annotation stage, and the JavaScript functions simply changed and reset attributes. Here, in the annotation stage, we place R objects in the SVG document as JavaScript variables, and in the viewing stage, we use JavaScript and these variables to create new shapes in the display. We provide two examples. In the first, we draw line segments on a scatter plot to connect a point to its nearest neighbors. The information as to which points are nearest others is calculated in R and placed in the SVG document as JavaScript variables. Now drawing is done in two places, in R via the plotting routines, and in JavaScript at the time the document is viewed (and R is no longer available). If we had made this plot using the earlier approach, we would have drawn all possible line segments in R, hidden them within the plot, and the JavaScript would respond to mouse-over and out events by modifying element attributes in order to show and hide the line segments. But in the approach here, we draw new lines as they are needed and then discard them.

doc = svgPlot(plot(mpg ~ wt, mtcars, 
                   main = "Motor Trend Car Road Tests",
                   pch=19, col= c("green", "blue")[(am+1)]))

ptz = getPlotPoints(doc, simplify = FALSE)[[1]]
sapply(seq(along = ptz), 
        function(i)
          addAttributes(ptz[[i]], id = i - 1)))

sapply(seq(along = ptz),
        function(i) {
           addAttributes(ptz[[i]],
                  onmouseover = "showNeighbors(evt, k, neighbors)", 
                  onmouseout = "hideLines(evt)")
        })

DD = as.matrix(dist(mtcars[, c("mpg", "wt")]))
D = t(apply(DD, 1, order)) - 1

dimnames(D) = list(NULL, NULL)
addECMAScripts(doc, "knn.js", TRUE, neighbors = D)

function addLines(obj, neighbors, numNeighbors)
{
    var x, y, x1, y1;

    var tmp = obj.getBBox();
    x = tmp.x + tmp.width/2;
    y = tmp.y + tmp.height/2;

    lineGroup = document.createElementNS(svgNS, "g");
    obj.parentNode.appendChild(lineGroup);
    var ids = obj.getAttribute('id') + ": ";
    for(var i = 1; i <= numNeighbors ; i++) {
        var target;
        target = document.getElementById(neighbors[i]);
        ids = ids + " " + neighbors[i];

        tmp = target.getBBox();
        x1 = tmp.x + tmp.width/2;
        y1 = tmp.y + tmp.height/2;

        var line = document.createElementNS(svgNS, "line");
        line.setAttribute('x1', x);
        line.setAttribute('y1', y);
        line.setAttribute('x2', x1);
        line.setAttribute('y2', y1);
        line.setAttribute('style', "fill: red; stroke: red;");

        line.setAttribute('class', "neighborLine");
        lineGroup.appendChild(line);
    }
    window.status = ids;
}

function hideLines()
{
  if(typeof lineGroup != "undefined") {
      lineGroup.parentNode.removeChild(lineGroup);
      lineGroup = document.createElementNS(svgNS, "g");
  }
}

An alternative approach to the above example is to add, in the annotation stage, all of the nearest neighbor lines for all of the points. We would set the visibility style attribute to "hidden" so these line segments would not be displayed when the document is loaded by the viewer. Then, a point's onmouseover function call would identify the appropriate line segments emanating from the point to its nearest neighbors and change their visibility attribute to "visible". Similarly, the onmouseout event would change them back to “hidden”. This alternative approach is similar in spirit to those examples in the section called “Mouse events and JavaScript”, i.e. JavaScript functions do little other than change attribute values on nodes in the document. There are run-time benefits because we don't have to create the lines each time the user moves over a point. However, there are many more lines in the display and the loading of the SVG file may be slower. This trade-off involves where we do the computations. The approach that leaves the line creation to JavaScript also generalizes to allow dynamic specification of the number of nearest neighbors, e.g. with a slider or HTML spin box.

library(graph)
library(Rgraphviz)
set.seed(123)
V = letters[1:10]
M = 1:4
g1 = randomGraph(V, M, 0.8)

layout2pi = agopen(g1, layoutType = "twopi", name = "bob")
doc = svgPlot(plot(layout2pi))

top = xmlRoot(doc)[["g"]][["g"]]

table(names(top))
   g path 
  10   55 

ids = addGraphIds(doc, layout2pi)

cat(toJSON(getEdgeInfo(rGraph)))

[ ["edge:a-c","edge:a-d","edge:a-e","edge:a-g","edge:a-h","edge:a-i",
   "edge:a-j","edge:a-b","edge:a-f"],
["edge:b-a","edge:b-c","edge:b-d","edge:b-e","edge:b-f","edge:b-g",
   "edge:b-h","edge:b-i","edge:b-j"],
...
["edge:j-a","edge:j-c","edge:j-d","edge:j-e","edge:j-g","edge:j-h",
   "edge:j-i","edge:j-b","edge:j-f"] ]

function highlightEdges(evt, row, color)
{
  var labels = edgeTable[row];
  if(undefined(color))
    color = "black";

     /* highlight the node. */
  evt.target.setAttribute('style', 'fill: ' + "red");

     /* highlight this node's edges */
  for(var i = 0; i < labels.length; i++) {
      var el = document.getElementById(labels[i]);
      setEdgeStyle(el, "stroke: " + color + add);
  }

      /* hide the other edges */
  labels = edgeDiff[row];
  var stroke = "lightgray";
  for(var i = 0 ; i < labels.length; i++) {
    var el = document.getElementById(labels[i]);
    setEdgeStyle(el, 'stroke: ' + stroke + add);
  }
}

ids = addGraphIds(doc, layout2pi)
els = getNodeElements(doc)  # get SVG elements for graph nodes

sapply(seq(along = els), 
    function(i) 
      addAttributes(els[[i]], 
       onmouseover = paste("highlightEdges(evt, ", i - 1, ", 'red');"),
       onmouseout = paste("highlightEdges(evt, ", i - 1, ");")))

  # Setup "hiding" the other edges when we highlight these ones.

info = getEdgeInfo(rGraph) # from the graph package.
otherEdges = lapply(info,
                     function(x) 
                       setdiff(ids$edgeIds, x))

addECMAScripts(doc, "highlightEdges.js", TRUE,
               edgeTable = info, edgeDiff = otherEdges)

saveXML(doc, docName(doc))

SVG supports two types of animation: declarative, which solely uses SVG facilities; and scripted, which relies on JavaScript. In this section, the focus is on the declarative approach, however, we present examples of both. The SVG animation facilities make it quite easy to produce animations similar to GapMinder, by simply annotating a scatter plot display with animation elements.

The basic concept of a “pure” SVG animation is that animation elements provide directions on how to move an object, or group of objects, and how to change the shape or appearance/style of an object. These animation elements are added as children of the object that is being animated. The animation tag names are <animate>, <animateMotion>, <animateTransform>, <animateColor>, and <set>. These tags act on a particular attribute of the parent object. For example, the <animateTransform> tag can be used to change the width attribute, causing the object to grow or shrink, or it can change the visibility attribute in order to make an object become hidden or visible. As another example, with <animateMotion>, we can specify a new location for the object, which causes the object to move to a new position on the display.

To get an idea as to how this works, the following SVG animation takes two seconds to move a circle from its original location at the time of loading to a new location and simultaneously shrink the circle from a radius of 5.4 to 3.

<circle x="95.1" y="369.8" r="5.4" 
        style="fill-rule: nonzero; 
               fill: rgb(100%,0%,0%); ...">
    <animateMotion id="move1" from="95.1, 369.8" to="66.7, 412.7" 
                   fill="freeze" dur="2s" begin="0s"/>
    <animateTransform attributeName="transform" type="scale" 
                   fill="freeze" to="3" dur="2s" begin="0s"/>
</circle>

This mini-animation is the building-block for the scatter-plot animation shown in Figure 4, “Scatter plot animation”. There, each point represents a country, and the x and y locations correspond to the country's average life expectancy and income for a particular decade. As the points move, they grow or shrink according to the change in population size from one decade to the next. The animation is described in more detail in Example 9, “Animating Scatter Plots through snapshots in time”.

Notice that the movement of the circle and the changing of its size are coordinated by specifying that both animations are to begin at the same time (begin is at 0 seconds, i.e. at load time) and take the same amount of time (dur is 2 seconds). With the <animateMotion>, it is also possible to specify the path the circle would take in traveling from one location to the other. Any animation element requires a dur attribute to specify its duration. The value can be provided in seconds, e.g. dur="10s", or minutes, e.g. dur="2min". It is also possible to use clock values, e.g. dur="2:10" for 2 minutes and 10 seconds. The SVG clock starts ticking when the document has completed loading.

In addition to specifying the duration of an animation, it is also possible to specify when the animation is to begin or end. The values of these attributes can be absolute values, as with dur, or they can be relative to the start or end of another animation. For example, if we change the begin value in our <animateTransform> to "move1.end+3s", then the circle would start shrinking 3 seconds after it finished moving to its new location, i.e. 3 seconds after the animation corresponding to the animation element with an id attribute value of "move1" ends. This can be useful when synchronizing parts of an animation.

The <set> element behaves somewhat differently in that it is used to change attribute values such as fill. For example, the color of the circle could be changed when it reaches its new location by embedding the following element as a child of the <circle> as follows:

<set attributeName="fill" fill = "freeze" 
     attributeType = "CSS"  to = "#FFDB00FF" 
     begin = "move1.end"/>

The attributeName specifies which attribute on the parent node is to be “animated”. The to attribute indicates the new color of the circle. The change of color begins when the circle has finished moving. The fill attribute on the <set> tag is not to be confused with the fill attribute of the circle. The <set> tag's fill attribute refers to what is to happen at the end of the animation; the value of "freeze" indicates that the final value should be kept. Without it, the attribute being animated would return to its original value, i.e. the color would change back to the color before the animation started.

One additional point to note is that the attributeType attribute in the <set> element is used to indicate where the attribute being changed can be found. That is, a value of "CSS" means that the fill color is located in the style attribute of <circle>. If the circle had specified the value of its fill color in a presentation attribute, then we would have given the attributeType value as "XML".

      yr        country longevity     income population
1   1900      Argentina    39.700  4708.2323    6584000
2   1900      Australia    63.220  6740.9394    4278000
3   1900        Austria    42.000  5163.9268    6550000
4   1900     Bangladesh    22.000   794.8383   31786000
5   1900        Belgium    51.110  4746.9662    7478000
6   1900         Brazil    32.900   705.4758   21754000
7   1900       Bulgaria    43.300  1578.9537    4000000
...
390 2000    Netherlands    80.000 35653.3938   16491461
391 2000         Norway    80.550 48264.6727    4610820
392 2000           Peru    69.906  6875.5102   28302603
393 2000    Philippines    70.303  3030.8802   89468677
394 2000       Portugal    78.920 20149.0828   10605870
395 2000 United Kingdom    78.471 32334.5334   60609153
396 2000  United States    77.890 42445.7000  298444215

doc = svgPlot( {
  plot(longevity ~ income, 
    subset(gapM, yr == 1900 & country %in% ctry),
    pch = 21, col = colsB, bg = colsI,
    xlab = "Income", ylab = "Life Expectancy",
    axes = FALSE,
    xlim = c(-400, 50000), ylim = c(20, 85) )
  box()
  y.at = seq(20, 85, by = 5)
  x.at = c(200, 400, 1000, 2000, 4000, 10000, 20000, 40000)
  axis(1, at = x.at, labels = formatC(x.at, big.mark = ",", 
       format = "d") )
  axis(2, at = y.at, labels = formatC(y.at) )
  abline(h = y.at, col="gray",  lty = 3)
  abline(v = x.at, col="gray",  lty = 3)
  legend(35000, 40, longCont, col = colB, fill = colB, 
         bty = "n", cex = 0.75 )
  })

 addToolTips(doc, 
   as.character(gapM$country[gapM$yr == 1900 & gapM$country %in% ctry]))

animate(doc, 
    data = gapM[gapM$country %in% ctry, c("income", "longevity")], 
    which = gapM$yr[gapM$country %in% ctry],
    dropFirst = TRUE,
    labels = seq(1900, length = 11, by = 10),
    begin = 0, interval = 3,  
    radii = radL[ctry])

rect = getBoundingBox(plotRegion)

transformX = function(vals, xlim, rect) {
     (vals - xlim[1]) * 
       (rect[2, 1]- rect[1, 1])/(xlim[2] - xlim[1])  + 
     rect[1, 1]
  }

animationHandle = setInterval("animationStep(polyIds, stateResultsByYear, 
   yearLabels, polyStateNames)", Interval);

<svg xmlns="http://www.w3.org/2000/svg"
     xmlns:xlink="http://www.w3.org/1999/xlink"
     width="504pt" height="504pt" viewBox="0 0 504 504"
     version="1.1" onload="init(evt)">

 
var animationHandle; 
function init(evt) { 
...  
animationHandle=  setInterval("animationStep(polyIds,
       stateResultsByYear, yearLabels, polyStateNames)", Interval);
}

library(maps)
doc = svgPlot({
        m <- map('state', fill = TRUE, col = stateResultsByYear[[1]])
        title(names(stateResultsByYear)[1])
        text(m$range[1] + 3, m$range[3] + 1, "Start", col = "green")
      })

labels = getAxesLabelNodes(doc)

title = asTextNode(labels[[1]][[1]], "1900")

xmlAttrs(title) = c(id = "title")

start = asTextNode(labels[[2]][[1]], "Start")
xmlAttrs(start) = c(id = "Start", onclick = "toggleAnimation(evt)")

addToolTips(labels[[2]], "Start or pause the animation")
addCSS(doc)

pts = getPlotPoints(doc)
mapply(function(node, id)
            xmlAttrs(node) = c(id = id),
        pts, m$names)

addToolTips(pts, m$names)

addECMAScripts(doc, "animateElectionMap.js",
                 stateResultsByYear = stateResultsByYear, 
                 yearLabels = names(stateResultsByYear),
                 polyIds = m$names,
                 polyStateNames = polyStateNames, 
               insertJS = FALSE)

convertCSSStylesToSVG(pts)

saveXML(doc, "exJSAnimateElectionMap.svg")

var animationHandle = null;
var currentYear = 0;
var Interval = 600;

function animationStep(ids, colors, yearLabels, stateNames)
{
  currentYear++;

  if(currentYear >= yearLabels.length) {
     var el = document.getElementById("Start");
     setTextValue(el, "Start");
     clearInterval(animationHandle);
     animationHandle = null;
     return;
  }

    displayYear(currentYear, ids, colors, yearLabels, stateNames);
}

function displayYear(year, ids, colors, yearLabels, stateNames)
{
  for(var i = 0; i < ids.length; i++) {
     var el = document.getElementById(ids[i]);
        /* Lookup the year by name. Then within the year, look up
           the state, using the actual name not the polygon id. */
     var col = colors[yearLabels[year]][ stateNames[ i ] ] ;
     if(el && col)
        el.setAttribute('style', 'fill: ' + col);
  }

  var title = document.getElementById('title');
  setTextValue(title, yearLabels[year]);
}

function toggleAnimation(evt)
{
 var label;
 if(animationHandle) {
   clearInterval(animationHandle);
   animationHandle = null;
   label = currentYear > 0 ? "Restart" : "Start";
 } else {
   animationHandle= setInterval("animationStep(polyIds, 
         stateResultsByYear, yearLabels, polyStateNames)", Interval);
   currentYear = 0;
   displayYear(currentYear, polyIds, stateResultsByYear, 
               yearLabels, polyStateNames);
   label = "Pause";
}

 var start = document.getElementById('Start');
 setTextValue(start, label);
}

function setTextValue(node, val)
{
 node.firstChild.data = val;
}

In Example 10, “Animation with JavaScript & SVG”, we added a colored rectangle with the text “Start” to act as a button, where clicking on this region in the plot started an animation. In this section, we extend this idea and demonstrate how to provide interactivity through user controls, such as buttons, check boxes, and sliders that are drawn on the display using SVG & JavaScript rather than R. The Carto:Net community [CartoNet] has developed an open source library of SVG graphical user interface (GUI) controls to facilitate interactivity in SVG documents. The library consists of JavaScript functions to build the controls as SVG elements and respond to user interaction. This library is available from http://carto.net/ and is also distributed with the SVGAnnotation package, for convenience. It includes controls such as a check box, radio button, button, slider, text box, and selection menu that are rendered using native SVG elements and are quite different from their JavaScript equivalents.

By using these SVG GUI components, we can create applications that have rich user interfaces. An alternative approach is to embed the SVG graphic in an HTML document and control it through buttons and boxes in an HTML form (we show how to do this in the section called “Interfacing with (X)HTML”). With SVG, there is the potential to design unique, sophisticated GUI elements, such as sliders, dial knobs, and color choosers. Another potentially useful feature of SVG-based GUI components is that they can be rendered with SVG filters and transformations, e.g. at an angle or different filters (e.g. Gaussian blurring), or even animated. The main disadvantage is complexity. SVG GUI elements are somewhat more complex to use in programs than the “built-in” HTML form elements. Fortunately, the Carto:Net library offers a variety of GUI elements that can be easily embedded in the document.

In this section, we provide examples of how to use two of these GUI controls, a slider and check box. The first example adds a slider to a display in order to give the viewer control of a smoothing parameter for a fitted curve. The second example uses check boxes to add and remove groups of data (time series) from a plot.

Although the GUI control is being drawn with JavaScript commands, the basic approach to annotating the SVG remains essentially the same. The annotation stage now typically requires the following additional tasks:

addSlider =
function(doc, onload, javascript,
          id = "slider", svg = NULL,
          defaultJavascripts = c("mapApp.js",
                                 "helper_functions.js", "slider.js"),
          side = "bottom", ...)

svg = xmlRoot(doc)

addSlider(doc, svg = svg,
          onload = sprintf("init(evt, %d);", max(lambdas)),
          javascript = "linkedSmoother.js", id = "slider-lambda")

saveXML(doc, docName(doc))

var cur_lambda = 2;

function init(evt, maxLambda) {
   var sliderStyles = {"stroke" : "blue", "stroke-width" : 3};
   var invisSliderWidth = 15;
   new slider("lambda", "slider-lambda", 
               100, 510, 2, 475, 510, maxLambda, 2,
                sliderStyles, invisSliderWidth, "sliderSymbol",
                setLambda, false);
}

var slider = new slider(id, parentNode, x1, y1, value1, x2, y2, value2,
                        startVal, sliderStyles, invisSliderWidth,
                        sliderSymb, functionToCall, mouseMoveBool);

 
function setLambda(evType, group,val) 
{ 
     if(Math.floor(val) == cur_lambda) return(0); 
     setVisibility(cur_lambda, 'hidden');
     cur_lambda = Math.floor(val); 
     setVisibility(cur_lambda, 'visible'); 
} 

function setVisibility(lambda, state)
{
       var el;
       lambda = Math.floor(lambda);
       el = document.getElementById("curve-lambda-" + lambda);
       el.setAttribute('visibility', state);

       el = document.getElementById("residual-group-" + lambda);
       if(el) {
            el.setAttribute('visibility', state);
            return(0);
       }
}

Check boxes for toggling elements in a plot

We can use a similar approach to create interactivity with other SVG GUI controls offered in Carto:Net. We provide one additional example involving check boxes, for users unfamiliar with event handling. The check boxes in Carto:Net support toggle events, i.e. when a check box is checked or unchecked then a user-supplied function is called to perform some action. For example, in Example 12, “Showing and hiding currency exchange series with check boxes”, several time series are overlaid on a plot and made visible or invisible according to whether or not a corresponding check box is checked or not. That is, when a check box is toggled, this event then triggers a function call to change the visibility attribute of the associated times series.

The SVG document needs to be modified in the same way we did for the slider so as to include the check box GUI controls. In particular, the document should have an empty group <g> that will hold the elements for the check boxes and their labels. This needs to be added with a unique id to the appropriate place in the document; the checkBox JavaScript object needs to be initialized via JavaScript in the onload attribute on the root element; and the JavaScript code from the files helper_functions.js, timer.js and check box_and_radiobutton.js must be included, either by reference or by content.

The radioShowHide() function in R sets up a group of check boxes for toggling on and off curves in a plot. Once the initial SVG plot has been made, radioShowHide() post-processes the SVG in the annotation stage. This function handles all of the setup. Similar to the slider, radioShowHide() expands the viewing area to make room for drawing the check boxes; sets up the drawing areas for the check boxes; adds to the document the initialization script that creates the JavaScript check box objects when the document is loaded in the browser; and includes the JavaScript functions provided by Carto:Net that respond to the viewer actions and the application specific JavaScript functions that change the graphical display in response to viewers actions.

The function signature/declaration for the radioShowHide() function provides the information needed to perform these tasks:

radioShowHide =
function(doc, insertScripts = TRUE, within = FALSE, group = FALSE,
          labels = paste("Series", seq(length = numSeries)),
          extraWidth = 15 * (max(nchar(labels)) + 1),
          save = !is(doc, "XMLInternalDocument"),
          id.prefix = "series",
          checkboxCallback = if(is.na(within)) "togglePanel"
                             else "toggle",
          jscripts = c("helper_functions.js", "timer.js", 
                       "checkbox_and_radiobutton.js", 
                       "hideSVGElements.js"),
          numPanels = 1)

Briefly, doc specifies the SVG document to be annotated; within indicates whether a regular plot (FALSE) or matplot (TRUE) call was used to create the plot, which helps in finding the series; group allow the series to be matched up across lattice panels so that a series can be toggled on and off in all panels; labels contains the text labels for the check boxes; and checkboxCallback holds the JavaScript for the call back function.

Example 12. Showing and hiding currency exchange series with check boxes

In this example, we create an interactive time series plot, where several times series curves are super-imposed on the same plot and check boxes along side the plot are used to toggle the display of the series on and off (see Figure 14, “Togglable Exchange Rate Display”). The check boxes are ordered according to the median value of the time series to make it easier to visually connect the check box with its time series. The text labels could also have their colors coordinated with the series to make this connection clearer. We create the SVG plot with the command

svgPlot({
          matplot(eu$Date, as.data.frame(lapply(eu[,-1], log)),
                  type = "l", xlab = "Year", ylab = "log(exchange rate)",
                  main = "European Exchange Rate", xaxt = "n")
          startYr = min(eu$Date)
          endYr = max(eu$Date)
          axis.POSIXct(1, at=seq(startYr, endYr, by="year"), format ="%y")
          abline(h = 1, col = "gray")
       }, "euSeries.svg")

Note that in this case we are explicitly writing the SVG to a file rather than returning the SVG tree.

• Static
• Dynamic

This screen shot shows a time-series plot (via matplot() ) of exchange rates against the Euro for 24 different currencies. The SVG is post processed to add check boxes to the right of the plot. These check boxes are interactive and allow the viewer to toggle on/off the display of the corresponding currency's time series within the plot. The SVG GUI controls shown here are provided by Carto:Net.

A simple call to radioShowHide() will do all the post-processing of the SVG document created in the matplot() call:

doc = radioShowHide("euSeries.svg", within = TRUE, 
         labels = currency.names[ match(names(eu)[-1], 
                                        names(currency.names))])

We can also extend this functionality to plots with multiple panels. For example, we might draw the daily time series for the different currencies for each year in a separate panel by conditioning on year. Then toggling the currency check box would show/hide the corresponding curves in each of the panels. Again, the reader should view the example by visiting the package's Web site and viewing it there.

The interactivity for the examples considered so far have been entirely contained within the SVG document. That is, the SVG or JavaScript code that responds to user interaction has been located in the SVG file. In this section, we demonstrate that it is also possible to control SVG using JavaScript that is placed within an HTML document, where the SVG display is also embedded in the HTML.

There are several benefits to this approach. For example, HTML forms can be used to control the interactivity, and these controls can be easily visually arranged using layout facilities in HTML, e.g. lists, <table>s or <div>s rather than in the SVG display. Other advantages are that embedding the SVG document in HTML allows us to control the width and height of the area in which it is displayed; multiple SVG documents can be embedded in one HTML document; and SVG documents can be linked together via JavaScript in the HTML document. There can be separate JavaScript code in the different components, i.e. in the HTML document and each SVG document. This increased locality and flexibility can also be slightly more complicated.

In this section, we provide two examples of this approach. The first revisits a previous example and creates interactivity through HTML forms rather than with mouseover calls to JavaScript functions. It provides an important comparison. In the second example, we move the process of annotating the SVG entirely into the viewing stage, specifically at the point where the document is loaded into the browser. As such, JavaScript, rather than R, is used to augment the SVG elements with the necessary annotations for interactivity, e.g. adding onmouseclick attributes to plot elements.

(X)HTML Forms

HTML forms [4] provide built-in controls, such as a choice menu, check box, radio button, textbox, and button that receive input from the user. The controls are not as rich as those available in Carto:Net, e.g. a slider is only available via JavaScript rather than a built-in HTML element, however they are simple to deploy in an HTML page and make available to readers.

With forms, we can mix controls in HTML with a plot in SVG. We embed the SVG display in an HTML document using the HTML element <object> such as

<object id="PlotID" data="plot.svg" 
        type="image/svg+xml" width="960" height="800"/>    

which specifies the name of the SVG file via the data attribute, its MIME type, and dimensions. When we want to operate on pieces of the SVG document (e.g. when the viewer clicks on an HTML button), we use JavaScript to retrieve the resulting SVG object. Once we have the SVG object, we can operate on it with JavaScript, just as we have when we placed the scripts in the SVG document. The JavaScript code below shows how to retrieve the the embedded object and treat it as an SVG document.

doc = document.getElementById('PlotID');
doc = doc.getSVGDocument();

Note that we use 0 as the index because JavaScript uses 0-based indexing (see the section called “Appendix: Basics of JavaScript”).

We can then write JavaScript callback functions that respond to viewer input via the controls in an HTML form where these functions interact with an SVG document embedded in the HTML document. For example, when a viewer selects an option from a choice menu, a JavaScript function can be called to modify an SVG display in the document. We illustrate this with the next example.

Example 13.  Using forms to highlight points in a lattice plot.

This example re-implements Example 6, “Linking across lattice plots”. In that example, we have a legend on a lattice plot. The legend displays the levels of a categorical variable which is not contained in the display but which is part of the data set being displayed, i.e. an additional variable. When the viewer moused over an entry in the legend, the observations corresponding to this level of the variable were highlighted in the different panels of the lattice plot. In this version of the example, we remove the legend from the plot, and instead control the highlighting action through a choice menu in an HTML form (see Figure 15, “ Linking an HTML select menu to points in a conditional plot ”). That is, the SVG is embedded in an HTML document and this document also contains an HTML form with a choice menu.

• Static
• Dynamic

This screen shot of an HTML page shows an SVG lattice plot that is controlled by a choice menu in an HTML form. It offers the same functionality as the SVG document in Figure 11, “ Linking a legend to a group of points in a conditional plot ”. However, when the viewer changes the choice in the HTML form, a JavaScript function in the HTML document is called to respond to this event.

The HTML document rendered in Figure 15, “ Linking an HTML select menu to points in a conditional plot ” contains the SVG plot by including it using the following <object> tag:

<object id="latticePlot"  data="mt_lattice_Choice.svg" 
        type="text/svg+xml" width="960" height="768" />

The SVG document is the same as the one created in the earlier example with two important differences. First, it no longer contains any JavaScript code. Also, the legend has been removed from the lattice plot as the HTML form is replacing the mouse-over capability. However, all of the plotting elements still have their appropriate identifier attributes (i.e. their id indicates to which group they belong).

Along with the SVG display of the scatter plot, the HTML document also contains a <form> with a <select> menu that has four options as shown below.

<form>
Choose number of gears: 
 <select name="gear" onchange="showChoice(this)">
   <option value="0" default="true">Select</option>
   <option value="1">three</option>
   <option value="2">four</option>
   <option value="3">five</option>
 </select>
</form>

Notice that when the selection is changed, the showChoice function is called.

The showChoice function is passed the JavaScript object corresponding to the choice menu and it uses this to query the value the viewer has selected. The showChoice function then calls highlight with the information that it needs to highlight the new group of points. showChoice is

var oldgroup = 0;
var group = 0;
var e;
 
function  showChoice(obj) 
{ 
  e = document.getElementById('latticePlot');
  e = e.getSVGDocument();
  group = Math.floor(obj.value);

  if (group > 0) {
    highlight(group, pointCounts[(group - 1)], true);
  }

  if (oldgroup > 0) {
    highlight(oldgroup, pointCounts[(oldgroup - 1) ], false);
  }

  oldgroup = group;
}

The highlight function called from showChoice and its helper function highlightPoint are identical to the functions by the same name that were placed in the <script> tag within the SVG document in Example 6, “Linking across lattice plots”. They extract the elements in the SVG document corresponding to the points that belong to the selected group, and change their style attributes. These function rely on the plotting elements having unique ids, that indicate the group of points to which they belong. The embedded SVG document is in the global variable e, from which highlight obtains the panel as follows:

function highlight(group, pointCts, status)
{
    var el;
    var i, numPanels = pointCts.length;

    for(panel = 1; panel <= numPanels; panel++) {
        for(i = 1; i <= pointCts[panel-1]; i++) {
            var id = panel + "-"+ group + "-" + i;
            el = e.getElementById(id);
            if(el == null) {
                alert("can't find element " + id)
                return(1);
            }
            highlightPoint(el, status);
        }
    }
}

highlight and highlightPoint now appear in the <head> of the HTML document rather than in the SVG document. We can programmatically add it to the HTML document in much the same way we did for the SVG document using addECMAScripts() .

Note that the SVG document created for this example had no JavaScript in it, and no calls to JavaScript functions. The interactive functionality does rely on the plot elements in the SVG having unique identifiers. In general, provided the plot elements have appropriate ids, “plain” SVG can be made interactive via JavaScript embedded in HTML rather than in the SVG. The advantage of this approach is that plots made for some general purpose can be made to have interactive capabilities.

<body>
<center>
<h3>Presidential Election 2008</h3>

<p>
The map is interactive in that you can click on
anywhere within a state to see more detailed
results about the voting in that state.
</p>
</center>

<div id="main">
 <div id="summaryMap">
    <div id="stateSummary"></div>
    <div id="map">
       <object id="svgMap" data="stateMap.svg" 
          type="image/svg+xml" width="700" height="700"> 
       </object>
    </div>
 </div>

 <div id="countySummary">
    <a id="toggleCounty" 
       onclick="toggleCountyView()">+ Click to see county results</a>
    <div id="countySummaryContent" class="hidden">
       Click on a state to see more detailed information about the
       election results for that state.
    </div>
  </div>
</div>

<script type="text/javascript">
    var doc;
    doc = document.getElementById('svgMap');
    doc = doc.getSVGDocument();

    for(var i = 0; i < polyIds.length ; i++) {
        var el = doc.getElementById(polyIds[i]);
        el.onclick = "parent.show('" + polyStates[i] + "')";
    }
</script>

<script type="text/javascript">
function show(stateName)
{
  var val;
  var div;
  val = stateSummaryTables[stateName];
  div = document.getElementById("stateSummary");
  div.innerHTML = val;

  val = countyTables[stateName];
  if(val) {
    div = document.getElementById("countySummaryContent");
    div.innerHTML = val;
  }
}
</script>

<script type="text/javascript" src="stateHTMLTables.js"></script>

The SVGAnnotation package allows R users to leverage the sophisticated and flexible static graphics frameworks in R to create displays of data and models and then display them in new and interesting ways in new emerging media. With SVGAnnotation, we can add interactivity and animation to the displays. The mechanism relies on post-processing the output from the R graphics engine and associating elements within the SVG output with the high-level components of the display. This is entirely deterministic based on the nature of the R plot, but is slightly different for each type of plot since there is no simple format or model for expressing all plots. The purpose of SVGAnnotation is to find the SVG elements corresponding to the R elements and allow the R user to easily augment these.

The package provides high-level facilities for “standard” plots in which we can readily identify the R elements. It also allows an R programmer to use intermediate-level facilities to operate on axes, legends, etc. There are also low-level facilities for identifying the shape of visual elements, e.g. polygon, line, vertical line, text. The functions in the package can also add high-level type identifiers to nodes in the SVG document such as identifying data points, axes, labels. These facilities allow us to handle cases from regular R graphics, lattice[20], ggplot [14] and grid [13]. Leveraging the XML facilities in R or higher-level functions offers capabilities for creating rich new plots in R. Most importantly, the approach and the concept it implements is readily extended to other contexts. The abstract idea and approach is the important contribution; the implementation is a detail.

Our approach in the SVGAnnotation package is to use the high-quality rendering engine provided by libcairo from within R. There are two other SVG graphics devices available for use within R. These are the RSvgDevice [31] and the derived RSVGTipsDevice [32] R packages. The former generates an SVG document that contains SVG elements corresponding to the graphical primitives the R graphics engine emits, e.g. lines, rectangles, circles, text. However, the libcairo system is more widely used and more robust. It also deals with text in more advanced and sophisticated ways. This is the primary reason we use the libcairo approach even though the format of the SVG documents that RSvgDevice produces is simpler and more direct.

The RSVGTipsDevice package builds on the code from RSvgDevice. It allows R programmers to add SVG annotations and does so when the SVG is being created, rather via post-processing additions. R users can set text for tooltips and URLs for hyperlinks that are applied to the next graphical primitive that the R graphics engine emits. This works well when the R programmer is creating all graphical elements in a display directly in their own code. However, it does not work when calling existing plotting functions that create many graphical elements. The computational model does not provide the appropriate resolution for associating an annotation with a particular element, but just the next one that will be created. As a result, we cannot annotate just the vertical axis label when calling a function that creates an entire plot.

Our post-processing approach is not limited to using libcairo. We could also use RSVGTipsDevice to generate the SVG content and then programmatically manipulate that. The documents generated by the two different devices will be somewhat different (e.g. the use of groups of characters for strings, in-line CSS styles versus separate classes, SVG primitives for circles rather than paths). However, because the elements of the graphical display were generated by the R graphics engine with the same R expressions, the order of the primitive elements and the general structure will be very similar.

The package gridSVG [12] is an earlier and quite different approach to taking advantage of SVG. As the name suggests, it is focused on R's grid graphics system.For this reason, it cannot work with displays created with the traditional and original graphics model (“grz”) but does handle all of the plot types in lattice. gridSVG takes advantage of the structured self-describing information contained in grid's graphical objects. As one creates the grid display, the information about the locations and shapes are stored as objects in R. These can then be translated to SVG without using the R graphics device system. New graphics primitives have been added to the grid system to add hyperlinks, animations, etc. corresponding to the facilities provided in SVG.

The approach provided by gridSVG is quite rich. It removes the need to post-process the graphics that we presented here. Instead, one proactively and explicitly states graphical concepts. One limitation that is similar to that of RSVGTipsDevice is that we still run into problems with interleaving SVG annotations. While a user can issue grid commands that add SVG facilities to the output, higher-level functions that create plots produce entire sequences/hierarchies of grid objects in a single operation. If these do not add the desired annotations, we have to post-process the grid hierarchy to add them. This is a very similar post-processing that we are doing, however it is done on R objects.

Of course, gridSVG is restricted to the grid graphics system. Our approach however works with the output of any R graphical output, although it needs to be “trained” to understand the content. The combination of the two approaches: gridSVG and SVGAnnotation appear to give a great deal of flexibility that allows both pre-processing and post-processing.

The animation package [33] provides functionality to create movies (e.g. animated GIF files or MPEG movies) entirely within R. The idea is that one draws a sequence of plots in R. These are combined and then displayed at regular intervals as frames of the movie to give the appearance of motion. R users can draw each frame using R code and without regard for particular graphics device or formats. This simplifies the process for many. The approach does, however, involve redrawing each frame rather than animating individual objects. It also provides no interactive facilities. It involves a different programming model where we redraw entire displays rather than working on individual graphical elements. In different circumstances, each model has advantages. So while animated displays are common to both the animation and SVGAnnotation packages, the goals and infrastructure are very different.

The motivation behind the SVGAnnotation package is the ability to exploit and harness new media such as interactive Web browsers. The aim is to enable statisticians to be able to readily create new graphical displays of data and models using existing tools that can be displayed in rich, interactive and animated venues such as Web browsers, Google Earth, Google Maps, GIS applications. The SVGAnnotation package focuses on facilitating R users in leveraging exiting R graphical functionality and then post-processing the output to make it interactive and/or animated. It is a complete computational model in that it enables the author of a display (or a third-party) to modify all elements in that display. This approach can be used for other modern formats.

Another format for graphical displays and applications is Adobe's Flash & Flex (http://www.adobe.com/products/flash). This is an alternative to SVG that is a very widely used framework (the ActionScript programming language, collection of run-time libraries, and compiler suite) for creating interactive, animated general interfaces and displays. The range of applications include rich graphical user interfaces and interactive, animated business charts. Flash and Flex are freely available, but not Open Source. The format and tools are mostly controlled by Adobe. The Adobe chart libraries for Flash are only available in commercial distributions.

There are publicly available Open Source libraries for creating certain types of common plots, e.g flare http://flare.prefuse.org. Alternatively, we can use R to create statistical graphical displays by generating ActionScript code to render the different elements in the display. We have developed a prototype R graphics device (in the FlashMXML package) that creates Flash plots within R. To provide interaction and animation, connect the plot to GUI components, etc., we can post-process that code in much the same way we do with the SVGAnnotation package.

Rather than considering Flash and JavaScript as competitors to SVG, we think that each has its own strengths. SVG is more straightforward and direct than Flash and JavaScript for creating graphical displays. For one, we have an excellent R graphics device that creates the initial SVG content. We can add GUI components, but Flash is better for this as it provides a much richer collection of GUI components such as the data grid. Drawing displays with JavaScript avoids depending on the presence of support for either SVG or Flash and so can be deployed in more environments.

Another approach is to use the HTML5 canvas element that has been recently introduced in several browsers. We can create JavaScript objects for drawing, e.g., circles, lines, text on a canvas. Again, we have developed a prototype R graphics device that generates such code for an R plot. We can also annotate this to add animation and interaction. We also mention the Vector Markup Language (VML) (http://msdn.microsoft.com/en-us/library/bb263898(VS.85).aspx) which is quite similar to SVG. It is used within Microsoft products such as Word, Excel and PowerPoint. However, it is not widely supported by other applications.

A fundamental aspect of what we have described with respect to the SVGAnnotation package is that R is used to create the display but is not available at viewing time when the SVG document is rendered. If R were an extension or plugin for the SVG viewer, the ECMAScript code within an SVG document coud make use of R at run-time. It could invoke R functions and access data to update the display in response to user interaction and animation. Additionally, we could use R code to manipulate the SVG and HTML content and so enable programming in either ECMAScript and R. We are developing such an extension for Firefox which embeds R within a user's browser. This modernizes our previous work in 2000 on the SNetscape package that embedded R and R graphics devices within the Netscape browser. We believe the combination of SVG (or Flash or the HTML5 canvas) with R at viewing-time will prove to be a very rich and flexible environment for creating new types of dynamic, interactive and animated graphics and also allow Google Earth and Maps displays to be combined with R plots and computations.

In conclusion, the increasing importance of Web based presentations is a space where statisticians need to be engaged. To accomplish this, we need more tools for creating these presentations. SVGAnnotation offers one approach; we are working on others. We ask that the reader think of the package as a rich starting point that enables a new mode of displaying R graphics in an interactive, dynamic manner on the Web. It establishes a foundation on which we and others can build even higher-level facilities for annotating SVG content and providing rich plots in sever different media (i.e. SVG, HTML, JavaScript).

The basic unit in an XML document is an element, also known as a node or chunk. An element can contain textual content and/or additional XML elements. By content, we mean the simple text, such as the word “Oregon” that appears in the simple SVG document shown in Figure 8, “Sample SVG”. So we have text and XML elements. An element begins with a start-tag and ends with an end-tag. The start-tag has the format <tagname> and the end-tag uses the same tag name but has an additional forward slash before the tag name, i.e. </tagname>. Those readers who have read or composed HTML (HyperText Markup Language) will recognize this format. For more in-depth information about XML see [5, 25].

SVG, like HTML or WordProcessingML, is an example of a specific grammar of XML, where the focus of SVG is to describe graphical displays. The SVG document rendered in Figure 8, “Sample SVG” includes element/tag names such as <circle> and <rect> for drawing circles and rectangles respectively. Notice that some of the elements in the sample SVG document are nested within other start and end tags. This hierarchical structure gives us great flexibility in describing complex, nested data with arbitrary depth.

For more details about the specific tags and how to create SVG graphics, see the section called “The SVG Grammar”.

In addition to child or sub-elements, an XML element can have attributes associated with it. Attributes are supplied in the element/tag itself as name="value" pairs separated by an equals sign as follows: <tagname attributeName="value">. For example, the <text> tag,

 <text x = "110" y = "200" fill = "navy" font-size = "15">
        Oregon
 </text>

has an attribute, x, which specifies the horizontal position of the text on the SVG canvas. The value for x in this example is "110", indicating position 110 along the x-axis of the canvas (which in our example is 300 by 300 points). The syntax rules for elements and their tags are provided below in the section called “ Well-formed XML”.

We should note one important short cut for start and end tags. If an XML element contains no text content or elements within it, i.e. there are no text or sub-elements contained between the start and end tags of the element, then it can be written as <tagname/> rather than the longer <tagname ></tagname>. For example, notice that the <rect> element:

<rect x = "10" y = "20" width = "50" height = "100" 
          class = "recs"/>

is empty. All of the relevant information for drawing the rectangle is contained in the attributes, i.e. its width, height, location on the canvas, and color. Hence the end tag is omitted and the start tag also acts as a closing tag.

 
<?xml version="1.0" encoding="UTF-8"?>

<?xml-stylesheet type="text/css"
   href= '~/Rpackages/SVGAnnotation/CSS/RSVGPlot.css'?>

 
<!-- This is a comment which is so long that 
it appears on three lines of
the document before it ends with -- followed by >. 
-->

<![CDATA[ 
 plot(y ~ x, myData[ (myData$var1 < 10 | myData$var1 > 20) & 
                       myData$var2 %in% c("A", "B", "&")])
 ]]>

We provide here a brief introduction to JavaScript for programmers who are familiar with the S language. JavaScript (the official name is ECMAScript) is an interpreted scripting language that is widely used within HTML documents and also within SVG displays and Flash applications (using a slight variant named ActionScript). JavaScript can be used within HTML to respond to user actions on buttons, menus, checkboxes, etc. in HTML forms, or to dynamically validate the content of a form before submitting it to a remote server. JavaScript can also be used to dynamically and programmatically construct the content of an HTML document. Within SVG, we use JavaScript to respond to user events on elements of the display (e.g. circles, lines, rectangles, ...) and to provide animation. Similar to HTML, JavaScript can be used to dynamically create SVG elements within the display after the initial display.

As with R, one does not need to compile JavaScript code since it is interpreted. However, JavaScript is more like C++, Python and Java in its computational model. Much of the use of the language will focus on classes and instances (objects) of these classes. We frequently invoke an object's methods rather than call top-level functions, although like R, we can have regular functions unattached to objects.

JavaScript is not a vectorized language like R, i.e. it does not operate on vectors element-wise unless explicitly programmed to do so using loop constructs.

JavaScript requires variables to be declared within the scope in which they are used. Unlike C++ or Java, one does not need to declare the type of a variable and a variable can take on values of different types during its lifetime.

To make use of JavaScript within an HTML or SVG document, we must connect that code with the document. We can do this by either inserting the code as content in the document or alternatively adding a reference to the file containing the JavaScript code. That code file may be located locally or on a remote server, subject to certain security restrictions. Both approaches use the <script> node within the HTML or SVG document. We can insert the code content between the start and end tag of the <script> node. Alternatively, we can use an attribute in the <script> element to refer to the JavaScript file. For SVG, we use an attribute named xlink:href; for HTML, we use src. The value in both cases is a local file name or a URL. The following illustrates the mechanism for SVG:

  <script xmlns:xlink="http://www.w3.org/1999/xlink" 
          xmlns="http://www.w3.org/2000/svg"
          type="text/ecmascript" 
          xlink:href="SVGAnnotation/tests/multiLegend.js"/>

For HTML

<script type="text/javascript" src="alert.js"/>

To in-line the JavaScript content, we use

<script type="text/ecmascript">

var neighbors = [[0,  1, 31, 20,  3, 29], [2, 8, 9, 24]]; 
var k = 4;

function showNeighbors(evt, k, neighbors)
{
    var idx = 1 * evt.target.getAttribute('id');
    window.status = "Showing " + idx;
    addLines(evt.target, neighbors[idx], k);
}
</script>

Note that we have to specify the type attribute but can use either javascript or ecmascript in most HTML browsers and SVG viewers.

Often, JavaScript code that defines functions that will be used in event handler attributes on HTML or SVG elements are placed in a script element near the top of the HTML or SVG document. For HTML, these function definitions and global variables often appear in the <head> element. JavaScript code can also appear within the <body> of an HTML document and is evaluated when it is processed and so can access previously created elements in the document.

We provide here a brief summary of many of the basic syntax features of the language. For more detailed information about JavaScript see [3, 24]

In addition to the syntactic rules for JavaScript above, we spend a great deal of time when writing JavaScript focused on objects and their methods. JavaScript provides a large library of classes and we either explicitly create instances of these via the new operator, e.g. rx = new Regexp("^[ACGT]+$") or work with existing objects provided to us. We operate on these objects via their methods. We invoke these methods as if they were functions belonging to the object, e.g. rx.exec("my string") or node.removeChildren(). Objects also have properties or fields and we can query and set these, e.g. button.value = "My Label" and document.links.

There are many classes and each has many methods. This is what makes JavaScript useful, but also difficult to learn because you need to find the classes and methods of use for your task. There are a few classes and methods, however, that arise very commonly in JavaScript code for SVG and HTML documents. One of this is the Document that provides access to the contents of the document being displayed. Another is the general concept of a document element represented by the Node and Element classes and the more specific SVGElement and HTMLElement classes and their sub-classes (e.g. SVGCircleElement, HTMLHeadingElement). These classes allow us to not only query the contents of the document, but also to programmatically modify this content, adding new elements or changing the characteristics of existing elements.

When JavaScript code is evaluated as part of an HTML or SVG document, there is an implicit global variable named document. This is the top-level Document object and we can refer to it without any declarations or additional code. Perhaps the most important method this provides for our use is getElementById which searches the entire SVG/HTML tree and finds the element which has an id attribute with the specified value. Another method, getElementsByTagName, allows us to find SVG/HTML elements based on the name of the element/tag, e.g. “h1” or “path”.

Once we have an element in the document, we can use its methods to operate on it. We can retrieve the values of the element's attributes via getAttribute, e.g. circle.getAttribute("r"). Similarly, we can set the value of an existing or new attribute using setAttribute. We can query the child nodes of a Node/Element via its childNodes field, and the parent node via parentNode field. We can add nodes via the appendChild and insertBefore methods, and we can remove nodes via removeChild.

status = "# of links " + document.links.length

<script type='text/javascript' 
        src='http://getfirebug.com/releases/lite/1.2/
                                      firebug-lite-compressed.js'>
</script>

function doConfirm()
{
var con = confirm("Do you really want to do this?");
if (con == true)
  {  ...  }
else
  { ... }
}