\documentclass[article]{jss}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% declarations for jss.cls %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%% almost as usual
\author{Paul Murrell\\The Unversity of Auckland \And 
        Simon Potter\\The Unversity of Auckland}
\title{Dynamic and Interactive \R{} Graphics for the Web: The \pkg{gridSVG} Package}

%% for pretty printing and a nice hypersummary also set:
\Plainauthor{Paul Murrell, Simon Potter} %% comma-separated
\Plaintitle{Dynamic and Interactive R Graphics for the Web: The gridSVG Package} %% without formatting
\Shorttitle{Dynamic and Interactive R Graphics for the Web} %% a short title (if necessary)

%% an abstract and keywords
\Abstract{
This article describes the \pkg{gridSVG} package, which
 provides functions to convert \pkg{grid}-based \R{} graphics
to an \svg{} format.  The package also provides a function to associate 
hyperlinks with components of a plot, a function to animate
components of a plot, a function to associate any \svg{}
attribute with a component of a plot, and a function to 
add \js{} code to a plot.  The last two of these provides
a basis for adding interactivity to the \svg{} version of the plot.  
Together these tools provide a way to generate dynamic and 
interactive \R{} graphics for use in web pages.
}
\Keywords{world-wide web, graphics, \proglang{R}, \proglang{SVG}}
\Plainkeywords{world-wide web, graphics, R, SVG} %% without formatting
%% at least one keyword must be supplied

%% publication information
%% NOTE: Typically, this can be left commented and will be filled out by the technical editor
%% \Volume{13}
%% \Issue{9}
%% \Month{September}
%% \Year{2004}
%% \Submitdate{2004-09-29}
%% \Acceptdate{2004-09-29}

%% The address of (at least) one author should be given
%% in the following format:
\Address{
  Paul Murrell\\
  Department of Statistics\\
  The University of Auckland\\
  38 Princes Street, Auckland\\
  New Zealand\\
  E-mail: \email{paul@stat.auckland.ac.nz}\\
  URL: \url{http://www.stat.auckland.ac.nz/~paul/}
}
%% It is also possible to add a telephone and fax number
%% before the e-mail in the following format:
%% Telephone: +43/1/31336-5053
%% Fax: +43/1/31336-734

%% for those who use Sweave please include the following line (with % symbols):
%% need no \usepackage{Sweave.sty}

%% end of declarations %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\usepackage{boxedminipage}

\newcommand{\svg}{\proglang{SVG}}
\newcommand{\png}{\proglang{PNG}}
\newcommand{\R}{\proglang{R}}
\newcommand{\ggobi}{\proglang{GGobi}}
\newcommand{\xml}{\proglang{XML}}
\newcommand{\xpointer}{\proglang{XPointer}}
\newcommand{\xpath}{\proglang{XPath}}
\newcommand{\cairo}{\proglang{Cairo}}
\newcommand{\js}{\proglang{JavaScript}}
\newcommand{\mpg}{\proglang{MPEG4}}
\newcommand{\java}{\proglang{Java}}
\newcommand{\html}{\proglang{HTML}}
\newcommand{\mac}{\proglang{MacOS X}}
\newcommand{\linux}{\proglang{Linux}}
\newcommand{\windows}{\proglang{Microsoft Windows}}

\newcommand{\dfn}[1]{\emph{#1}}

\begin{document}

\SweaveOpts{keep.source = true, eps = false}

<<echo=FALSE>>=
options(prompt="R> ", continue="R+ ", useFancyQuotes=FALSE)
@ 

%% include your article here, just as usual
%% Note that you should use the \pkg{}, \proglang{} and \code{} commands.

\section{Introduction}
%% Note: If there is markup in \(sub)section, then it has to be escape as above.
Interactive and dynamic plots within web pages are becomingly 
increasingly popular, as part of a general trend towards making data sets
more open and accessible on the web, for example, 
GapMinder \citep{bib:GapMinder} and
ManyEyes \citep{manyeyes}.

The \R{} language and environment for
statistical computing and graphics \citep{R} has many facilities for 
producing plots, and it can produce graphics formats that are
suitable for including in web pages,
but the core graphics facilities in \R{} are largely focused on 
\emph{static} plots.

This article describes an \R{} extension package, \pkg{gridSVG},
that is designed to embellish and transform a standard, static
\R{} plot and turn it
into a dynamic and interactive plot that can be embedded in a web page.

\subsection[R graphics]{\R{} graphics}

Several \R{} packages are being developed to produce interactive and dynamic 
plots for inclusion in web pages.  For example, the \pkg{googleVis} package
\citep{pkg:googleVis}
provides an interface to the Google Visualization API
and the \pkg{webvis} package \citep{pkg:webvis} produces \js{} code for the
\proglang{protovis} \citep{protovis} web visualization library.  In both cases,
the graphics are produced by an external system rather than \R{}.
This abandons the powerful graphical facilities that \R{} possesses.

The \pkg{gridSVG} package provides a way to add dynamic and
interactive features to plots that are produced by \R{}
\citep[specifically, plots that are based on the \pkg{grid} graphics 
package;][]{Murrell201106}.

\subsection{Vector graphics}

It is straightforward to produce a \emph{static} \R{} graphic that can be
included in a web page.  For example, a plot that
is saved as a \png{} file can be included via an \html{} \code{<img>} element.
However, raster image formats such as \png{} are only
designed for a specific size and do not scale well.

A better solution 
is possible with recent web browsers because they
now have native support for the \svg{} format
\citep{bib:SVGEssentials}.  This allows 
\emph{vector} graphics to be used for a web page, which will produce better
results because the plot should look good at any scale.
The \svg{} file can be included
in a web page via an \html{} 
\code{<object>} element.

Producing static \svg{} output from \R{} is a little more complicated 
than producing \png{} output
because it depends on the operating system.  On \linux{} and \mac{},
there is an \code{svg()} function, but on \windows{} the
\pkg{Cairo} package \citep{pkg:cairo} must be installed to provide the 
\code{CairoSVG()} function. 

Some \R{} extension packages can be used to add some interactivity to
an \R{} plot in a \png{} format.  These make use of the fundamental
\html{} image map technology whereby regions of a raster image
can be identified and have interactive behaviour associated with them. 
The \pkg{iWebPlots} \citep{pkg:iwebplots}
package provides functions for producing 
image maps with tooltips for some standard plot types and
the \pkg{imagemap} package \citep{pkg:imagemap} provides similar functionality.

The \pkg{gridSVG} package targets the \svg{} format instead, to allow
dynamic and interactive features to be added to \R{}
plots in a \emph{vector} format.

\subsection{Smooth animation}

The \pkg{animation} package \citep{pkg:animation}
can be used to animate standard \R{} graphics.
This works by producing multiple static images, in a raster format, 
and then either stitching the images together in a movie format,
 such as \mpg{}, or playing the images rapidly one after the other.
A movie file can be embedded in a web page using an 
\code{<object>} element and the \pkg{animation} package 
provides a convenience function to generate a web page with
\js{} controls for playing a sequence of images.

One limitation of this approach is that the result is 
a raster image, with the disadvantages mentioned above.
It is also not possible to 
interact with this sort of dynamic plot.  Furthermore, the animation 
is described in a ``brute force'' method, with every frame having 
to be drawn separately.  

By targeting the \svg{} format, 
the \pkg{gridSVG} package allows both dynamic and interactive features at once,
in a vector graphics format,
and it allows dynamic features to be described more elegantly.
For example, in order to make a single point move within a plot, it
is only necessary to describe the changing location of that point,
and in simple cases only the start and end locations are required.

\subsection{Direct interaction}

A number of \R{} packages provide GUI toolkits, such as 
\pkg{tcltk} \citep{R}, \pkg{RGtk2} \citep{pkg:rgtk2}, 
and \pkg{gWidgets} \citep{pkg:gwidgets}.  With regard to graphics,
these provide a way to allow user interaction with a plot via menus, dialogs,
buttons, and sliders.

However, these sorts of interfaces do not allow direct interaction with
the components of a plot, such as tooltips on data points and drill-down
by clicking on a region of a plot.

The \pkg{gridSVG} package is designed to allow interaction with
individual components of an \R{} plot.

\subsection{Extensibility}

The \pkg{RSVGTipsDevice} package \citep{pkg:rsvgtips}
 provides an \R{} graphics device
that saves \R{} plots in an \svg{} format and allows 
tooltips and hyperlinks to be associated with different
components of the plot.
The main limitation of this package is that it is hard-wired
for these two sorts of interaction (tooltips and hyperlinks).
The package is not designed to be extended by the user for other
 sorts of interaction.

The \pkg{SVGAnnotation} package \citep{pkg:svgannotation}
provides a much wider range
of facilities for adding dynamic and interactive features to
an \R{} plot (in an \svg{} format).  It is possible to 
add tooltips, animate points, and even link plots (so that
clicking on a point in one plot highlights the corresponding 
point in a separate plot).  This package will be discussed in
more detail in a later section, once we have established 
the structure of the \pkg{gridSVG} package.
For now, it will just be stated that 
although the \pkg{SVGAnnotation} package provides some very 
powerful functions for adding interaction to some plots, 
it is not straightforward for a non-expert to extend the
package to plots that are not currently supported.

One aim of the \pkg{gridSVG} package is to provide general tools
that can be easily adapted by non-experts to add interactivity
to any plot or indeed any graphic in general that has been produced by
\R{}'s \pkg{grid} graphics system.

In summary, the \pkg{gridSVG} package is aimed at producing 
dynamic and interactive \R{} graphics,
in a vector format, for inclusion in web pages,
using a transparent mechanism that can be easily
adapted and extended by the non-expert user.

\section[The gridSVG package]{The \pkg{gridSVG} package}

This section gives a brief introduction to the main features
of the \pkg{gridSVG} package.

The main function in the \pkg{gridSVG} package is 
\code{gridToSVG()}, which copies the current \pkg{grid} 
scene to an \svg{} document.
An example of a simple \pkg{grid} scene, consisting of two rectangles,
one above the other, is shown in Figure~\ref{figure:gridscene}.
The code to produce this scene is shown below.

<<>>=
library("grid")
@ 

<<gridscene, fig=TRUE, include=FALSE, width=2, height=2>>=
topvp <- viewport(y=1, just="top", name="topvp",
                  height=unit(1, "lines"))
botvp <- viewport(y=0, just="bottom", name="botvp",
                  height=unit(1, "npc") - unit(1, "lines"))
grid.rect(gp=gpar(fill="grey"), vp=topvp, name="toprect")
grid.rect(vp=botvp, name="botrect")
@ 

\begin{figure}
\begin{center}
\includegraphics[width=2in]{gridsvg-gridscene}
\end{center}
\caption{\label{figure:gridscene}A simple \pkg{grid} scene
consisting of two rectangles, one above the other.}
\end{figure}

The following call to \code{gridToSVG()} creates an \svg{} document
from this scene.  The resulting document is 
called \code{"gridscene.svg"} and Figure~\ref{figure:gridsceneweb}
shows this document as it appears in a web browser.

<<>>=
library("gridSVG")
@ 

<<gridsceneweb, eval=FALSE>>=
gridToSVG("gridscene.svg")
@

<<echo=FALSE>>=
<<gridscene>>
<<gridsceneweb>>
@ 

\begin{figure}
\begin{center}
{\includegraphics[width=2in]{gridsceneweb.png}}
\end{center}
\caption{\label{figure:gridsceneweb}The simple \pkg{grid} scene
from Figure~\ref{figure:gridscene} in an \svg{} format, viewed
in Firefox.}
\end{figure}

The current \pkg{grid} scene could be produced from raw \pkg{grid} 
calls, as above, or it could be produced from calls to functions
from packages that are built on top of \pkg{grid}, such as 
\pkg{lattice}, \pkg{ggplot2}, \pkg{vcd}, and \pkg{partykit}.
Sections \ref{section:gridbased} and
 \ref{section:examples} provide some more complex examples.

The result of calling \code{gridToSVG()} is just a static \svg{} version
of the static \pkg{grid} scene, but the \pkg{gridSVG} package
provides other functions to add dynamic and interactive features.

\subsection{Animation}

The \code{grid.animate()} function allows the components of a \pkg{grid}
scene to
be animated.  For example, the following code animates the 
two rectangles in the simple \pkg{grid} scene above so that they
both shrink to a width of 1 inch
over a period of 3 seconds (see Figure
\ref{figure:gridanimweb}).  The widths begin with a value of 
\Sexpr{unit(1, "npc")} and end with a value of \Sexpr{unit(1, "in")}.

<<>>=
widthValues <- unit(c(1, 1), c("npc", "in"))
widthValues
@ 

The component of the \pkg{grid} scene that is to be animated 
is specified by name.  For example, the first call to 
\code{grid.animate()} below modifies the rectangle called 
\code{"toprect"}.

<<gridanimate, eval=FALSE>>=
grid.animate("toprect", width=widthValues, duration=3)
grid.animate("botrect", width=widthValues, duration=3)
@ 

<<gridanimateweb, eval=FALSE>>=
gridToSVG("gridanim.svg")
@

<<echo=FALSE, fig=TRUE, include=FALSE, width=2, height=2>>=
grid.newpage()
<<gridscene>>
<<gridanimate>>
<<gridanimateweb>>
@ 

\begin{figure}
\begin{center}
\hspace*{\fill}
{\includegraphics[width=2in]{gridsceneweb.png}}
\hspace*{\fill}
{\includegraphics[width=2in]{gridanimweb.png}}
\hspace*{\fill}
\end{center}
\caption{\label{figure:gridanimweb}A simple animated \pkg{grid} scene.
The scene starts off as shown on the left (the same as
Figure~\ref{figure:gridsceneweb}), but then the rectangles shrink
over three seconds until they end up only 1 inch wide, as shown on the right.}
\end{figure}

\subsection{Interactivity}

The \code{grid.hyperlink()} function associates a hyperlink with
a component of a \pkg{grid} scene.  For example, the 
following code adds some text to the top rectangle in the
simple \pkg{grid} scene so that when the text is clicked
the web browser will navigate to the \R{} home page
(see Figure~\ref{figure:gridhyperweb}).
Again, the component that is to be turned into a hyperlink
is specified by name;  in this case, it is the text component called
\code{"hypertext"}.

<<gridhyper, eval=FALSE>>=
grid.text("take me there", vp=topvp, name="hypertext")
grid.hyperlink("hypertext", "http://www.r-project.org")
@ 

<<gridhyperweb, eval=FALSE>>=
gridToSVG("gridhyper.svg")
@

<<echo=FALSE, fig=TRUE, include=FALSE, width=2, height=2>>=
grid.newpage()
<<gridscene>>
<<gridhyper>>
<<gridhyperweb>>
@ 

\begin{figure}
\begin{center}
\hspace*{\fill}
{\includegraphics[width=2in]{gridhyperweb-with-cursor.png}}
\hspace*{\fill}
\end{center}
\caption{\label{figure:gridhyperweb}A simple \pkg{grid} scene 
containing hyperlinked text.  If the text is clicked on with the
mouse, the web browser will navigate to the \R{} home page.}
\end{figure}

The \code{grid.garnish()} function allows general \svg{} attributes
to be associated with a component of a \pkg{grid} scene.
For example, the following code adds an event handler to
the bottom rectangle in the simple \pkg{grid} scene above
so that, when the mouse is clicked over the bottom rectangle, an
alert dialog pops up (see Figure~\ref{figure:gridmouseweb}).
The \code{onmousedown} attribute specifies what action to take
when the mouse is clicked and
the \code{pointer-events} attribute makes sure that the rectangle
notices mouse clicks within its interior (not just on its drawn border).

<<gridmouse, eval=FALSE>>=
grid.garnish("botrect", 
             onmousedown="alert('ouch!')",
             "pointer-events"="all")
@ 

<<gridmouseweb, eval=FALSE>>=
gridToSVG("gridmouse.svg")
@

<<echo=FALSE, fig=TRUE, include=FALSE, width=2, height=2>>=
grid.newpage()
<<gridscene>>
<<gridhyper>>
<<gridmouse>>
<<gridmouseweb>>
@ 

\begin{figure}
\begin{center}
\hspace*{\fill}
{\includegraphics[width=2in]{gridmouseweb-with-cursor.png}}
\hspace*{\fill}
{\includegraphics[width=3in]{gridmousealert.png}}
\hspace*{\fill}
\end{center}
\caption{\label{figure:gridmouseweb}A simple interactive \pkg{grid} scene.
When the mouse is clicked over the bottom rectangle, an alert dialog pops up.}
\end{figure}

More complex interaction requires adding \js{} \citep{bib:JavaScriptGuide}
to the \svg{} output.
This is achieved via the \code{grid.script()} function, which can 
be given either \js{} code as a character vector or the name of a file 
that contains \js{} code.  For example, 
the following code adds an event handler to the top rectangle 
in the simple \pkg{grid} scene so that, when the mouse is clicked within
the top rectangle, the interior of the rectangle is filled black
(see Figure~\ref{figure:gridscriptweb}).
The design of the \js{} code will be described in 
Section \ref{section:gridsvgdesign} and
Section \ref{section:examples} contains some more sophisticated 
examples of interaction.

<<gridscript, eval=FALSE>>=
grid.garnish("toprect", 
             onmousedown="allblack()",
             "pointer-events"="all")
grid.script("
  allblack = function() {
    rect = document.getElementById('toprect.1');
    rect.setAttribute('style', 'fill:black');
  }")
@ 

<<gridscriptweb, eval=FALSE>>=
gridToSVG("gridscript.svg")
@

<<echo=FALSE, fig=TRUE, include=FALSE, width=2, height=2>>=
grid.newpage()
<<gridscene>>
<<gridhyper>>
<<gridmouse>>
<<gridscript>>
<<gridscriptweb>>
@ 

\begin{figure}
\begin{center}
\hspace*{\fill}
{\includegraphics[width=2in]{gridmouseweb.png}}
\hspace*{\fill}
{\includegraphics[width=2in]{gridscriptweb-with-cursor.png}}
\hspace*{\fill}
\end{center}
\caption{\label{figure:gridscriptweb}A slightly more complex
 interactive \pkg{grid} scene.
When the mouse is clicked over the top rectangle, 
the top rectangle is filled with black.}
\end{figure}

\subsection[Graphics based on grid]{Graphics based on \pkg{grid}}
\label{section:gridbased}

The examples so far have used direct calls to \pkg{grid} functions
to draw a scene, but the techniques described will also work with
plots drawn by packages that are built on \pkg{grid}, such as 
\pkg{lattice} \citep{pkg:lattice}, \pkg{ggplot2} \citep{pkg:ggplot}, 
\pkg{vcd} \citep{pkg:vcd}, and \pkg{partykit} \citep{pkg:partykit}.

For example, the following code generates a multipanel conditioning
plot using the \pkg{lattice} package.

<<>>=
library("lattice")
@ 

<<xyplot>>=
xyplot(Sepal.Length ~ Sepal.Width | Species, iris)
@ 

The next piece of code uses the \pkg{grid.hyperlink()} function 
to add hyperlinks to the strip labels in that plot.

<<latticehyperlink>>=
grid.hyperlink("plot_01.textr.strip.1.1", 
               "http://en.wikipedia.org/wiki/Iris_flower_data_set")
grid.hyperlink("plot_01.textr.strip.1.2", 
               "http://en.wikipedia.org/wiki/Iris_virginica")
grid.hyperlink("plot_01.textr.strip.2.1", 
               "http://en.wikipedia.org/wiki/Iris_versicolor")
@ 

The plot can now be converted to \svg{} using \code{gridToSVG()}
so that clicking on the strip labels in a web browser will
navigate to the relevant pages of Wikipedia (see Figure 
\ref{figure:latticehyper}).

<<lh>>=
gridToSVG("latticehyper.svg")
@ 

<<latticehyper, echo=FALSE>>=
<<xyplot>>
<<latticehyperlink>>
<<lh>>
@ 

\begin{figure}
\begin{center}
\hspace*{\fill}
{\includegraphics[width=5in]{latticehyper-with-cursor.png}}
\hspace*{\fill}
\end{center}
\caption{\label{figure:latticehyper}A \pkg{lattice} plot
with hyperlinks on the strip labels.}
\end{figure}

\section[The design of gridSVG]{The design of \pkg{gridSVG}}
\label{section:gridsvgdesign}

This section describes some of the details about how the
\pkg{gridSVG} package works.  It is necessary to understand
some of these details in order to be able to 
produce more complex dynamic and interactive plots with \pkg{gridSVG}.

\subsection[The components of a grid scene]{The components of a \pkg{grid} scene}

The \pkg{gridSVG} package works by looking at what has been drawn
on the current page and converting that drawing to \svg{}.
The \pkg{gridSVG} package works off the \pkg{grid} display list,
which is a record of all \pkg{grid} output on the current page.
This display list consists of \pkg{grid} viewports and grobs 
(graphical objects).  

The \code{grid.ls()} function can be used to list the grobs and viewports 
in the current scene and the following code demonstrates this for the 
simple scene from Figure~\ref{figure:gridscene}.  
There are two \code{rect} grobs,
called \code{toprect} and \code{botrect}, and each rectangle is drawn
in a its own viewport (\code{topvp} and \code{botvp}, respectively).

<<gridls, eval=FALSE>>=
grid.ls(viewports=TRUE, fullNames=TRUE, print=grobPathListing)
@ 

<<gridscenels, echo=FALSE>>=
grid.newpage()
<<gridscene>>
<<gridls>>
@ 

\subsection[Converting grobs to SVG]{Converting grobs to \svg{}}
\label{section:convertinggrobs}

The main function in the \pkg{gridSVG} package is called \code{gridToSVG()}.
This function takes each grob in the current scene
and converts it to one or more \svg{} elements.  


<<gridscenetosvg, eval=FALSE>>=
gridToSVG("gridscene.svg")
@ 

<<gridscenesvg, echo=FALSE, fig=TRUE, include=FALSE, width=2, height=2>>=
<<gridscene>>
<<gridscenetosvg>>
@ 

In the simple \pkg{grid}
scene shown in Figure~\ref{figure:gridscene}, 
each \code{rect} grob is converted to an \svg{} \code{<rect>} element,
as shown below.

<<echo=FALSE>>=
library("XML")
@ 

<<echo=FALSE>>=
presentationAttributes <-
    c("stroke", "stroke-opacity",
      "fill", "fill-opacity",
      "opacity",
      "font-weight", "font-style", "font-family", "fonts-size",
      "stroke-dasharray", "stroke-width",
      "stroke-linecap", "stroke-linejoin", "stroke-miterlimit")
removePresentation <- function(node) {
    removeAttributes(node, .attrs=presentationAttributes)
}
<<echo=FALSE>>=
gridscenesvg <- xmlParse("gridscene.svg")
toprect <- getNodeSet(gridscenesvg,
                      "//svg:rect[@id='toprect.1']",
                      c(svg="http://www.w3.org/2000/svg"))[[1]]
removePresentation(toprect)
botrect <- getNodeSet(gridscenesvg,
                      "//svg:rect[@id='botrect.1']",
                      c(svg="http://www.w3.org/2000/svg"))[[1]]
removePresentation(botrect)
@ 

Most grobs have an obvious correspondence to an \code{SVG} element 
like this
(see Table \ref{table:grobtosvg}), but there are some exceptions.  
For example, the many different sorts of \pkg{grid} line 
grobs all get converted to an \svg{} \code{<polyline>} element.  This includes
open \code{xspline} grobs (the smooth curve is stored as a series of 
short straight lines).

\begin{table}
\caption{\label{table:grobtosvg}The \svg{} elements that basic \pkg{grid}
grobs are converted into.}
\begin{center}
\begin{tabular}{l l} \hline
{\bf \pkg{grid} grob} & {\bf \svg{} element} \\ \hline
\code{rect} & \code{<rect>} \\
\code{circle} & \code{<circle>} \\
\code{lines} & \code{<polyline>} \\
\code{polyline} & \code{<polyline>} \\
\code{segments} & \code{<polyline>} \\
\code{xspline} & \code{<polyline>} or \code{<path>} \\
\code{polygon} & \code{<polygon>} \\
\code{path} & \code{<path>} \\
\code{raster} & \code{<image>} \\
\code{text} & \code{<g><g><text><tspan>} \\ \hline
\end{tabular}
\end{center}
\end{table}

Another exception is the \code{text} grob, which converts to a series
of nested \svg{} elements.  This is necessary in order to get the
size and orientation of the text correct.  For example, 
the following \pkg{grid} code produces a text grob.

<<textgrob>>=
grid.text("take me there", name="sampleText")
@ 

The \code{gridToSVG()} function converts this text to
 \svg{} elements shown below.

<<textgrobsvg, echo=FALSE, fig=TRUE, include=FALSE, width=2, height=2>>=
<<textgrob>>
gridToSVG("textgrob.svg")
@ 

<<echo=FALSE>>=
textgrobsvg <- xmlParse("textgrob.svg")
gsvg <- getNodeSet(textgrobsvg,
                   "//svg:g[@id='sampleText.1']",
                   c(svg="http://www.w3.org/2000/svg"))[[1]]
textsvg <- getNodeSet(gsvg, "svg:g/svg:text",
                      c(svg="http://www.w3.org/2000/svg"))[[1]]
devnull <- removePresentation(textsvg)
cat(saveXML(gsvg))
@ 

A \code{points} grob is also handled differently because different
data symbols consist of different shapes, so the \svg{} element
that is produced will depend on the choice of data symbol.
Some data symbols also consist of more than one shape,
for example, a circle with a plus inside it.  In those cases,
the \code{points} grob is converted to a \code{<g>} element
with several other elements inside it.  For example,
the following \pkg{grid} code draws two data symbols, one a simple circle
and one a combination of a circle and a plus (a vertical line and
a horizontal line; see Figure~\ref{figure:pointsgrob}).

<<pointsgrob, fig=TRUE, include=FALSE, width=1, height=1>>=
pushViewport(viewport())
grid.points(1:2/3, 1:2/3, pch=c(1, 10), name="symbols")
@ 

\begin{figure}
\hspace*{\fill}
\fbox{\includegraphics[width=1in]{gridsvg-pointsgrob}}
\hspace*{\fill}
\fbox{\includegraphics[width=1in]{gridsvg-arrowgrob}}
\hspace*{\fill}
\fbox{\includegraphics[width=1in]{gridsvg-circlegrob}}
\hspace*{\fill}
\caption{\label{figure:pointsgrob}Three simple grid scenes:
on the left, two data symbols (one a simple
circle and the other a combination of a circle and two lines); in the
middle, a line segment with an arrow head on the end; on the right,
three circles which are drawn from a single grob.}
\end{figure}

The \code{gridToSVG()} function converts these data symbols to the
 \svg{} elements shown below.

<<pointsgrobsvg, echo=FALSE, fig=TRUE, include=FALSE, width=2, height=2>>=
<<pointsgrob>>
gridToSVG("pointsgrob.svg")
@ 

<<echo=FALSE>>=
pointsgrobsvg <- xmlParse("pointsgrob.svg")
circlesvg <- getNodeSet(pointsgrobsvg,
                   "//svg:circle[@id='symbols.1']",
                   c(svg="http://www.w3.org/2000/svg"))[[1]]
removePresentation(circlesvg)
symbolsvg <- getNodeSet(pointsgrobsvg, 
                        "//svg:g[@id='symbols.2']",
                        c(svg="http://www.w3.org/2000/svg"))[[1]]
poly1svg <- getNodeSet(pointsgrobsvg, 
                       "//svg:polyline[@id='symbols.2.1']",
                       c(svg="http://www.w3.org/2000/svg"))[[1]]
devnull <- removePresentation(poly1svg)
poly2svg <- getNodeSet(pointsgrobsvg, 
                       "//svg:polyline[@id='symbols.2.2']",
                       c(svg="http://www.w3.org/2000/svg"))[[1]]
devnull <- removePresentation(poly2svg)
circle2svg <- getNodeSet(pointsgrobsvg, 
                         "//svg:circle[@id='symbols.2.3']",
                         c(svg="http://www.w3.org/2000/svg"))[[1]]
devnull <- removePresentation(circle2svg)
cat(saveXML(symbolsvg))
@ 

All line grobs in \pkg{grid} can have arrow heads at either end.
These are implemented in \svg{} using \code{<marker>} elements,
which are then referred to using \code{marker-start} and \code{marker-end}
attributes in the \code{<polyline>} element.  The following
\pkg{grid} code draws a line segment with an arrow at the end
(see Figure~\ref{figure:pointsgrob}).

<<arrowgrobsrc>>=
grid.segments(0, 0, 1, 1, arrow=arrow(), name="lineWithArrow")
@ 

<<arrowgrob, echo=FALSE, fig=TRUE, include=FALSE, width=1, height=1>>=
pushViewport(viewport(width=.8, height=.8))
<<arrowgrobsrc>>
@ 

This \code{segments} grob, with its arrow,
 is converted to the following \svg{} code.

<<arrowgrobsvg, echo=FALSE, fig=TRUE, include=FALSE, width=2, height=2>>=
<<arrowgrobsrc>>
gridToSVG("arrowgrob.svg")
@ 

<<echo=FALSE>>=
# Function to break a long line of SVG code
#   'text' is the SVG text (possibly containing newlines)
#   'element' gives the name of the element whose line we want to break
#             This is used to find the line to break
#   'attribs' gives one or more attribute names that want to break on
#   'anchor'  gives the attribute name that the new lines should line up with
breakLongLine <- function(text, element, attribs, anchor,
                          perl=FALSE) {
    text <- strsplit(text, "\n")[[1]]
    line <- grep(element, text, perl=perl)
    for (l in line) {
        newline <- text[l]
        indent <- regexpr(anchor, newline, perl=perl)
        for (i in attribs) {
            # Wrap attrib names in parentheses so can use \\1 in replacement text
            # This allows regular expression in attrib name
            newline <- gsub(paste("(", i, ")", sep=""), 
                            paste("\n", 
                                  paste(rep(" ", indent - 1), collapse=""),
                                  "\\1", sep=""),
                            newline, perl=perl)
        }
        text[l] <- newline
    }
    paste(text, collapse="\n")
} 
@ 

<<echo=FALSE>>=
arrowgrobsvg <- xmlParse("arrowgrob.svg")
markersvg <- getNodeSet(arrowgrobsvg, "//svg:defs",
                        c(svg="http://www.w3.org/2000/svg"))[[1]]
devnull <- removeChildren(markersvg, kids=list(1))
markerpathsvg <- getNodeSet(markersvg, "//svg:path",
                            c(svg="http://www.w3.org/2000/svg"))[[1]]
devnull <- removePresentation(markerpathsvg)
polylinesvg <- getNodeSet(arrowgrobsvg, "//svg:polyline",
                          c(svg="http://www.w3.org/2000/svg"))[[1]]
devnull <- removePresentation(polylinesvg)
cat(breakLongLine(saveXML(markersvg),
                  "<marker", c("overflow", "markerHeight"), "id"))
cat(breakLongLine(saveXML(polylinesvg),
                  "<polyline", "marker-end", "id"))
@ 

\subsection{Converting grobs that draw multiple shapes}

A single \pkg{grid} grob may produce several distinct shapes.
For example, the following code creates a single \code{circle}
grob, but three distinct circles are drawn
(see Figure~\ref{figure:pointsgrob}).

<<circlegrob, fig=TRUE, include=FALSE, width=1, height=1>>=
grid.circle(x=1:3/4, y=1:3/4, r=0.1, name="circles")
@ 

When this grob is converted to \svg{}, three distinct \code{<circle>}
elements are 
created.  Because it may be useful to treat the three elements as a
coherent group, the conversion nests the three \code{<circle>} elements
within a \code{<g>} element.  The resulting \svg{} code for this example
is shown below.

<<circlegrobsvg, echo=FALSE, fig=TRUE, include=FALSE, width=2, height=2>>=
<<circlegrob>>
gridToSVG("circlegrob.svg")
@ 

<<echo=FALSE>>=
circlegrobsvg <- xmlParse("circlegrob.svg")
gsvg <- getNodeSet(circlegrobsvg,
                   "//svg:g[@id='circles']",
                   c(svg="http://www.w3.org/2000/svg"))[[1]]
circlesvg <- getNodeSet(gsvg, "svg:circle",
                      c(svg="http://www.w3.org/2000/svg"))
devnull <- lapply(circlesvg, removePresentation)
cat(saveXML(gsvg))
@ 

For consistency in the \svg{} code, this \code{<g>} element is added
whether a grob produces multiple shapes or not.  For example,
the \code{toprect} grob from Figure~\ref{figure:gridscene}, which
produces only a single \code{<rect>} element, is actually recorded
in \svg{} as shown below.

<<echo=FALSE>>=
gridscenesvg <- xmlParse("gridscene.svg")
toprectg <- getNodeSet(gridscenesvg,
                      "//svg:g[@id='toprect']",
                      c(svg="http://www.w3.org/2000/svg"))[[1]]
toprect <- toprectg["rect"][[1]]
devnull <- removePresentation(toprect)
cat(saveXML(toprectg))
@ 

\subsection{Converting grob names}

Each \pkg{grid} grob has a name and this name gets recorded 
as the \code{id} attribute of the corresponding \svg{} element.
This conversion is slightly complicated by the fact that a single
grob always generates multiple \svg{} elements (as described in the
previous section), so some ``mangling'' of the original grob name 
is necessary.

The general rule is that the parent \code{<g>} element has 
an \code{id} attribute that is identical to the original grob name.
The children of that \code{<g>} element have \code{id} attributes
based on the original grob name, but with a numeric suffix appended.
The sample \svg{} code in the previous section demonstrates this idea.

Some cases are more complicated, for example, determining the \code{id} 
attributes of \code{<marker>} elements when converting lines with 
arrow heads (see Section \ref{section:convertinggrobs}), but
in all cases the \code{id} value is based upon the original grob name,
with a sensible extension added.

\subsection{Converting graphical parameters}

The detailed appearance of \pkg{grid} grobs---things like colours,
line widths, and fonts---is controlled by a set of graphical parameters,
such as \code{col} and \code{fill} (border and fill colours), 
\code{lwd} (line width), and \code{fontface} and \code{fontfamily}.

When a \pkg{grid} grob is converted to an \svg{} element, these 
graphical parameter settings are converted to \dfn{presentation attributes}
in the \svg{} element.  

There are always default graphical parameter settings in place so that a grob
will only specify explicit settings where necessary.  This is 
reflected in \svg{}, with presentation attributes only recorded
when they are explicitly set.  A top level \code{<g>} element
establishes a full set of defaults.

For example, 
in the simple \pkg{grid} scene from
Figure~\ref{figure:gridscene},
the \code{toprect} grob explicitly specifies a grey fill
via the \code{gp} argument.

<<eval=FALSE>>=
grid.rect(gp=gpar(fill="grey"), vp=topvp, name="toprect")
@ 

The top level \code{<g>} element and the \code{<rect>} element
for the \code{toprect} grob are shown below.
Many default presentation attribute settings are established
in the \code{<g>} element and the grey
fill for the \code{<rect>} element is recorded 
as \code{fill="rgb(190,190,190)"}.

{\small
<<echo=FALSE>>=
gridscenesvg <- xmlParse("gridscene.svg")
gridsvg <- getNodeSet(gridscenesvg,
                      "//svg:g[@id='gridSVG']",
                      c(svg="http://www.w3.org/2000/svg"))[[1]]
gridsvgchild <- getNodeSet(gridscenesvg,
                           "//svg:g[@id='gridSVG']/svg:g",
                           c(svg="http://www.w3.org/2000/svg"))[[1]]
toprect <- getNodeSet(gridscenesvg,
                      "//svg:rect[@id='toprect.1']",
                      c(svg="http://www.w3.org/2000/svg"))[[1]]
# Make the <rect> element the only child of the gridsvg element
devnull <- removeChildren(gridsvg, kids=xmlChildren(gridsvg))
devnull <- addChildren(gridsvg, kids=list(toprect))
cat(gsub(", ", ",", 
         gsub("</g>", "\n</g>",
              gsub("( +<rect)", "\n\\1",
                   breakLongLine(breakLongLine(saveXML(gridsvg),
                                               "<rect", 
                                               c("fill=", "fill-opacity"),
                                               "id"),
                                 "<g", 
                                 c("fill=", "stroke=", "stroke-dasharray",
                                   "font-size", 
                                   "font-family", 
                                   "(?<= )opacity", "stroke-linecap",
                                   "stroke-opacity"), 
                                 "id",
                                 perl=TRUE)))))
# Remove the children of the
@ 
}

In all other code samples in this article, these presentation attributes
have been removed to aid readability of the \svg{} code.

\subsection{Converting viewports}

A \pkg{grid} scene consists not only of grobs, but also viewports,
which provide contexts for drawing the grobs.
The conversion of grobs to \svg{} makes use of the viewports to 
determine the correct locations and sizes to use within the \svg{} elements,
but the viewports themselves 
are also recorded in the \svg{} code as \code{<g>} elements, 
with an \code{id} attribute set from the viewport name.

If a viewport sets the clipping region, a \code{<clipPath>} element
is added to the \svg{} output and this is referenced in the 
\code{<g>} element for the viewport using the \code{clip-path}
attribute.

We now have enough information to understand the
complete \svg{} code
that is produced by \code{gridToSVG()} for the simple \pkg{grid} scene
in Figure~\ref{figure:gridscene}.  This \svg{} code is shown
in Figure~\ref{figure:gridscenesvg}.

\begin{figure}
\begin{boxedminipage}{\textwidth}
<<echo=FALSE>>=
gridscenesvg <- xmlParse("gridscene.svg")
removeStyle <- function(node) {
    removePresentation(node)
    children <- xmlChildren(node)
    if (length(children) > 0)
        lapply(children, removeStyle)
    invisible()
}
invisible(lapply(xmlChildren(gridscenesvg), removeStyle))
cat(breakLongLine(saveXML(gridscenesvg),
                  "<svg", c("xmlns:xlink", "width"), "xmlns"))
@ 
\end{boxedminipage}
\caption{\label{figure:gridscenesvg}The \svg{} code that 
is generated by \code{gridToSVG()} from the simple \pkg{grid} scene
in Figure~\ref{figure:gridscene}.  All \code{style} attributes 
have been removed to improve readability.}
\end{figure}

\subsection{Converting gTrees}

A gTree is a grob that can have other grobs as its children.
For example, the following code creates a gTree that has a 
\code{text} grob and a \code{rect} grob as its children.

<<gtree>>=
tg <- textGrob("this is a gTree", name="textchild")
rg <- rectGrob(width=grobWidth(tg) + unit(2, "mm"), 
               height=unit(1, "lines"),
               gp=gpar(col=NA, fill="grey"), name="rectchild")
textWithBG <- gTree(children=gList(rg, tg), name="gtree")
@ 

When a gTree is drawn, it draws all of its children.  For
example, the following code calls the above function to
create a gTree and then draws it, which has the effect of
drawing both the text grob and the rect grob
(see Figure~\ref{figure:gtree}).

<<gtreefig, fig=TRUE, include=FALSE, width=2, height=1>>=
grid.draw(textWithBG)
@ 

\begin{figure}
\begin{center}
\fbox{\includegraphics[width=2in]{gridsvg-gtreefig}}
\end{center}
\caption{\label{figure:gtree}A \pkg{grid} scene
consisting of a gTree, with a rectangle and a piece of text as
its children.}
\end{figure}

The output from \code{grid.ls()} shows the hierarchical nature of the scene
just created.

<<gridls, eval=FALSE>>=
grid.ls(fullNames=TRUE)
@ 

<<echo=FALSE>>=
<<gtreefig>>
<<gridls>>
@ 

When a gTree is exported to \svg{}, the gTree itself creates a 
\code{<g>} element, with the child grobs exported as \svg{} elements 
within that.  The \svg{} code from the gTree created above is shown
below.

<<echo=FALSE>>=
grid.newpage()
<<gtreefig>>
gridToSVG("gtree.svg")
@ 

<<echo=FALSE>>=
gtreesvg <- xmlParse("gtree.svg")
gtree <- getNodeSet(gtreesvg,
                     "//svg:g[@id='gtree']",
                     c(svg="http://www.w3.org/2000/svg"))[[1]]
text <- getNodeSet(gtreesvg,
                   "//svg:text",
                   c(svg="http://www.w3.org/2000/svg"))[[1]]
devnull <- removePresentation(text)
rect <- getNodeSet(gtreesvg,
                   "//svg:rect",
                   c(svg="http://www.w3.org/2000/svg"))[[1]]
devnull <- removePresentation(rect)
cat(saveXML(gtree))
@ 

\subsection{Fonts}

The \pkg{gridSVG} package does not embed fonts in the 
\svg{} document that it produces.  It only records the name
of the font that should be used to render text.
Because there is no guarantee that a web browser (or the operating system
of its host) has access to a particular font, \pkg{gridSVG}
also records additional font names so that if the first font
cannot be found, there are alternatives that can be used.

The collection of font names is called a \dfn{font stack} and 
the \pkg{gridSVG} package maintains three font stacks:
one for serif fonts, one for sans-serif fonts, and one for
monospace fonts.  In each case, the final font name in each stack
is a generic name, like \code{"monospace"} so that the web browser
should always be able to find something to use.

When text is exported to \svg{}, the font stack that is recorded
is the one that contains the font family used for that text.
For example, the following code draws text with a Helvetica 
font.

<<font>>=
grid.text("font test", gp=gpar(fontfamily="Helvetica"),
          name="font")
@ 

The Helvetica font is part of the sans-serif font stack, so the
\svg{} code records the sans-serif font stack, as shown below
(see the \code{font-family} attribute within the \code{<text>}
element).

<<echo=FALSE>>=
grid.newpage()
<<font>>
gridToSVG("font.svg")
@ 

{\small
<<echo=FALSE>>=
fontsvg <- xmlParse("font.svg")
font <- getNodeSet(fontsvg,
                   "//svg:g[@id='font']",
                   c(svg="http://www.w3.org/2000/svg"))[[1]]
cat(gsub(", ", ",", 
         breakLongLine(saveXML(font),
                       "<text", c("font-family", "fill="), "x=")))
@ 
}

The default font stacks only contain some common font names (on the major
operating systems).  However, the \code{setSVGFonts()} function
is provided to allow further fonts to be added to the font stacks.
The \code{getSVGFonts()} function can be used to obtain the current font
stacks.  For example, the following code adds the Inconsolata font
to the monospace font stack.

<<>>=
fontstacks <- getSVGFonts()
fontstacks$mono <- c("Inconsolata", fontstacks$mono)
setSVGFonts(fontstacks)
@ 

The new monospace font stack is shown below.

<<>>=
getSVGFonts()$mono
@ 

Again, this does not guarantee that the Inconsolata font will be used
to display the text in a browser; that will only happen if the browser
has access to the Inconsolata font.

This concludes the discussion of how standard \pkg{grid} objects are
converted to \svg{}.  The following sections describe how \pkg{gridSVG} adds 
dynamic and interactive features to a \pkg{grid} scene and exports those 
features to \svg{} code.

\subsection{Hyperlinks}

The \code{grid.hyperlink()} function allows hyperlinks
to be associated with a component of a \pkg{grid} scene.
This function works by modifying the appropriate grob
to add information about the hyperlink.  The modified
grob is also given the class \code{linked.grob} so that it can be
handled differently when it is converted to \svg{}.
The conversion of a \code{linked.grob} to \svg{} creates an 
\code{<a>} (anchor) element around the normal
\svg{} elements that would otherwise be generated.

For example, the following code draws a piece of text and 
associates a hyperlink with the text so that when the text
is clicked with the mouse in a web browser, the browser
will navigate to the \R{} home page.

<<hypertext, fig=TRUE, include=FALSE>>=
grid.text("take me there", name="hypertext")
grid.hyperlink("hypertext", href="http://www.r-project.org")
@ 

The \code{text} grob is now a \code{linked.grob}.

<<gridget, eval=FALSE>>=
grid.get("hypertext")
@ 

<<echo=FALSE>>=
<<hypertext>>
<<gridget>>
@ 

The \code{gridToSVG()} function converts this \code{linked.grob}
to a set of \code{<tspan>}, \code{<text>}, and \code{<g>} elements
as normal, \emph{plus} an \code{<a>} element around the outside,
as shown below.

<<echo=FALSE>>=
grid.newpage()
<<hypertext>>
gridToSVG("hypertext.svg")
@ 

<<echo=FALSE>>=
hypertextsvg <- xmlParse("hypertext.svg")
anchor <- getNodeSet(hypertextsvg,
                     "//svg:a",
                     c(svg="http://www.w3.org/2000/svg"))[[1]]
text <- getNodeSet(hypertextsvg,
                   "//svg:text",
                   c(svg="http://www.w3.org/2000/svg"))[[1]]
devnull <- removePresentation(text)
cat(saveXML(anchor))
@ 

Placing the \svg{} anchor around the outside of the normal \svg{} output from
a grob means that we should be able to associate an anchor with 
any component of a \pkg{grid} scene.

\subsection{Animation}

The \pkg{gridSVG} package provides the \code{grid.animate()} function
for animating a \pkg{grid} grob.  This function works by 
modifying the appropriate grob to add attributes that contain
information about the animation.  The modified grob is also given the 
class \code{animated.grob} so that it can be handled differently
when it is converted to \svg{}.
The conversion of an \code{animated.grob} to \svg{} creates an
\code{<animate>} element in addition to the normal \svg{} elements
that would otherwise be generated. 

 For example, the following 
code draws a circle on the left of the screen and then animates
it so that it moves across to the right of the screen.

<<animcircle, fig=TRUE, include=FALSE>>= 
grid.circle(x=.2, r=.1, 
            gp=gpar(fill="black"), name="oneCircle")
grid.animate("oneCircle", x=c(.2, .8))
@ 

The \code{circle} grob is now an \code{animated.grob}.

<<gridget, eval=FALSE>>=
grid.get("oneCircle")
@ 

<<echo=FALSE>>=
grid.newpage()
<<animcircle>>
<<gridget>>
@ 

The \code{gridToSVG()} function converts this grob to a \code{<circle>}
element as normal, \emph{plus} an \code{<animate>} element, as shown below.

<<echo=FALSE>>=
grid.newpage()
<<animcircle>>
gridToSVG("animcircle.svg")
@ 

<<echo=FALSE>>=
animcirclesvg <- xmlParse("animcircle.svg")
animate <- getNodeSet(animcirclesvg,
                      "//svg:animate",
                      c(svg="http://www.w3.org/2000/svg"))[[1]]
cat(breakLongLine(saveXML(animate), 
                  "<animate", c("begin", "values"), "xlink"))
circleg <- getNodeSet(animcirclesvg,
                      "//svg:g[@id='oneCircle']",
                      c(svg="http://www.w3.org/2000/svg"))[[1]]
circle <- getNodeSet(animcirclesvg,
                     "//svg:circle[@id='oneCircle.1']",
                     c(svg="http://www.w3.org/2000/svg"))[[1]]
devnull <- removePresentation(circle)
cat(saveXML(circleg))
@ 

A more complex situation arises when
a grob generates more than one shape, and thereby generates 
more than one \svg{} element. In this case, animation values 
can be given for each individual shape by specifying
a matrix of animation values.  For example, the following code 
draws two circles, one at the bottom-left of the screen and one 
at the top-right, then animates
the circles so that the bottom-left circle moves to the bottom-right of
the screen
and the top-right circle moves to the top-left of the screen.

<<twocircles, fig=TRUE, include=FALSE>>= 
grid.circle(x=c(.2, .8), y=c(.2, .8), 
            r=.1, gp=gpar(fill="black"), name="twoCircles")
@ 

The first column of the matrix is used as animation values for
the first circle and the second column is used for the second circle.
The first circle will transition from an x-value of \code{.2} to
an x-value of \code{.8}, while the second circle transitions 
from \code{.8} to \code{.2}.

<<animvalues>>=
animValues <- cbind(c(.2, .8), c(.8, .2))
animValues
@ 
<<animtwocircles, eval=FALSE>>=
grid.animate("twoCircles", x=animValues)
@ 

The \code{gridToSVG()} function converts this grob to two \code{<circle>}
elements plus two \code{<animate>} elements, as shown below.

<<echo=FALSE>>=
grid.newpage()
<<twocircles>>
<<animtwocircles>>
gridToSVG("twocircles.svg")
@ 

<<echo=FALSE>>=
twocirclessvg <- xmlParse("twocircles.svg")
animate <- getNodeSet(twocirclessvg,
                      "//svg:animate",
                      c(svg="http://www.w3.org/2000/svg"))
invisible(lapply(animate, 
                 function(x) { 
                     cat(breakLongLine(saveXML(x), 
                                       "<animate", 
                                       c("begin", "values"), 
                                       "xlink"),
                         "\n")
                 }))
circleg <- getNodeSet(twocirclessvg,
                      "//svg:g[@id='twoCircles']",
                      c(svg="http://www.w3.org/2000/svg"))[[1]]
circle1 <- getNodeSet(twocirclessvg,
                     "//svg:circle[@id='twoCircles.1']",
                     c(svg="http://www.w3.org/2000/svg"))[[1]]
circle2 <- getNodeSet(twocirclessvg,
                     "//svg:circle[@id='twoCircles.2']",
                     c(svg="http://www.w3.org/2000/svg"))[[1]]
devnull <- removePresentation(circle1)
devnull <- removePresentation(circle2)
cat(saveXML(circleg))
@ 

It is also possible to specify an animation for an entire 
set of shapes at once, by specifying \code{TRUE} for the 
\code{group} argument.  For example, the following code 
draws two circles which \emph{both} disappear after 1 second.

<<animgroupcircles, eval=FALSE>>=
grid.circle(x=c(.2, .8), y=c(.2, .8), 
            r=.1, gp=gpar(fill="black"), name="groupCircles")
grid.animate("groupCircles", 
             visibility=c("visible", "hidden"),
             begin=1, duration=0.01,
             group=TRUE)
@ 
The \svg{} code produced for this example has an \code{<animate>}
element that refers to the parent \code{<g>} element rather than
the individual \code{<circle>} elements, as shown below.

<<echo=FALSE>>=
grid.newpage()
<<animgroupcircles>>
gridToSVG("groupcircles.svg")
@ 

<<echo=FALSE>>=
groupcirclessvg <- xmlParse("groupcircles.svg")
animate <- getNodeSet(groupcirclessvg,
                      "//svg:animate",
                      c(svg="http://www.w3.org/2000/svg"))
invisible(lapply(animate, 
                 function(x) { 
                     cat(breakLongLine(saveXML(x), 
                                       "<animate", 
                                       c("begin", "values"), 
                                       "xlink"),
                         "\n")
                 }))
circleg <- getNodeSet(groupcirclessvg,
                      "//svg:g[@id='groupCircles']",
                      c(svg="http://www.w3.org/2000/svg"))[[1]]
circle1 <- getNodeSet(groupcirclessvg,
                     "//svg:circle[@id='groupCircles.1']",
                     c(svg="http://www.w3.org/2000/svg"))[[1]]
circle2 <- getNodeSet(groupcirclessvg,
                     "//svg:circle[@id='groupCircles.2']",
                     c(svg="http://www.w3.org/2000/svg"))[[1]]
devnull <- removePresentation(circle1)
devnull <- removePresentation(circle2)
cat(saveXML(circleg))
@ 

For some shapes, for example polygons, a single shape requires 
multiple x-values and multiple y-values.  This means that, even when
animating a single shape, a vector of values is required at each time
point.  For the simple case of a single shape of this sort, using a 
matrix for the animation values will still work because 
\code{grid.animate()} will treat each column of the matrix as a different
time point (rather than each column being a different shape).

However, for the case of animating a grob that produces multiple shapes,
where each shape requires multiple values at each time point, specifying
the animation values via vectors or matrices becomes limiting.
Furthermore, the animation examples shown so far have actually only
involved simple numeric vectors, but features like the x-location of a 
grob need to be specified as \code{unit} objects, so \code{grid.animate()}
has been doing some work behind the scenes to extract an appropriate
coordinate system for the animation.

A more explicit way to express the animation values is to use
the \code{animUnit()} function to create an \code{animUnit} object.
For example, the simple set of animation values for a single circle
could be generated with the following code.  This specifies
a single value for each of two time points.

<<>>=
animUnit(unit(c(.2, .8), "npc"))
@ 

The following code generates a single value for each of two time points,
for each of two shapes.  The \code{id} argument to the
\code{animUnit()} function is used to associate different animation
values with different shapes.

<<>>=
animUnit(unit(c(.2, .8, .8, .2), "npc"), id=rep(1:2, each=2))
@ 

The following code demonstrates how to generate multiple values
for each time point, by specifying the \code{timeid} argument, 
which associates different animation values with different time 
points.

<<>>=
animUnit(unit(c(.2, .8, .8, .2), "npc"), timeid=rep(1:2, each=2))
@ 

By specifying \emph{both} \code{timeid} and \code{id} arguments,
it is possible to specify multiple animation values at each time point
for different shapes, as shown below.

<<>>=
animUnit(unit(c(.2, .8, .8, .2, .1, .9, .9, .1), "npc"), 
         timeid=rep(rep(1:2, each=2), 2), 
         id=rep(1:2, each=4))
@ 

Not all features of a grob are locations or dimensions (which require
\code{unit} values), so there is also an \code{animValue()} function
for generating sets of non-\code{unit} animation values.
The vignette \code{"animation"} in the \pkg{gridSVG} package
describes these functions in more detail.

\subsection{Interactivity}

The general mechanism for adding interactivity to a \pkg{grid}
scene involves associating \js{} code \citep{bib:JavaScriptGuide}
with a component of
the \pkg{grid} scene.  This usually requires two steps:
adding \js{} code to the scene and specifying which
component of the scene will call that \js{} code (and when).

The first step is straightforward.  The 
\code{grid.script()} function adds a \code{script.grob} object
to the current \pkg{grid} scene (nothing is drawn on screen,
but the grob is added to the \pkg{grid} display list).
The \js{} code for the \code{script.grob} object can be specified
as a character vector or as the name of a file that contains
\js{} code.  For example, the following code adds \js{} code
to a scene from the file called \code{"script.js"}.

<<gridscript>>=
grid.script(filename="script.js", name="script")
@ 

The \code{gridToSVG()} function generates a \code{<script>} element
from the \code{script.grob} object.  By default, if the \js{} code
is from an external file, the \code{<script>} element just provides
a reference to the external file, as shown below.

<<echo=FALSE>>=
grid.newpage()
<<gridscript>>
gridToSVG("script.svg")
@ 

<<echo=FALSE>>=
scriptsvg <- xmlParse("script.svg")
script <- getNodeSet(scriptsvg,
                     "//svg:script",
                     c(svg="http://www.w3.org/2000/svg"))[[1]]
cat(saveXML(script))
@ 

If the \js{} code is specified as a character vector or, if
the code is in an external file, but the \code{inline} argument
is set to \code{TRUE}, then the \js{} code is embedded in the
\svg{} document.  For example, the following code
creates a simple script that will be directly embedded in the
\svg{} output.

<<scriptembed>>=
grid.script("document.onload = alert('hi');",
            name="embeddedScript")
@ 

The resulting \svg{} code is shown below.  When the \svg{} document
is loaded by a browser, an alert dialog will immediately pop up.

<<echo=FALSE>>=
grid.newpage()
<<scriptembed>>
gridToSVG("scriptEmbed.svg")
@ 

<<echo=FALSE>>=
scriptembedsvg <- xmlParse("scriptEmbed.svg")
scriptembed <- getNodeSet(scriptembedsvg,
                          "//svg:script",
                          c(svg="http://www.w3.org/2000/svg"))[[1]]
cat(saveXML(scriptembed))
@ 

The second step in adding interactivity to a \pkg{grid} scene
is to specify which component of the scene will run the
\js{} code (and when).  This is achieved with the 
\code{grid.garnish()} function, which works by
modifying a grob to add attributes that specify when the grob
will call \js{} code.  The modified grob is also given the 
class \code{garnished.grob} so that it can be handled differently
when it is converted to \svg{}.
The conversion of a \code{garnished.grob} to \svg{} creates 
the normal \svg{} elements
that would otherwise be generated, but adds extra \svg{} attributes
to the elements.  

For example, the following 
code draws a circle in the middle of the screen and then 
adds an attribute so that when the circle is clicked with the mouse
in a web browser, an alert dialog will pop up.

<<gridgarnish>>=
grid.circle(r=.1, gp=gpar(fill="black"), name="clickme")
grid.garnish("clickme", 
             onmousedown="alert('ouch!')",
             "pointer-events"="all")
@ 

The \code{gridToSVG()} function converts the garnished
 grob to a \code{<circle>}
element within a \code{<g>} element as normal, 
but with \code{onmousedown} and \code{pointer-events}
attributes added to the \code{<g>} element, as shown below.

<<echo=FALSE>>=
grid.newpage()
<<gridgarnish>>
gridToSVG("gridgarnish.svg")
@ 

<<echo=FALSE>>=
gridgarnishsvg <- xmlParse("gridgarnish.svg")
circleg <- getNodeSet(gridgarnishsvg,
                      "//svg:g[@id='clickme']",
                      c(svg="http://www.w3.org/2000/svg"))[[1]]
circle <- getNodeSet(gridgarnishsvg,
                     "//svg:circle",
                     c(svg="http://www.w3.org/2000/svg"))[[1]]
devnull <- removePresentation(circle)
cat(saveXML(circleg))
@ 

The following code shows how \code{grid.script()}
and \code{grid.garnish()} can be combined so that a 
component of a \pkg{grid} scene can be set up to call
\js{} code from a script that has been added to the scene.
In this case, a \code{circle} grob will call the \js{} 
function \code{allwhite()} when the mouse is clicked within the
circle and the \code{allwhite()} function is defined
in a \code{script.grob} object within the scene.

<<gridinteract>>=
grid.circle(r=.1, gp=gpar(fill="black"), name="clickme")
grid.garnish("clickme", onmousedown="allwhite()")
grid.script("
  allwhite = function() {
    circle = document.getElementById('clickme.1');
    circle.setAttribute('style', 'fill:white');
  }", name="allwhite")
@ 

The \svg{} generated from this scene is shown in Figure 
\ref{figure:gridinteract}.  An important feature of the 
\js{} code is that it refers to the relevant \svg{}
element by name (\code{"clickme.1"}).  We will return
to this point in Section \ref{section:discussion}.

<<echo=FALSE>>=
grid.newpage()
<<gridinteract>>
gridToSVG("gridinteract.svg")
@ 

\begin{figure}
\begin{boxedminipage}{\textwidth}
<<echo=FALSE>>=
gridinteractsvg <- xmlParse("gridinteract.svg")
removeStyle <- function(node) {
    if (is(node, "XMLInternalElementNode")) {
        removePresentation(node)
        children <- xmlChildren(node)
        if (length(children) > 0)
            lapply(children, removeStyle)
    }
    invisible()
}
invisible(lapply(xmlChildren(gridinteractsvg), removeStyle))
cat(breakLongLine(saveXML(gridinteractsvg),
                  "<svg", c("xmlns:xlink", "width"), "xmlns"))
@ 
\end{boxedminipage}
\caption{\label{figure:gridinteract}The \svg{} code that 
is generated by \code{gridToSVG()} from a \pkg{grid} scene
consisting of a garnished \code{circle} grob and a \code{script.grob}.}
\end{figure}

Another important feature of the code in Figure~\ref{figure:gridinteract}
is that the \code{onmousedown} attribute has been added to the
\code{<g>} element parent, not the \code{<circle>} element
itself.  In some circumstances, this is very useful.  For example,
the following code draws three circles with one \pkg{grid} call
and then associates an interaction with all three circles at once.

<<threecircles>>=
grid.circle(x=1:3/4, r=.1, gp=gpar(fill="black"),
            name="threeCircles")
grid.garnish("threeCircles", 
             onmousedown="alert('ouch')")
@ 

The \svg{} version of this scene is shown below, with three
\code{<circle>} elements nested within a \code{<g>} element.
Because the \code{onmousedown} attribute is added to the \code{<g>}
parent of the the \code{<circle>} elements, an alert dialog will pop up
when \emph{any} of the three circles is clicked with the mouse.

<<echo=FALSE>>=
grid.newpage()
<<threecircles>>
gridToSVG("threeCircles.svg")
@ 

<<echo=FALSE>>=
threecirclessvg <- xmlParse("threeCircles.svg")
circleg <- getNodeSet(threecirclessvg,
                      "//svg:g[@id='threeCircles']",
                      c(svg="http://www.w3.org/2000/svg"))[[1]]
circle1 <- getNodeSet(threecirclessvg,
                     "//svg:circle[@id='threeCircles.1']",
                     c(svg="http://www.w3.org/2000/svg"))[[1]]
devnull <- removePresentation(circle1)
circle2 <- getNodeSet(threecirclessvg,
                     "//svg:circle[@id='threeCircles.2']",
                     c(svg="http://www.w3.org/2000/svg"))[[1]]
devnull <- removePresentation(circle2)
circle3 <- getNodeSet(threecirclessvg,
                     "//svg:circle[@id='threeCircles.3']",
                     c(svg="http://www.w3.org/2000/svg"))[[1]]
devnull <- removePresentation(circle3)
cat(saveXML(circleg))
@ 

However, it is also possible to make \code{grid.garnish()} add 
attributes to the child elements rather than to the parent \code{<g>}.
For example, the following code again draws three circles,
but then associates a different interaction with each circle,
by specifying three values for the \code{onmousedown} attribute
and setting the \code{group} argument to \code{FALSE}.


<<diffcircles>>=
grid.circle(x=1:3/4, r=.1, gp=gpar(fill="black"),
            name="diffCircles")
grid.garnish("diffCircles", 
             onmousedown=c("alert('click me!')",
                           "alert('no, click me!')",
                           "alert('no, no, click me!')"),
             group=FALSE)
@ 

The \svg{} version of this scene is shown below, with the 
\code{onmousedown} attributes set on
\code{<circle>} elements rather than on the \code{<g>} element.

<<echo=FALSE>>=
grid.newpage()
<<diffcircles>>
gridToSVG("diffCircles.svg")
@ 

<<echo=FALSE>>=
diffcirclessvg <- xmlParse("diffCircles.svg")
circleg <- getNodeSet(diffcirclessvg,
                      "//svg:g[@id='diffCircles']",
                      c(svg="http://www.w3.org/2000/svg"))[[1]]
circle1 <- getNodeSet(diffcirclessvg,
                     "//svg:circle[@id='diffCircles.1']",
                     c(svg="http://www.w3.org/2000/svg"))[[1]]
devnull <- removePresentation(circle1)
circle2 <- getNodeSet(diffcirclessvg,
                     "//svg:circle[@id='diffCircles.2']",
                     c(svg="http://www.w3.org/2000/svg"))[[1]]
devnull <- removePresentation(circle2)
circle3 <- getNodeSet(diffcirclessvg,
                     "//svg:circle[@id='diffCircles.3']",
                     c(svg="http://www.w3.org/2000/svg"))[[1]]
devnull <- removePresentation(circle3)
cat(breakLongLine(saveXML(circleg),
                  "<circle", "onmousedown", "id"))
@ 

\subsection{Custom grobs}

It is possible to create a new class of grob, typically when
the grob has to perform calculations every time it is drawn.
For example, the following code defines a new \code{boxedtext} class
that consists of nothing but a label.

<<boxedtext>>=
bt <- grob(label="this is a label", name="bt",
           cl="boxedtext")
@ 

This grob will create a \code{text} and \code{rect} grob every time it is
drawn, which is one way to make sure that the \code{rect} grob is
always the right size for the text.  This is achieved by writing
a \code{drawDetails()} method for the \code{boxedtext} class, as shown below.

<<btgrob>>=
btgrob <- function(x) {
    tg <- textGrob(x$label, name="text")
    rg <- rectGrob(width=grobWidth(tg) + unit(2, "mm"), 
                   height=unit(1, "lines"),
                   gp=gpar(col=NA, fill="grey"), name="box")
    gTree(children=gList(rg, tg), name=x$name)
}
@ 

<<drawdetails>>=
drawDetails.boxedtext <- function(x, ...) {
    grid.draw(btgrob(x))
}
@ 

Whenever the \code{boxedtext} grob is drawn, the \code{drawDetails()} method
is called.  The following code draws \code{bt} and then edits it to change
the label and, because the \code{text} and \code{rect} grobs are 
recreated each time, the \code{rect} grob automatically scales to 
accommodate the text (see Figure~\ref{figure:drawdetails}).

<<editsrc>>=
grid.draw(bt)
grid.edit("bt", label="New label!")
@ 

<<edit, echo=FALSE, results=hide>>=
pdf("gridsvg-edit-%d.pdf", width=2, height=1, onefile=FALSE)
<<editsrc>>
dev.off()
@ 

\begin{figure}
\hspace*{\fill}
\fbox{\includegraphics[width=2in]{gridsvg-edit-1}}
\hspace*{\fill}
\fbox{\includegraphics[width=2in]{gridsvg-edit-2}}
\hspace*{\fill}
\caption{\label{figure:drawdetails}A \pkg{grid} scene
consisting of a new \code{boxedtree} grob (on the left).
On the right, the \code{boxedtree} grob has been edited to change
the label (and the rectangle has automatically scaled to fit the new
label).}
\end{figure}

This sort of new grob class presents a problem for \pkg{gridSVG} 
because it does not know how to convert the \code{boxedtext} grob
(which only consists of a label) into \svg{} code.  The solution 
is to define a \code{primToDev()} method for the \code{boxedtext}
grobs.  This is the generic function that converts grobs into \svg{}
code and a new method can be written quite easily by generating
standard \pkg{grid} grobs and calling \code{primToDev} on those grobs
(much like a \code{drawDetails()} method). 
The following code does this for the \code{boxedtext} class.

<<primtodev>>=
primToDev.boxedtext <- function(x, ...) {
    primToDev(btgrob(x), ...)
}
@ 

With that method defined, \pkg{gridSVG} will export \svg{}
code based on the \code{text} and \code{rect} grobs produced by
the  \code{btgrob()} function, as shown below.

<<echo=FALSE>>=
grid.newpage()
grid.draw(bt)
gridToSVG("boxedtext.svg")
@ 

<<echo=FALSE>>=
boxedtextsvg <- xmlParse("boxedtext.svg")
btg <- getNodeSet(boxedtextsvg,
                      "//svg:g[@id='bt']",
                      c(svg="http://www.w3.org/2000/svg"))[[1]]
text <- getNodeSet(boxedtextsvg,
                   "//svg:text",
                   c(svg="http://www.w3.org/2000/svg"))[[1]]
devnull <- removePresentation(text)
rect <- getNodeSet(boxedtextsvg,
                   "//svg:rect",
                   c(svg="http://www.w3.org/2000/svg"))[[1]]
devnull <- removePresentation(rect)
cat(saveXML(btg))
@ 

In addition to the generic function \code{primToDev()}, there are
also generic functions \code{animate()} and \code{garnish()} to allow
new grob classes to be animated and garnished.  The \code{"extensibility"} 
vignette in the \pkg{gridSVG} package describes these functions in more
detail.

\section{Examples}
\label{section:examples}

This section describes two, more advanced examples of using
the \pkg{gridSVG} package.

\subsection{Animations for teaching}

\cite{RSSA:RSSA678} describe a number of animations to be used 
in developing students' intuition about inference.  One example
\citep[Figure 10 of][]{RSSA:RSSA678} shows a barplot of samples from
a single categorical variable.  The bars transition from one sample to
the next and leave a ``footprint'' consisting of a horizontal line 
at the top of the bar.

To produce an \svg{} version of this animation using \pkg{gridSVG},
we start  with
data that consists of a list of counts for each
of five categories.

<<echo=FALSE>>=
# Just enough code to get some sample output
# FULL code in Examples/Wild/

modes <- c("walk", "car", "bus", "bike", "other")
travel <- factor(rep(modes,
                     c(7349, 8992, 6486, 1156, 263+311+384)))
# Take many samples from the pop and tabulate them
n <- 100
sn <- 100
samples <- lapply(1:n, function(i) { table(sample(travel, sn)) })
@ 

<<>>=
samples[1:3]
@ 

The following code generates a \pkg{lattice} barplot from the first
set of sample data to provide the basis 
of the animation (see Figure~\ref{figure:barchart}).

<<barchart, fig=TRUE, include=FALSE>>=
boxWidth <- unit(2, "cm")
barchart(samples[[1]],
         col=rgb(0,0,1,.2),
         ylim=c(0, max(sapply(samples, max))),
         horizontal=FALSE,
         box.width=boxWidth)
@ 

\begin{figure}
\hspace*{\fill}
\fbox{\includegraphics[width=2in]{gridsvg-barchart}}
\hspace*{\fill}
\caption{\label{figure:barchart}A \pkg{lattice} barplot
that provides the basis for an animated barplot 
(see Figure~\ref{figure:wild}).}
\end{figure}

The next code shows how the heights of the bars can be animated
using the \pkg{gridSVG} package.  This code identifies the 
grob to animate, which is a \code{rect} grob that draws the five
bars in the plot, and provides a set of animation values for
the heights of those bars (a matrix with five columns;  each column
provides animation values for one bar).

<<eval=FALSE>>=
time <- 10
grid.animate("plot_01.barchart.rect.panel.1.1",
             height=do.call("rbind", samples),
             duration=time, interpolate="discrete")
@ 

The ``footprints'' left behind after each step in the animation
are horizontal line segments.  The following code adds these 
segments to the basic plot (see Figure~\ref{figure:footprints}).

<<footprintsrc, eval=FALSE>>=
trellis.focus("panel", 1, 1)
count <- 1
samplefun <- function(samp) {
    grid.segments(unit(1:5, "native") - 0.5*boxWidth,
                  unit(samp, "native"), 
                  unit(1:5, "native") + 0.5*boxWidth,
                  unit(samp, "native"),
                  gp=gpar(lwd=2, col=rgb(0,0,1,.2)),
                  name=paste("sample.line", count, sep="."))
    count <<- count + 1
}    
lapply(samples, samplefun)
trellis.unfocus()
@ 

<<footprints, echo=FALSE, results=hide>>=
pdf("gridsvg-footprints-%d.pdf", onefile=FALSE)
<<barchart>>
<<footprintsrc>>
dev.off()
@ 

\begin{figure}
\hspace*{\fill}
\fbox{\includegraphics[width=2in]{gridsvg-footprints-1}}
\hspace*{\fill}
\caption{\label{figure:footprints}The \pkg{lattice} barplot
from Figure~\ref{figure:barchart}, with horizontal line segments
added.  These line segments will be animated to leave
``footprints'' in the animated barplot 
(see Figure~\ref{figure:wild}).}
\end{figure}

The footprints are made to appear at the appropriate times
by animating their \code{visibility} attribute, as shown by the 
following code.

<<animatefootprints, eval=FALSE>>=
for (i in 1:n) {
    grid.garnish(paste("sample.line", i, sep="."),
                 visibility="hidden")
    grid.animate(paste("sample.line", i, sep="."),
                 visibility=c("hidden", "visible"),
                 group=TRUE,
                 begin=i/n*time,
                 duration=.01)
}
@ 

Figure~\ref{figure:wild} shows snapshots of the animation 
and the live \svg{} file, plus full \R{} code, is available with the online
resources for this paper.

\begin{figure}
\hspace*{\fill}
{\includegraphics[width=2in]{Examples/Wild/wild1.png}}
\hspace*{\fill}
{\includegraphics[width=2in]{Examples/Wild/wild2.png}}
\hspace*{\fill}
\caption{\label{figure:wild}Some snapshots from an animation
showing barplots of samples from a single categorical variable.}
\end{figure}

\subsection[A grid object browser]{A \pkg{grid} object browser}

One of the obstacles to overcome when animating or garnishing a 
\pkg{grid} scene is determining the name of the grob that we wish
to animate or garnish.  For example, the following code 
generates a relatively complex plot using \pkg{ggplot2}
(see Figure~\ref{figure:ggplot}).

<<>>=
library("ggplot2")
@ 

<<qplotsrc>>=
qplot(disp, mpg, data=mtcars) + facet_wrap(~ cyl)
@ 

<<qplot, echo=FALSE, fig=TRUE, include=FALSE>>=
print(
<<qplotsrc>>
)
@ 

\begin{figure}
\begin{center}
{\includegraphics[width=4in]{gridsvg-qplot}}
\end{center}
\caption{\label{figure:ggplot}A relatively complex \pkg{ggplot2}
plot.}
\end{figure}

This plot has many components (over 100).  
The first few are shown below (the indenting of some of the 
lines in that display indicates that the grobs are collected 
together in a gTree).

<<eval=FALSE>>=
grid.ls()
@ 

<<echo=FALSE, results=hide>>=
print(
<<qplotsrc>>
)
x <- grid.ls()
y <- lapply(x, "[", 1:5)
class(y) <- "flatGridListing"
# Capture the display list so can reuse it later
DL <- grid:::grid.Call("L_getDisplayList")
DLi <- grid:::grid.Call("L_getDLindex")
@ 

<<echo=FALSE>>=
y
@ 

One way to help explore the many grobs in this plot is to generate
an \svg{} version of the plot with tooltips so that when the mouse
hovers over a grob a tooltip is displayed to show the name of the grob.
The following code performs this task.  First of all, the names
of all ``leaf'' grobs are obtained (all grobs that are not gTrees).

<<gridlsgrobs, eval=FALSE>>=
grobs <- grid.ls()
names <- grobs$name[grobs$type == "grobListing"]
@ 

Now we garnish all of those grobs so that they will respond to
the mouse by showing a tooltip.

<<ggplotgarnish, eval=FALSE>>=
for (i in unique(names)) {
    grid.garnish(i, 
                 onmouseover=paste("showTooltip(evt, '", i, "')"),
                 onmouseout="hideTooltip()")
}
@ 

Finally, we add a script file that contains the \js{} code to draw the 
tooltips and export the whole scene to \svg{}.  A snapshot of
the result, as viewed in a browser, is shown in Figure
\ref{figure:ggplotbrowser}.

<<qplotbrowser, eval=FALSE>>=
grid.script(filename="tooltip.js")
gridToSVG("qplotbrowser.svg")
@ 

<<echo=FALSE, results=hide>>=
# Restore exact display list 
# (otherwise auto-generated grob names are different)
grid.newpage()
devnull <- grid:::grid.Call("L_setDisplayList", DL)
devnull <- grid:::grid.Call("L_setDLindex", as.integer(DLi))
<<gridlsgrobs>>
names <- names[names != "NULL"]
<<ggplotgarnish>>
<<qplotbrowser>>
@ 

\begin{figure}
\begin{center}
{\includegraphics[width=4in]{qplotbrowser-with-cursor.png}}
\end{center}
\caption{\label{figure:ggplotbrowser}An \svg{} version of the 
plot in Figure~\ref{figure:ggplot} with tooltips added to show the 
name of the grob over which the mouse is hovering.}
\end{figure}

A live version of this plot is available with the online
resources for this paper.

% \pkg{lattice} multipanel version of GapMinder ?

% Auckland campus map

% gridTree() with tooltips

% interactive ggplot2 plot with slider!

\section{Discussion}
\label{section:discussion}

The \pkg{gridSVG} package is not the only package that
provides tools for generating
dynamic and interactive \R{} graphics for inclusion in web pages.
This section looks more closely at where the approach taken in 
\pkg{gridSVG} provides advantages over other approaches and where
it is weaker than other approaches.

\subsection[Avoiding the R graphics engine]{Avoiding the \R{} graphics engine}

An important feature of the \pkg{gridSVG} package is that it 
works directly from the \pkg{grid} display list.  
This is in contrast to packages that provide an
\R{} graphics device, like \pkg{RSVGTipsDevice},
which work from the graphics calls made by the
\R{} graphics engine.  Figure~\ref{figure:design} shows a diagram
of this difference.

<<design, echo=FALSE, fig=TRUE, include=FALSE, height=3>>=
textBox <- function(label, x, y) {
    grid.roundrect(x, y, height=unit(1, "lines"),
              width=stringWidth(label) + unit(2, "mm"),
              name=label,
              gp=gpar(fill="white"))
    grid.text(label, x, y)
}
lineBetween <- function(from, to, afrom, ato) {
    grid.segments(grobX(from, afrom), grobY(from, afrom),
                  grobX(to, ato), grobY(to, ato),
                  arrow=arrow(length=unit(3, "mm"), angle=10,
                    type="closed"),
                  gp=gpar(fill="black"))
}
grid.newpage()
grid.roundrect(.1, .5, width=.4, height=.4,
               just="left",
               gp=gpar(col=NA, fill="grey80"))

textBox("graphics", .2, .6)
textBox("grid", .2, .4)

textBox("grDevices", .4, .5)
lineBetween("graphics", "grDevices", 0, 180)
lineBetween("grid", "grDevices", 0, 180)

nright <- 4
maxright <- 50 
minright <- -50
t <- seq(minright, maxright, length.out=nright)
x <- .5 + cos(t/180*pi)*.3
y <- .5 + sin(t/180*pi)*.4
right <- c("PDF", "PNG", "SVG", "RSVGTipsDevice")
for (i in 1:nright) {
    textBox(right[nright - i + 1], x[i], y[i])
    lineBetween("grDevices", right[nright - i + 1], 0, 
                switch(as.character(i), "1"=90, 180))
}

textBox("gridSVG", .4, .2)
lineBetween("grid", "gridSVG", 0, 90)
@

\begin{figure}
\begin{center}
\includegraphics[width=.7\textwidth]{gridsvg-design}
\end{center}
\caption{\label{figure:design}The organisation of graphics packages,
which shows that \pkg{gridSVG} works directly from the \pkg{grid} display list
whereas graphics devices work from the \R{} graphics engine
(the \pkg{grDevices} package).}
\end{figure}

The significance of this approach is that \pkg{gridSVG} is working with
much richer information.  The \pkg{grid} display list contains a higher-level
description of the current scene than the \R{} graphics engine.  
For example, the following code draws a set of three data symbols
(see Figure~\ref{figure:gridsymbols}).

<<gridsymbolssrc, eval=FALSE>>=
grid.points(1:3/4, 1:3/4, pch=10, name="points")
@ 

<<gridsymbols, echo=FALSE, fig=TRUE, include=FALSE, width=9, height=3>>=
pushViewport(viewport(layout=grid.layout(1, 3)))
pushViewport(viewport(layout.pos.col=1))
grid.rect(width=.9, height=.9)
grid.points(1:3/4, 1:3/4, pch=10)
popViewport()
pushViewport(viewport(layout.pos.col=2))
grid.rect(width=.9, height=.9)
grid.rect(y=.95, height=unit(1.5, "lines"), just="top", width=.9,
          gp=gpar(fill="black"))
grid.text("grid display list",
          y=unit(.95, "npc") - unit(.75, "lines"),
          gp=gpar(col="white"))
grid.text("\"points\" grob",
          y=unit(.95, "npc") - unit(2.5, "lines"), just="top")
popViewport()
pushViewport(viewport(layout.pos.col=3))
grid.rect(width=.9, height=.9)
grid.rect(y=.95, height=unit(1.5, "lines"), just="top", width=.9,
          gp=gpar(fill="black"))
grid.text("R graphics engine",
          y=unit(.95, "npc") - unit(.75, "lines"),
          gp=gpar(col="white"))
grid.text("circle\nline\nline\ncircle\nline\nline\ncircle\nline\nline",
          y=unit(.95, "npc") - unit(2.5, "lines"), just="top")
@ 

\begin{figure}
{\includegraphics[width=\textwidth]{gridsvg-gridsymbols}}%
\caption{\label{figure:gridsymbols}A set of three data symbols (left)
is recorded as a single named grob on the \pkg{grid} display list, but
gets reduced to 9 separate shapes in the \R{} graphics engine.}
\end{figure}

On the \pkg{grid} display list, these data symbols are represented
as a single grob, called \code{points}, 
but the \R{} graphics engine breaks them into 
9 separate unnamed shapes (3 circles, 3 vertical lines, and 3
horizontal lines).  In the latter case, it is very difficult to
identify the 9 shapes as a coherent set, but by working off the
\pkg{grid} display list, it is straightforward for the \pkg{gridSVG}
package to identify the data symbols, which makes it possible to
animate or garnish the data symbols as a coherent set of shapes.

Because \pkg{gridSVG} has richer information to work with,
there are more things that it can (easily) do and, at the same time,
\pkg{gridSVG}'s internal algorithms can be relatively straightforward.
That in turn means that the low-level infrastructure of \pkg{gridSVG}
can be exposed and explained to the user (as shown in 
Section \ref{section:gridsvgdesign}), which means that the
user can participate in the development of new uses for \pkg{gridSVG}.
This is also reflected in the small set of fundamental \pkg{gridSVG} functions
(\code{grid.hyperlink()}, \code{grid.animate()}, \code{grid.garnish()},
and \code{gridToSVG()}).

\subsection[Generating SVG code directly]{Generating \svg{} code directly}

Another consequence of working directly off the \pkg{grid} display list is that
\pkg{gridSVG} has complete control over the \svg{} code that it generates.
This is in contrast to the \pkg{SVGAnnotation} package, which works
off the \svg{} code that is generated by the \R{} graphics engine.
Figure~\ref{figure:envy} shows a diagram of this difference.

\begin{figure}
\begin{center}
\begin{boxedminipage}{.7\textwidth}
~\\
\begin{center}
\R{} graphics engine $\rightarrow$ \svg{} $\rightarrow$ \pkg{SVGAnnotation} $\rightarrow$ \svg{}
\end{center}
\begin{center}
\pkg{grid} display list $\rightarrow$ \pkg{gridSVG} $\rightarrow$ \svg{}
\end{center}
~
\end{boxedminipage}
\end{center}
\caption{\label{figure:envy}A comparison of \pkg{gridSVG}, which works
off the \pkg{grid} display list and produces \svg{} directly, and 
\pkg{SVGAnnotation}, which works with the \svg{} that is produced by the 
\R{} graphics engine and produces new \svg{} code from that.}
\end{figure}

Two main advantages flow from this:  the structure of the
\svg{} code that \pkg{gridSVG} 
produces can reflect the structure of the original image; and
the \svg{} elements that \pkg{gridSVG} produces have \code{id} 
attributes that reflect the names of the grobs in the original scene.
Together, these make it much easier to work with the \svg{} code that is
produced by \pkg{gridSVG}. 
Figure~\ref{figure:gridscenesvg}, which shows the \svg{} code generated
by \pkg{gridSVG} for the simple \pkg{grid} scene in Figure 
\ref{figure:gridscene}, demonstrates both of these ideas.

 By way of comparison, Figure 
\ref{figure:gridsceneCairo} shows the \svg{} code that the \R{}
graphics engine produces from the simple \pkg{grid} scene in Figure
\ref{figure:gridscene}. 
The \pkg{SVGAnnotation} package has to work much harder to identify 
meaningful components of the original scene from the \svg{}
because the structure of the code does not relate as well to the 
structure of the original scene and because there are no useful 
\code{id} attributes to label components.  As a specific example,
the two rectangles in the original scene in Figure~\ref{figure:gridscene}
are represented by four \code{path} elements in the \svg{} code
in Figure~\ref{figure:gridsceneCairo}.

\begin{figure}
<<echo=FALSE, results=hide>>=
svg("gridsceneCairo.svg", width=2, height=2)
<<gridscene>>
dev.off()
@ 
\begin{boxedminipage}{\textwidth}
{\small
<<echo=FALSE>>=
gridscenesvg <- xmlParse("gridsceneCairo.svg")
removeStyle <- function(node) {
    removeAttributes(node, .attrs="style")
    children <- xmlChildren(node)
    if (length(children) > 0)
        lapply(children, removeStyle)
    invisible()
}
invisible(lapply(xmlChildren(gridscenesvg), removeStyle))
cat(breakLongLine(breakLongLine(saveXML(gridscenesvg),
                                "<svg", c("xmlns:xlink", "width"), "xmlns"),
                  "<path", "transform", "d"))
@ 
}
\end{boxedminipage}
\caption{\label{figure:gridsceneCairo}The \svg{} code that 
is generated by the \cairo{}-based \code{svg()} graphics device
 from the simple \pkg{grid} scene
in Figure~\ref{figure:gridscene}. All \code{style} attributes 
have been removed to improve readability. }
\end{figure}

The predictable structure and useful labelling of the \svg{} code 
that is produced by \pkg{gridSVG} makes it possible to convey
the structure (as shown in Section \ref{section:gridsvgdesign}),
which makes it possible for non-expert users to work with the
\svg{} code that is produced by \pkg{gridSVG}.  This is important
in understanding the \code{grid.animate()} and
\code{grid.garnish()} functions \emph{and} in writing \js{} code
to implement interactive features of a scene
\emph{and} in working with the \svg{} code more generally 
(see Section \ref{section:xml}).

\subsection{Generality}

The two previous sections have emphasized that it is not enough to be
able to export \svg{} output from \R{} graphics; a great deal can be 
gained if that \svg{} output is also sensibly structured and labelled.

The \pkg{gridSVG} approach provides a general solution to exporting 
\svg{} output in the sense that it will
export the structure and labelling of \emph{any} \pkg{grid} scene.
As long as the \pkg{grid} scene has a clear hierarchical structure (as in
\pkg{ggplot2} plots) or a clear labelling scheme (as in \pkg{lattice}
plots), that structure and labelling will be translated to the
\svg{} document that \pkg{gridSVG} creates.  

This is a significant
step forward from packages that work off the \R{} graphics engine
because, in that case, almost all structure and
labelling from the original scene is lost.  
The solutions provided by these packages
cannot be as general because the package has to be told
what functions were used to draw a scene in order to know how to
recover structure from the neutered information that is provided by the 
\R{} graphics engine.

For example, the 
\pkg{SVGAnnotation} package has to be ``trained'' to handle the output 
from different sorts of plots.  An impressive amount of work has been
done to provide useful high-level functions for a range of plots
already, but expanding the scope of the package requires extra effort
\emph{and} detailed expert knowledge.

The \pkg{iWebPlots} package has a similar problem because 
it has to match the calculations done by the original plot 
in order to reverse
engineer the locations of elements of the plot within a raster image.
This means not only training the package for each different sort of
plot, but it also limits the components that can be made interactive.
For example, it is difficult to recover the positions of axis labels
within a raster image.

\subsection[The power of XML]{The power of \xml{}}
\label{section:xml}

The fact that \pkg{gridSVG} produces \svg{} code, 
and the fact that the \svg{} code is predictable, coherently structured, 
and labelled, 
means that there are significant opportunities for working
with an \svg{} document after it has been produced by \pkg{gridSVG}.

This opportunity arises because \svg{} is a dialect of \xml{} 
\citep{bib:XMLNutshell}
and there are extremely powerful tools for working with
\xml{} code, such as \xpath{} and \xpointer{} 
\citep{bib:XPathXPointer}.

As an example, we will look at some of the set up of an interactive
\pkg{ggplot2} plot.  The scene consists of two plots, 
one above the other, where the upper plot shows a zoomed 
region of the lower plot.  The lower plot has a ``thumb'' rectangle
which the user can slide to determine which region of the lower
plot is shown in the upper plot (a snapshot of this interactive scene
 is shown in Figure
\ref{figure:ggplotsnapshot}).

\begin{figure}
\begin{center}
{\includegraphics[width=4in]{ggplotsnapshot-with-cursor.png}}
\end{center}
\caption{\label{figure:ggplotsnapshot}A snapshot of an interactive
\pkg{ggplot2} scene.  The user slides the blue rectangle in the
lower plot and the upper plot shows a zoomed view corresponding
to the blue rectangle.}
\end{figure}

The data used in this scene is a data frame version of the
\code{Nile} time series and the plot is just a simple line plot.

<<>>=
df <- data.frame(time=as.numeric(time(Nile)), 
                 flow=as.numeric(Nile))
thePlot <- ggplot(df, aes(x=time, y=flow)) + 
           geom_line() 
botPlot <- thePlot 
@ 

<<echo=FALSE>>=
# Fine tune lower plot:
# invisibilize y-axis label, thin y-axis scale, and remove x-axis
botPlot <- thePlot +
           scale_y_continuous(breaks=c(600, 1200)) +
           opts(plot.background=theme_rect(colour="transparent"),
                axis.title.y=theme_text(colour="white", size=6),
                axis.title.x=theme_blank())
@ 

The arrangement of the plots is achieved using \pkg{grid} viewports
and an \svg{} version is generated with the code below
(see top plot in Figure~\ref{figure:ggplotslider}).

<<>>=
doplot <- function() {
    pushViewport(viewport(y=1, height=.8, just="top", 
                          name="topvp"))
    print(thePlot, newpage=FALSE)
    upViewport()
    pushViewport(viewport(y=0, height=.25, just="bottom", 
                          name="bottomvp"))
    print(botPlot, newpage=FALSE)
    upViewport()
}
@ 


<<results=hide>>=
pdf(width=4, height=4)
doplot()
gridToSVG("normalplot.svg")
dev.off()
@ 

A zoomed version of the scene is generated by drawing the same scene
on a much wider device (see the middle plot in 
Figure~\ref{figure:ggplotslider}).

<<results=hide>>=
pdf(width=12, height=4)
doplot()
gridToSVG("wideplot.svg")
dev.off()
@ 

Now we can begin to take advantage of the fact that the \svg{} code
is \xml{} code.  The \pkg{XML} package \citep{pkg:xml} 
provides access to several
of the \xml{} processing tools.

<<>>=
library("XML")
@ 

The first step is to read the normal scene and the zoomed scene into \R{}.

<<>>=
normalSVG <- xmlParse("normalplot.svg")
wideSVG <- xmlParse("wideplot.svg")
@ 

Next, we identify the section of \svg{} code that corresponds to the 
data region in the top plot of the normal scene.  This makes use 
of \xpath{} to find the \code{<g>} element with an \code{id} attribute
of \code{panel-3-3.1} (determined by inspecting the \svg{} code).

<<results=hide>>=
normalPlotSVG <- 
    getNodeSet(normalSVG,
               "//svg:g[@id='panel-3-3.1']",
               c(svg="http://www.w3.org/2000/svg"))[[1]]
@ 

We can identify the contents of the same region in the zoomed scene
with similar code.

<<results=hide>>=
widePlotSVG <- 
    getNodeSet(wideSVG,
               "//svg:g[@id='panel-3-3.1']/svg:g[@id='panel-3-3']",
               c(svg="http://www.w3.org/2000/svg"))[[1]]
@ 

<<echo=FALSE, results=hide>>=
# To set clip attribute for axis viewport,
# need the x, y, width, height from background rect for panel-3-3
# (which is first <rect> below panel-3-3)
# BEFORE we replace that with the one from fancyWide.svg!
panelBg  <- getNodeSet(normalPlotSVG,
                       ".//svg:rect",
                       c(svg="http://www.w3.org/2000/svg"))[[1]]
# Do same thing for x-axis
normalAxisSVG <- getNodeSet(normalSVG,
                            "//svg:g[@id='axis_h-5-3.1']",
                            c(svg="http://www.w3.org/2000/svg"))[[1]]
wideAxisSVG <-
    getNodeSet(wideSVG,
               "//svg:g[@id='axis_h-5-3.1']/svg:g[@id='axis_h-5-3']",
               c(svg="http://www.w3.org/2000/svg"))[[1]]
removeChildren(normalAxisSVG, "g")
addChildren(normalAxisSVG, wideAxisSVG)
# Set a clip region for the x-axis on the top plot
axisClipRectAttrs <- xmlAttrs(panelBg)[c("x", "y", "width", "height")]
axisClipRectAttrs["height"] <- axisClipRectAttrs["y"]
axisClipRectAttrs["y"] <- 0
addChildren(normalAxisSVG,
            newXMLNode("clipPath",
                       newXMLNode("rect",
                                  attrs=axisClipRectAttrs),
                       attrs=c(id="axis_h-5-3.1-clip")))
addAttributes(normalAxisSVG,
              "clip-path"="url(#axis_h-5-3.1-clip)")
@ 

Now all we have to do is remove the original data region and replace
it with the zoomed data region.  The following code does that and
writes out the result to a new \svg{} document
(see the bottom plot in .
Figure~\ref{figure:ggplotslider}).

<<results=hide>>=
removeChildren(normalPlotSVG, "g")
addChildren(normalPlotSVG, widePlotSVG)
saveXML(normalSVG, file="customplot.svg")
@ 

<<echo=FALSE>>=
system("inkscape --export-png=normalplotsvg.png --export-dpi=300 normalplot.svg")
system("inkscape --export-png=wideplotsvg.png --export-dpi=300 wideplot.svg")
system("inkscape --export-png=customplotsvg.png --export-dpi=300 customplot.svg")
@ 

\begin{figure}
\begin{center}
{\includegraphics[width=1.5in]{normalplotsvg.png}}

\vspace{.2in}
{\includegraphics[width=4.5in]{wideplotsvg.png}}

\vspace{.2in}
{\includegraphics[width=1.5in]{customplotsvg.png}}
\end{center}
\caption{\label{figure:ggplotslider}The top plot shows a \pkg{ggplot2} scene
consisting of two plots, one above the other.  The middle plot shows 
the same scene, just drawn much wider.  The bottom plot shows a
modification of the top
scene, with the original plot region replaced with the plot region
from the middle scene. }
\end{figure}

The complete interactive plot, plus \R{} code, is available with the online
resources for this paper.

\subsection{Drawbacks}

The first major limitation of the \pkg{gridSVG} package is that
it can only export \pkg{grid} scenes.  It will completely
ignore any drawing done by the traditional graphics system 
(the \pkg{graphics} package).  This is not a limitation
suffered by the  packages \pkg{SVGAnnotation}, 
\pkg{RSVGTipsDevice}, or \pkg{iWebPlots}.

A secondary issue is that the usefulness of the package
depends on grobs being sensibly named.  This is fortunately not 
an issue if we call \pkg{grid} functions directly to draw a scene
(because we can simply supply names ourselves), and the 
\pkg{lattice} package and (to a lesser extent) the \pkg{ggplot2} package
have named most of the grobs that they create when drawing.
However, there are other packages that do not name grobs and that
will limit what can be done to animate or interact with scenes
drawn by those packages.

Another major weakness of the \pkg{gridSVG} approach is that
it is focused on producing 
self-contained \svg{} documents;  the document has 
to contain \emph{all} of the data and graphics
required for any animation or interaction.
This has several negative consequences:
there is a limit to how much interactivity can be added to a plot,
because the document has to contain all possible graphics that might be
generated in response to user input,
and the documents that are produced tend to be large.
The verbosity of the \svg{} format does not help with the latter problem
(though compression to an \proglang{SVGZ} format can be very effective).

It is in theory possible to have \R{} in the background,
either on a web server or embedded in the web browser,
so that the content of the \svg{} document can be generated
or updated on-the-fly,
but the generation of scenes
 is almost certainly too slow to provide sufficiently responsive interaction.
This approach is never going to compete with interactive systems like
\pkg{iplots} \citep{pkg:iplots} or \ggobi{} \citep{bib:gGobi}.

Another issue with the \pkg{gridSVG} approach is that,
in order to implement any non-trivial interaction, we have to write
\js{} code.  It also helps to have an basic understanding of the 
structure of \svg{} code.  These place an additional burden on the
user, although some relief may be provided if a body of generic 
\js{} code can be built up and shared amongst users.
It should also be possible to build a layer of canned dynamic 
or interactive plot templates as higher-level \R{} functions.

There are some features still missing from the package. A significant
one is a lack of support for mathematical formulas (see \code{?plotmath}).
It is hoped that it will be possible to add support based on the
\proglang{MathJax} library \citep{bib:MathJax}.

It is also arguably a weakness that \pkg{gridSVG} only provides
low-level infrastructure for creating animated and interactive plots;
\pkg{gridSVG} does not contain any high-level functions that
generate complete animated or interactive plots.

Finally, because fonts are not embedded in the \svg{} document, 
the positioning of text in a scene may not be exact.

\section{Summary}

The \pkg{gridSVG} package converts any \pkg{grid} scene to 
an \svg{} document.  The \code{grid.hyperlink()} function
allows a hyperlink to be associated with any component of the scene,
the \code{grid.animate()} function can be used to animate any component
of a scene, and the \code{grid.garnish()} function can be used to 
add \svg{} attributes to the components of a scene.
By setting event handler attributes on a component, plus
possibly using the \code{grid.script()} function to add \js{} to the scene,
it is possible
to make the component respond to user input such as mouse clicks.

\bibliography{gridsvg}

\end{document}