\documentclass{article}
\usepackage[T1]{fontenc}
\usepackage{Sweave}
\usepackage{thumbpdf}
\usepackage{url}
%\usepackage{wrapfig}
\usepackage{hyperref}

\hypersetup{
  pdftitle={Introduction to googleVis},%
  pdfauthor={Markus Gesmann},%
}

%\VignetteEngine(Sweave)
%!\VignetteEncoding{UTF-8}
%\VignetteIndexEntry{Introduction to googleVis}
%\VignetteDepends{googleVis}
%\VignetteKeywords{google, visualisation, api}
%\VignettePackage{googleVis}


\SweaveOpts{engine=R, eps=FALSE, keep.source = TRUE}
<<options, echo=FALSE>>=
options(prompt = "R> ", digits = 4, show.signif.stars = FALSE)
@


%\keywords{google, visualisation, api, \proglang{R}}

\setlength{\parindent}{0.0in}
\setlength{\parskip}{2mm}

\newcommand{\googleVis}{\textbf{\texttt{googleVis}} }
\newcommand{\knitr}{\textbf{\texttt{knitr}} }
\newcommand{\rsp}{\textbf{\texttt{R.rsp }}}
\newcommand{\brew}{\textbf{\texttt{brew }}}
\newcommand{\rapache}{\emph{{RApache }}}
\newcommand{\Rook}{\emph{{Rook }}}
\newcommand{\shiny}{\textbf{\texttt{shiny }}}

\renewcommand{\familydefault}{\sfdefault}

\begin{document}
\SweaveOpts{concordance=TRUE}

\author{Markus Gesmann\footnote{markus.gesmann@gmail.com},
  Diego de Castillo\footnote{decastillo@gmail.com}}
\title{Introduction to googleVis \Sexpr{packageDescription("googleVis")[['Version']]}
}
\maketitle
\begin{abstract}
  The \googleVis package provides an interface between R and the
  Google Charts API. Google Charts offer interactive
  charts which can be embedded into web pages. The best 
  known of these charts is probably the Motion Chart, popularised 
  by Hans Rosling in his TED talks. 
 
  The functions of the \googleVis package allow the user to visualise
  data stored in R data frames with Google Charts
  without uploading the data to Google. The output of a \googleVis
  function is HTML code that contains the data and references to
  JavaScript functions hosted by Google.
  
  googleVis makes use of the internal R HTTP server to display the
  output locally. A modern browser with an Internet connection is
  required and for some charts a Flash player.
	     
\end{abstract}

\clearpage
\tableofcontents
\clearpage

\section{Introduction}\label{sec:Intro}

\subsection{Motivation}\label{sec:Motivation}
More and more data is becoming available, and yet
stories and insights are still often missed: we are lost in the data
jungle and struggle to see the wood for the trees. 

Hence, new tools are required to bring data to life, to engage with
users, to enable them to slice and dice the data, to view it from
various angles and to find stories worth telling: outliers, trends or
even the obvious. 

In 2006 Hans Rosling gave an inspiring talk at
TED~\cite{HansRoslingTedTalk} about social and economic developments
in the world over the past 50 years, which challenged the views and
perceptions of many listeners. Rosling had used extensive data analysis
to reach his conclusions.  To visualise his talk, he and his team at
Gapminder~\cite{Gapminder} had developed animated bubble charts, aka
motion charts, see Figure~\ref{MotionChartGUI}. 

Rosling's presentation popularised the idea and use of interactive
charts. One year later the software behind
Gapminder was bought by Google and integrated as motion charts into
their Google Charts API~\cite{GoogleVisApi}, formerly known as Google
Visualisation API.  

In 2010 Sebasti\'{a}n P\'{e}rez Saaibi~\cite{Saaibi2010} presented at the 
R/Rmetrics Workshop on  Computational Finance and Financial
Engineering, the idea to use Google motion charts to visualise R
output with the \rsp package~\cite{Rsp}. 

Inspired by those talks and the desire to use interactive data
visualisation tools to foster the dialogue between data analysts and
others the authors of this vignette started the development of the
\googleVis package~\cite{googleVis},
\cite{RJournal:2011-2:GesmannCastillo} in August 2010. 

\begin{figure}[t]
\begin{center}
\includegraphics[width=\textwidth]{./figures/MotionChart.pdf}
\caption{
  Overview of a Google Motion Chart.  Screenshot of the output of
  \texttt{plot(gvisMotionChart(Fruits, idvar='Fruit', timevar='Year'))}
}\label{MotionChartGUI}
\end{center}
\end{figure}
%\clearpage

\subsection{Google Chart Tools}\label{sec:GoogleChartTools}

The Google Charts API~\cite{GoogleVisApi}
allows users to create interactive charts as part of Google
documents, spreadsheets and web pages. In this text, we will focus 
on the usage of the API as part of web pages.

The Google Public Data Explorer~\cite{GooglePublicData} provides a
good example, demonstrating the use of interactive charts and how they can
help to analyse data. Please note, that all of those charts are
rendered by the browser.

The charting data can either be embedded into the HTML file or read
dynamically. The key to the Google Charts is that the data is
structured in a DataTable~\cite{DataTable}, and this is where the \googleVis
package helps, as it transforms R data frames into JSON~\cite{json}
objects, using the \texttt{\textbf{jsonlite}} package~\cite{jsonlite}, as
the basis for a DataTable. 

As an example we shall look at the html-code of a motion chart from
Google's visualisation gallery~\cite{GoogleMotionChart}, which
generates output similar to Figure~\ref{MotionChartGUI}:

\begin{small}\label{motionchartcodeexample}
\begin{verbatim}
 1 <html>
 2  <head>
 3   <script type="text/javascript" 
 4     src="http://www.google.com/jsapi">
 5   </script>
 6   <script type="text/javascript">
 7     google.load('visualization', '1', 
 8      {'packages':['motionchart']});
 9    google.setOnLoadCallback(drawChart);
10    function drawChart() {
11    var data=new google.visualization.DataTable();
12    data.addColumn('string', 'Fruit');
13    data.addColumn('date', 'Date');
14    data.addColumn('number', 'Sales');
15    data.addColumn('number', 'Expenses');
16    data.addColumn('string', 'Location');
17    data.addRows([
18    ['Apples',new Date(1988,0,1),1000,300,'East'],
19    ['Oranges',new Date(1988,0,1),1150,200,'West'],
20    ['Bananas',new Date(1988,0,1),300,250,'West'],
21    ['Apples',new Date(1989,6,1),1200,400,'East'],
22    ['Oranges',new Date(1989,6,1),750,150,'West'],
23    ['Bananas',new Date(1989,6,1),788,617,'West']
24    ]);
25    var chart=new google.visualization.MotionChart(
26      document.getElementById('chart_div'));
27    chart.draw(data, {width: 600, height:300});
28   }
29   </script>
30  </head>
31  <body>
32   <div id="chart_div" 
33        style="width:600px; height:300px;">
34   </div>
35  </body>
36 </html>
\end{verbatim}
\end{small}
The code and data are processed and rendered by the browser and is
not submitted to any server\footnote{\url{https://google-developers.appspot.com/chart/interactive/docs/gallery/motionchart.html\#Data\_Policy}}. 

You will notice that the above HTML code has five generic
parts\footnote{For more details see
\url{https://google-developers.appspot.com/chart/interactive/docs/index}}:
\begin{itemize}
\item references to Google's AJAX (l. 4) and Visualisation
  API (ll. 7 -- 8),
%%shown here as \verb=jsapi= and \verb='motionchart'=,

\item data to visualise as a \verb=DataTable= (ll. 11 -- 24),

\item an instance call to create the chart (ll. 25 -- 26),

\item a method call to draw the chart including options, shown
  here as width and height (l. 27),
 
\item an HTML \verb=<div>= element to add the chart to the page (ll.
  32 -- 34).
\end{itemize}
These principles hold true for most of the interactive charts of the
Google Chart Tools, see the examples in Figure~\ref{demos}.

However, before you use the API you should read the \href{https://developers.google.com/terms/}{Google
  Terms of Service}~\cite{GoogleTerms}. 

\section{The \googleVis package}\label{sec:googleVisPackage}


The \googleVis package provides an interface between R and the Google
Chart Tools.  The functions of the package allow the user to
visualise data stored in R data frames with Google Charts.

Version (\Sexpr{packageDescription("googleVis")[['Version']]}) of the package
provides interfaces to  Motion Charts, Annotated Time Lines, 
Maps, Geo Maps, Geo Charts, Intensity Maps, Tables, Gauges, 
Tree Maps, further Line, Bar, Bubble, Column, Area, Stepped Area, 
Combo, Scatter, Candlestick, Pie, Sankey, Annotation, 
Histogram, Timeline, Calendar and Org Charts; see 
Figure~\ref{demos} for some examples. 

The output of a \googleVis function is HTML code that contains the
data and references to JavaScript functions hosted by Google. A
browser with an Internet connection is required to view
the output, and for Motion Charts, Geo Maps, and Annotated Time Lines
also Flash. For Geo Maps and Annotated Time Lines HTML5 alternatives are available with Geo Charts and Annotation Charts. 

<<eval=FALSE, echo=FALSE>>=
## Code for screen shot
MC <- gvisMotionChart(Fruits, "Fruit", "Year", options=list(width=500, height=300))
ATL <- gvisAnnotatedTimeLine(Stock, datevar="Date",
                           numvar="Value", idvar="Device",
                           titlevar="Title", annotationvar="Annotation",
                           options=list(
                             width=300, height=300,
                             fill=10, displayExactValues=TRUE,
                             colors="['#0000ff','#00ff00']")
                           )
                          
Map <- gvisMap(Andrew, "LatLong" , "Tip",
              options=list(showTip=TRUE, showLine=TRUE, enableScrollWheel=TRUE,
                           mapType='terrain', useMapTypeControl=TRUE,
                           width=400, height=200))
Geo <- gvisGeoMap(Exports, locationvar='Country', numvar='Profit',
                 options=list(dataMode="regions", width=400,height=200)) 

## Table with enabled paging
Table <- gvisTable(Population, options=list(page='enable', height=200, width=500))

Tree <- gvisTreeMap(Regions,  "Region", "Parent", "Val", "Fac",
                    options=list(width=300, height=200,
                                 fontSize=16,
                                 minColor='#EDF8FB',
                                 midColor='#66C2A4',
                                 maxColor='#006D2C',
                                 headerHeight=20,
                                 fontColor='black',
                                 showScale=TRUE))

M <- gvisMerge(gvisMerge(gvisMerge(MC, ATL, TRUE, tableOptions="cellspacing=10"), 
                         gvisMerge(Map, Geo, TRUE, tableOptions="cellspacing=10")), 
                         gvisMerge(Table, Tree, TRUE, tableOptions="cellspacing=10"))
plot(M)
@ 
\begin{figure}[t]
\begin{center}
\includegraphics[width=\textwidth]{./figures/googleVisDemoPlots.pdf}
\caption{
  Screenshot of some of the outputs of \texttt{demo(googleVis)}.
  Clockwise from top left:
  \texttt{gvisMotionChart}, \texttt{gvisAnnotatedTimeLine}, 
  \texttt{gvisGeoMap}, \texttt{gvisTreeMap}, \texttt{gvisTable}, and \texttt{gvisMap}.
}\label{demos}
\end{center}
\end{figure}

\subsection{Installation}\label{sec:Installation}
You can install \googleVis in the usual way from CRAN, e.g.:
<<eval=FALSE>>=
install.packages('googleVis') 
@
The installation was successful if the
command \texttt{library(googleVis)} gives you the following message:
<<echo=FALSE, quite=TRUE>>=
library(googleVis)
@ 
<<eval=FALSE>>=
library(googleVis)
@ 
<<echo=FALSE>>=
cat(googleVis:::gvisWelcomeMessage())
@ 

\subsection{Using the  \googleVis package}\label{sec:UsingGoogleVis}

The individual functions of the \googleVis package are documented in
the help pages. Here we will cover only the principles of
the package.

As an example, we will show how to generate a motion chart as displayed in   
Figure~\ref{MotionChartGUI}. It works similarly for the other
APIs. Further examples are covered in the demos\footnote{See
  \texttt{demo(package="googleVis")} for a list of the available demos.} of the \googleVis
package.

The design of the visualisation functions is fairly generic. The name
of the visualisation function is \texttt{'gvis' + ChartType}. So for
the Motion Chart we have: 
\begin{verbatim}
gvisMotionChart(data, idvar='id', timevar='date', 
                options=list(), chartid)
\end{verbatim}
Here \texttt{data} is the input \texttt{data.frame} and \texttt{idvar}
and \texttt{timevar} specify the column names of the id variable and
time variable for the plot, while display options are set in an
optional list, which we discuss in more detail on
page~\pageref{settingoptions}. The options and data requirements
follow those of the Google Charts API  and are documented in the
help pages, see 
<<eval=FALSE>>=
help('gvisMotionChart')
@ 

\begin{figure}%{r}{0.35\textwidth}
\begin{center}
\includegraphics[width=0.34\textwidth]{./figures/gvisObject.pdf}
\caption{Schematic structure of a gvis list object.
}\label{gvisObject}
\end{center}
\end{figure}

The argument \texttt{chartid}  allows the user to set a chart id of the
output chart manually. If the argument is missing a random id using 
\texttt{tempfile(pattern=\textquotesingle\textquotesingle)}  
will be generated. Unique chart ids are required to place more than
one chart on a web page. 

The output of a \googleVis function is a list of lists (a nested list)
containing information about the chart type, chart id and the HTML
code in a  sub-list with header, chart, caption and footer, see Figure~\ref{gvisObject}.

The idea behind this concept is that users can get a
complete web page, while at the same time offer a facility to extract 
specific parts, such as the chart itself. 
This is particularly helpful if the package functions
are used in solutions where the user wants to feed the visualisation
output into other sites, or would like to embed them into rsp-pages
(see page~\pageref{rspexample}),  use \rapache (see
page~\pageref{rapacheexample}) or Google Gadgets.  

The output of a \googleVis function will be of class \texttt{'gvis'}
and \texttt{'list'}. Generic print (\texttt{print.gvis})  and plot
(\texttt{plot.gvis}) functions exist to ease the handling of such objects. 

To illustrate the concept we shall create a motion chart using the
\texttt{Fruits} data set. 

\subsection{Motion Chart Example}\label{sec:MotionChartExample}

Following the documentation of the Google Motion Chart API we need a
data set which has at least four columns: one identifying the
variable we would like to plot, one time variable and at least two
numerical variables, further numerical and character columns are allowed.

As an example we use the \texttt{Fruits} data set:
<<>>=
data(Fruits)
Fruits
@

Here we will use the columns \texttt{'Fruit'} and
\texttt{'Year'} as id and time variable respectively. However we could
have used \texttt{'Date'} instead of \texttt{'Year'} as well. 

<<>>=
 M <- gvisMotionChart(Fruits, idvar="Fruit", timevar="Year")
@
The structural output of \texttt{gvisMotionChart} is a list of lists as
described above 
<<eval=FALSE>>=
 str(M)
@ 
<<echo=FALSE>>=
## This statement avoids truncation
cat(paste(substring( capture.output( str(M) ) , 0, 66), sep="\n", collapse="\n"))
@ 
The first two items of the list contain information about the chart type
used and the individual chart id: %generated at run time from the chart
%type and \texttt{tempfile(pattern=\textquotesingle\textquotesingle)}:
<<>>=
M$type
M$chartid
@ 
The html output is a list with header, chart, caption and
footer. This allows the user to extract only certain parts
of the page, or to create a complete html page. 

The header part of the html page has only basic html and formatting tags: 
<<>>=
print(M, tag='header')
@ 
Here we used the \texttt{print} statement with the tag
\texttt{'header'} instead of \texttt{M\$html\$header} to achieve
a formatted screen output. This is the same output as
\texttt{cat(M\$html\$chart)}. 

The actual Google visualisation code is stored with the data
as a named character vector in the \texttt{chart} item of the HTML
list. The chart is made up of several JavaScript and  HTML
statements. Please notice that the JavaScript functions are  
uniquely named with the information of the chart id.
This concept allows the user get all the chart code directly or only
specific parts; see the examples in the help page of \texttt{print.gvis}
for more details.
<<>>=
names(M$html$chart)
@ 
The complete chart can be displayed via:
<<>>=
print(M, tag='chart')  ## or cat(M$html$chart)
@
Similarly you can also access specific components of the chart, e.g. (output  truncated)
<<eval=FALSE>>=
cat(M$html$chart['jsChart']) # or print(M, 'jsChart')
@ 
<<echo=FALSE>>=
cat(paste(substring( capture.output( cat(M$html$chart['jsChart']) ) , 0, 66), sep="\n", collapse="\n"))
@ 
A basic chart caption and html footer are the final items of the html
list (output  truncated):

<<eval=FALSE>>=
print(M, tag='caption')
@ 
<<echo=FALSE>>=
cat(paste(substring( capture.output( cat(M$html$caption) ) , 0, 66), sep="\n", collapse="\n"))
@ 

<<eval=FALSE>>=
print(M, tag='footer')
@ 
<<echo=FALSE>>=
cat(paste(substring( capture.output( cat(M$html$footer) ) , 0, 66), sep="\n", collapse="\n"))
@ 

\subsection{Displaying \texttt{gvis} objects
  locally}\label{sec:DisplayLocally} 

To display the page locally, type:
<<eval=FALSE>>=
plot(M)  # returns invisibly the file name
@

The plot method for \texttt{gvis}-objects creates HTML files in a temporary folder using
the type and chart id information of the object and it will display
the output using the R HTTP help web server locally, usually under
http://127.0.0.1.   

Note that the chart caption provides a link to the chart code via
the chart id for copy and paste. 

The R command \texttt{tempdir()}  will show you the path of the
per-session temporary directory, in which the files were written.  
You can write the chart into a local html file via the \texttt{print}
command with the file argument, e.g.
<<eval=FALSE>>=
print(M, file="myGoogleVisChart.html")
@ 

Please note that Flash charts\footnote{Currently the following charts
  require Flash: motion chart, geo map and
  annotated time line} may not work when loaded as a local file
due to security settings, and therefore require to be displayed via a
web server.  However, you can overcome this issue by changing your Flash security
settings. Tony Breyal posted the following solution on
\href{http://stackoverflow.com/questions/8009825/cannot-view-gvismotionchart-from-printed-html-file 
}{stackoverflow.com}: 

\begin{enumerate}\label{breyal}
\item Go to \url{http://www.macromedia.com/support/documentation/en/flashplayer/help/settings_manager04.html}
\item Click on the dropbox which says 'Edit location' and choose 'add location'
\item Click 'browse for folder'
\item Choose the folder in which you saved your HTML file
\item Click OK
\end{enumerate}

Now open your \googleVis HTML file and it should display
successfully. 

Alternatively use the function \texttt{plot.gvis} explicitly,
e.g. suppose your html file is stored in
\texttt{/Users/JoeBloggs/myGoogleVisChart.html}. Using the
\texttt{plot.gvis} the file will be copied into a temporary directory
and displayed via the R HTTP help server with, in the same way as a
gvis-object: 
<<eval=FALSE>>=
plot.gvis("/Users/JoeBloggs/myGoogleVisChart.html")
@ 

Please note that this feature of \texttt{plot.gvis} was introduced
to \googleVis  with version 0.3.2.

\subsection{Setting default behaviour of \texttt{print.gvis} and
  \texttt{plot.gvis}}\label{sec:Options} 

In \googleVis version 0.3.2 the function \texttt{plot.gvis} gained the
same argument as \texttt{print.gvis}: \texttt{tag}. By default the
\texttt{tag} argument is set to \texttt{NULL} in \texttt{plot.gvis}
and the plot function will display its output in a browser
window. However, if \texttt{tag} is not \texttt{NULL} the function
\texttt{plot.gvis} will behave exactly like \texttt{print.gvis}.

The default \texttt{tag} can be set for both functions globally via
the \texttt{options()} function. On package load \googleVis sets
\texttt{options(gvis.print.tag='html')} and
\texttt{options(gvis.plot.tag=NULL)}. 

Suppose you would set \texttt{options(gvis.plot.tag='chart')} then all
following plot statements would print the chart part of the
gvis-object only, without opening a browser window. This might
seem a bit odd at first, yet it becomes helpful when you write R
Markdown files for \knitr or files for other packages such as
\textbf{\texttt{R.rsp}}. 

While you draft your file you may want to see the output of \googleVis
in an interactive way, so you set \texttt{options(gvis.plot.tag=NULL)}
at the top of the file and you change the setting to \texttt{'chart'}
before you parse the file, say with \textbf{\texttt{knitr}}. This will
ensure that all plot statements return the HTML code of the chart,
rather than opening browser windows. Section~\ref{sec:knitr} on
page~\pageref{sec:knitr} provides more details and a little \knitr
example.   

\subsection{Combining charts with \texttt{gvisMerge}}\label{gvisMerge}

The function \texttt{gvisMerge} takes two \texttt{gvis}-objects 
and merges the underlying components into one page. The charts are
aligned either horizontally or vertically next to each other in an HTML table. 

\begin{figure}[ht]
\begin{center}
\includegraphics[width=0.8\textwidth]{./figures/gvisMerge.pdf}
\caption{
  Three charts combined with \texttt{gvisMerge}.
}\label{gvisMerge}
\end{center}
\end{figure}

The output of \texttt{gvisMerge} is a \texttt{gvis}-object again.
This allows us to apply the same function iteratively to create more complex
chart layouts.  The following example, see Figure~\ref{gvisMerge}, aligns a geo chart
and table below each other, and combines the output with a motion chart to the right:
<<>>=
G <- gvisGeoChart(Exports, "Country", "Profit", 
                  options=list(width=200, height=100))
T <- gvisTable(Exports, 
                  options=list(width=200, height=270))
M <- gvisMotionChart(Fruits, "Fruit", "Year",
                     options=list(width=400, height=370))
GT <- gvisMerge(G,T, horizontal=FALSE) 
GTM <- gvisMerge(GT, M, horizontal=TRUE, 
                 tableOptions="bgcolor=\"#CCCCCC\" cellspacing=10")
@ 
<<eval=FALSE>>=
plot(GTM)
@ 

\subsection{Setting options}\label{settingoptions}

Setting the various options of a \googleVis objects can be a bit
cumbersome at first. The options follow those of the Google
Charts API and can be set via a named list using the argument \texttt{options}.
In the following example, we create a line chart and set various
options\footnote{Please refer to the help file of the individual
  \googleVis functions, as the options can vary from chart to chart.},
see the output in Figure~\ref{Options}.  
\begin{figure}[ht]
\begin{center}
\includegraphics[width=0.8\textwidth]{./figures/Options.pdf}
\caption{
  A line chart with various options set.
}\label{Options}
\end{center}
\end{figure}
<<eval=FALSE>>=
df <- data.frame(country=c("US", "GB", "BR"), 
                        val1=c(1,3,4), val2=c(23,12,32))

Line <-  gvisLineChart(df, xvar="country", yvar=c("val1","val2"),
                        options=list(
                          title="Hello World",
                          titleTextStyle="{color:'red', 
                                           fontName:'Courier', 
                                           fontSize:16}",                         
                          backgroundColor="#D3D3D3",                          
                          vAxis="{gridlines:{color:'red', count:3}}",
                          hAxis="{title:'Country', titleTextStyle:{color:'blue'}}",
		          series="[{color:'green', targetAxisIndex: 0},	
                                   {color: 'orange',targetAxisIndex:1}]",
                          vAxes="[{title:'val1'}, {title:'val2'}]",
                          legend="bottom",
                          curveType="function",
                          width=500,
                          height=300                         
                          ))
plot(Line)
@
As you can see from the example above, the simpler options can be set by name=value,
e.g. width=500, while the more complex options with sub-components are
listed in curly brackets \{\}, and arrays, e.g. to define the two
axes, use square brackets [ ].

Generally, the following rules apply:

\begin{itemize}

\item parameters with names that do not include a "." are set with a single 
value, e.g. width and height. Those are set like one would do in R, that is
\texttt{options=list(}\texttt{width=200,} \texttt{height=300)}. 
Boolean arguments are set to 
either \texttt{TRUE} or \texttt{FALSE}, using the R syntax.

\item parameters with names that do not include a "." and are set with 
multiple values, e.g. \texttt{color}, and are wrapped in "[ ]", e.g. 
\texttt{options=list(} \texttt{colors="['\#cbb69d',} \texttt{'\#603913',}
\texttt{'\#c69c6e']")}

\item parameters with names that do include a "." present parameters with 
several sub-options and have to be set as a string wrapped in "\{ \}".
The values of those sub-options are set via parameter:value. Boolean values
have to be stated as \texttt{'true'} or \texttt{'false'}. 
For example the Google documentaion states the formating options for the 
vertical axis and states the parameter as \texttt{vAxis.format}. 
Then this paramter can be set in R as:
\texttt{options=list(} \texttt{vAxis="\{format:'\#,\#\#\#\%'\}")}. 

\item If several sub-options have to be set, e.g. 
\texttt{titleTextStyle.color,} \texttt{title\-Text\-Style.\-fontName} and 
\texttt{titleTextStyle.fontSize}, then those can be combined in one list item 
such as:
\texttt{options=list(} \texttt{titleTextStyle="\{color:'red',} 
\texttt{fontName:'Courier',} \texttt{fontSize:16\}")}

\item paramters that can have more than one value per sub-options are 
wrapped in "[ ]". For example to set the labels for left and right axes use:
\texttt{options=list(} \texttt{vAxes="[\{title:'val1'\},} 
\texttt{\{title:'val2'\}]")}

\end{itemize}


The following example set the colour axis of a geo chart, 
see Figure~\ref{geochart}:
<<eval=FALSE>>=
Geo <- gvisGeoChart(CityPopularity, locationvar='City', 
                    colorvar='Popularity',
                     options=list(region='US', height=350, 
                      displayMode='markers',
            	      colorAxis="{values:[200,400,600,800],
                       colors:[\'red', \'pink\', \'orange',\'green']}")
                      ) 
plot(Geo)
@ 
\begin{figure}[ht]
\begin{center}
\includegraphics[width=0.8\textwidth]{./figures/gvisGeoChart.pdf}
\caption{
A geo chart with options set for a colour axis.}
\label{geochart}
\end{center}
\end{figure}

\subsubsection{Chart Editor}
A special option for all charts is \texttt{gvis.editor}, which adds an
edit  button to the page, allowing the user to edit, change and
customise the chart on the fly, see the following example and
Figure~\ref{Editor}. The content of the list item \texttt{gvis.editor}
describes the label of the browser button\footnote{See also
  \url{https://google-developers.appspot.com/chart/interactive/docs/drawing\_charts\#charteditor}}. 
<<eval=FALSE>>=
Editor <- gvisLineChart(df, options=list(gvis.editor='Edit me!'))
plot(Editor)
@ 
\begin{figure}[ht]
\begin{center}
\includegraphics[width=0.8\textwidth]{./figures/Editor.pdf}
\caption{
Example of \googleVis chart with \texttt{options = list (gvis.editor =
  'Edit me!')}.
}\label{Editor}
\end{center}
\end{figure}

\subsubsection{Dealing with apostrophes in column names}
The \googleVis package converts data frames into JSON objects.
The column names of the resulting JSON tables are encapsulated with
single speech marks, see lines 12 -- 16 of the code example on
page~\pageref{motionchartcodeexample}. 

Hence apostrophes in column names of your input data frame have
to be encapsulated by a double backslash.

Here is a little example, see the output in Figure~\ref{fig:apostrophes}.
<<>>=
df <- data.frame("Year"=c(2009,2010), "Lloyd\\'s"=c(86.1, 93.3), 
                 "Munich Re\\'s R/I"=c(95.3, 100.5),
                 check.names=FALSE) 
df
CR <- gvisColumnChart(df, options=list(vAxis='{baseline:0}', 
                            title="Combined Ratio %",
                            legend="{position:'bottom'}"))
@ 
<<eval=FALSE>>=
plot(CR)
@ 
\begin{figure}[t]
  \centering
  \includegraphics[width=0.5\textwidth]{./figures/Apostrophe.pdf}
  \caption{Visualising data with apostrophes in column names.}
  \label{fig:apostrophes}
\end{figure}

\section{Embedding \googleVis in web sites}

\subsection{Integrating \texttt{gvis} objects in existing sites}

Suppose you have an existing web page and would like to integrate the
output of a \googleVis function, such as \texttt{gvisMotionChart}. 
In this case you only need the chart output from
\texttt{gvisMotionChart}.  So you can either copy and paste the output
from the R console
<<eval=FALSE>>=
print(M, 'chart')  ## or cat(M$html$chart) 
@ or the browser, see previous section, 
into your existing html page, or write the content directly into a file
<<eval=FALSE>>=
print(M, 'chart', file='myfilename')
@
and process it from there.

\subsection{Using \googleVis output with WordPress}

\href{http://wordpress.org/}{WordPress} is a popular web software for
creating websites and blogs. Here we give some tips about the
usage with \googleVis output.  

By default WordPress does not allow JavaScript code (and hence \googleVis
output) to be inserted into a page. However, additional plugins
allow you to extend the functions of WordPress.

One option of embedding JavaScript code inside a WordPress post is to use
the ``custom fields shortcode''
plugin\footnote{\url{http://wordpress.org/extend/plugins/custom-fields-shortcode}}. 
The plugin allows you to create a custom field for the \googleVis
code, which can be referred to in your article.

Suppose you created a motion chart in R:
<<eval=FALSE>>=
M <- gvisMotionChart(Fruits, "Fruit", "Year",
		     options=list(width=400, height=370))
@
Copy the chart code, e.g. from
<<eval=FALSE>>=
print(M, 'chart')
@ 
and paste it into the value text area of a custom field in WordPress, e.g.
with instance name \texttt{Fruits}.  To include the motion chart into your article add
\texttt{[cf]Fruits[/cf]} into the post, see Figure~\ref{wordpress} for
an illustration.

\begin{figure}[t]
  \centering
  \includegraphics[width=0.8\textwidth]{./figures/CreatePost.pdf}
  \caption{Including \googleVis output in a WordPress blog entry.}
  \label{wordpress}
\end{figure}


\subsection{Using \googleVis output with Google Sites, Blogger, etc.}

Google Charts can be used with other Google products such as Google
Sites, Blogger or Google Code wiki pages. 
However, in most cases, the chart has to be embedded as a Google Gadget.
Google Gadgets are written in XML and can have HTML and Javascript components.
Here is an example of a 'Hello World' program written using Google
Gadget technology from \href{http://en.wikipedia.org/wiki/Google_Gadgets}{Wikipedia}.
\begin{verbatim}
<?xml version="1.0" encoding="UTF-8" ?> 
<Module>  
<ModulePrefs title="simple hello world example" />   
<Content type="html">     
     <![CDATA[ 
       Hello, world!
     ]]>
</Content> 
</Module>
\end{verbatim}
The \googleVis package comes with the function
\texttt{createGoogleGadget}, which takes a gvis-object and
wraps it into an XML gadget file. Here is an example with a motion chart:
<<>>=
M <- gvisMotionChart(Fruits, "Fruit", "Year")
G <- createGoogleGadget(M)
@ 
<<eval=FALSE>>=
cat(G, file="myGadget.xml")
@ 
In order to use the gadget, the file \texttt{myGadget.xml} has to be
hosted online, e.g. using Google Docs. 
Suppose the URL to the gadget is
\texttt{http://example.com/myGadget.xml}, than you can embed  the gadget

\begin{itemize}

\item in a Google Site via the menu:
  
  "Insert" -> "More gadgets ..." -> "Add gadget URL",
  
\item in a Google Code wiki via the \texttt{wiki:gadget} tag, e.g.: 
  
  \texttt{<wiki:gadget url="http://example.com/gadget.xml" />},

 \item in Blogger via the design tab, see site gadgets.
\end{itemize}

However, the situation is different again, if you would like to include the \googleVis
output into a blogger post.  In this case, a gadget does not
work. You can either copy and paste the chart directly into your
post, but then it does not seem to work with MS Internet Explorer, or
you use an indirect approach. This means that the \googleVis
chart has to be hosted on a separate page (e.g. in a public web
folder) and is embedded into the blog post by using the
\texttt{<iframe>} tag, e.g.: 
\begin{verbatim}
<iframe width="100%" height="400px" frameborder="0" 
src="http://example.com/myGoogleVisChart.html">
</iframe>
\end{verbatim}
For an example see the following blog entry:
\href{http://www.magesblog.com/2011/09/including-googlevis-output-into-blogger.html}
{http://www.magesblog.com/2011/09/including-googlevis-output-into-blogger.html}.



\subsection{Embedding \googleVis in web sites dynamically}

In this section, we provide examples how the \googleVis functions can be
embedded into web pages dynamically. 

The R packages \rsp~\cite{Rsp} and \brew~\cite{brew2010} are two
options to integrate R snippets into HTML code. While the \rsp package
comes with its own internal web server, \brew requires the Apache HTTP
server~\cite{Apache2.0} with the \rapache~\cite{Rapache} module
installed. Please note that currently the \rapache module only runs on
UNIX/Linux and Mac OS X.   

Since version 2.11.0 R ships with its own internal web server and with
\Rook~\cite{Rook} and \shiny~\cite{shiny} there are also two 
alternatives that use this facility. Both packages allow users to
deploy web application locally with very little overhead. The \shiny
framework is the newest and certainly easiest option to 
get started with web apps using R and \googleVis.

\subsubsection{Using \googleVis with \rsp}\label{rspexample}
The \rsp package allows the user to integrate R code into html code.
The R code is parsed by the \rsp web server and executed
at run time. 

As an example, we embed a motion chart into a rsp-page: 
\begin{verbatim}
<html>
<body>
<% library(googleVis)
   M <- gvisMotionChart(Fruits, idvar="Fruit", timevar="Year") %>
<%= M$html$chart %>
</body>
</html>
\end{verbatim}
The R code included in \texttt{<\%$\dots$\%>} is executed when read by
the R.rsp HTTP server, but no R output will be displayed. To embed the
R output into the html code we have to add an equal sign,
\texttt{<\%=$\dots$\%>}, which acts as a \texttt{cat} statement.

\subsubsection{Using \googleVis with \rapache and \brew}\label{rapacheexample}

\rapache supports web application development using
R and the Apache HTTP server. The  \rapache module
embeds the R interpreter into the Apache web server.  However, as we
would like to mix R and HTML code we also need a parser and
this is where the R package \brew comes into place. 

Files sitting in a dedicated \brew folder of the HTTP repository are
parsed by \brew when opened in the browser. The R code is 
executed with \rapache and the output is embedded into the site.
Hence the approach is similar to \rsp with the difference that the
two tasks are split. This has the advantage that R does not have to
run in a separate window.

Detailed installation instructions for \rapache are available on the
project site: 
\href{http://rapache.net/manual.html}{http://\-rapache.\-net/\-manual\-.html},
for specific comments on Mac OS X see: 
\href{http://worldofrcraft.blogspot.com/2010/08/installing-rapache-on-mac-os-x-snow.html}{http://\-worldofrcraft\-.blog\-spot\-.com/\-2010/\-08/\-installing\--rapache\--on\--mac\--os\--x\--snow\-.html}  

Following the installation of \rapache you will have to configure Apache.
Most likely you have to add something along the following lines to your
\path{apache2.conf} or \path{httpd.conf} file (often found in
\path{/etc/httpd} or \path{/private/etc/apache2/httpd.conf} on Mac OS X):
\begin{verbatim}
LoadModule R_module /usr/lib/apache2/modules/mod_R.so
## On Mac OS X more likely to be:
## LoadModule R_module libexec/apache2/mod_R.so
ROutputErrors
RSourceOnStartup "/var/www/rapache/R/startup.R"
## On Mac OS X the www folder is often equivalent to:
## /Library/WebServer/Documents/
\end{verbatim}
The first line loads the R module when the Apache web server is
started, the second line deals with error handling, while
the \path{startup.R} file is suitable for initial
set ups, e.g. libraries and global variables:
\begin{verbatim}
## Ensure the packages are installed so that mod_R 
## has access to them, e.g. not in your home folder
library{googleVis} 
library{lattice}
library{Cairo}
MyGlobalVar <- 42
\end{verbatim}

To test that \rapache is working open
\href{http://localhost/RApacheInfo}{http://\-localhost/\-RApacheInfo} and
you should find details about your system, an example can be found on
the \rapache site:
\href{http://biostat.mc.vanderbilt.edu/rapache/files/RApacheInfo.html}{http://\-biostat.\-mc.\-vanderbilt.\-edu/\-rapache/\-files/\-RApacheInfo\-.html} 

The next step is to install the \brew R package in the usual way:
<<eval=FALSE>>=
install.packages('brew')
@
Following this we have to tell Apache that files in a specific folder
should be parsed by \textbf{\texttt{brew}}. Again we edit the \path{apache2.conf} or
\path{httpd.conf}  and add the connection of the RHandler with the function \path{brew}:
\begin{verbatim}
<Directory /var/www/rapache/brew>
## On Mac OS more likely to be something like:
## <Directory /Library/WebServer/Documents/rapache/brew>
      SetHandler r-script
      RHandler brew::brew
</Directory>
\end{verbatim}

That's all. Restart the HTTP daemon and you can start placing files in
the \brew directory and access them via
\path{http://localhost/rapache/brew/filename}, e.g. a file containing:  
\begin{verbatim}
<html>
<body>
<h1>Fruits</h1>
<% library(googleVis)
   M <- gvisMotionChart(Fruits, idvar="Fruit", timevar="Year") %>
<%= M$html$chart %>
</body>
</html>
\end{verbatim}

You will notice that the  \brew syntax is very similar to \texttt{rsp}.
For more information read the documentation of the \rapache
module and \brew package. 
You find two simple examples of brew files in the \googleVis
package. Again the following R command shows you the 
folder path:
<<eval=FALSE>>=
system.file("brew", package = "googleVis")
@ 

\subsubsection{Using \googleVis with \Rook}

\Rook~\cite{Rook} is a web server interface for R, written by Jeffrey Horner, the author 
of rApache and brew. Compared to other web frameworks \Rook appears incredibly lightweight.
\Rook doesn't need any configuration. It is an R package, which works out of the box with the R HTTP 
server. That means no configuration files are needed. No files have to be placed 
in particular folders. Instead, \Rook web applications can be run on a local desktop. 
However, \Rook requires some knowledge of the HTTP protocol. 

Here is a \Rook app example with \texttt{googleVis}. It displays a little R data frame in a 
\googleVis table by default. 
The user can change the visualisation by clicking on the \emph{Edit me!} button 
and upload her/his own CSV-file, see Figure~\ref{fig:Rook}. 

\begin{figure}[ht]
  \centering
  \includegraphics[width=0.8\textwidth]{./figures/Rook.pdf}
  \caption{Screen shot of a Rook app with \googleVis output.}
  \label{fig:Rook}
\end{figure}

<<eval=FALSE>>=
require(Rook)
require(googleVis)
s <- Rhttpd$new()
s$start(listen='127.0.0.1')

my.app <- function(env){
 ## Start with a table and allow the user to upload a CSV-file
  req <- Request$new(env)
  res <- Response$new()

  ## Provide some data to start with
  ## Exports is a sample data set of googleVis
  data <- Exports[,1:2] 
  ## Add functionality to upload CSV-file
  if (!is.null(req$POST())) {
    ## Read data from uploaded CSV-file
   data <- req$POST()[["data"]]
   data <- read.csv(data$tempfile)
  }
  ## Create table with googleVis
  tbl <- gvisTable(data, 
                   options=list(gvis.editor="Edit me!",
                                height=350),
                                chartid="myInitialView")
  ## Write the HTML output and
  ## make use of the googleVis HTML output.
  ## See vignette('googleVis') for more details
  res$write(tbl$html$header) 
  res$write("<h1>My first Rook app with googleVis</h1>")
  res$write(tbl$html$chart)
  res$write('
Read CSV file:<form method="POST" enctype="multipart/form-data">
<input type="file" name="data">
<input type="submit" name="Go">\n</form>')            
  res$write(tbl$html$footer)
  res$finish()
}
s$add(app=my.app, name='googleVisTable')
## Open a browser window and display the web app
s$browse('googleVisTable')
@

\subsubsection{Using \googleVis with \shiny}
Shiny\footnote{\url{http://www.rstudio.com/shiny/}} is a package by
RStudio. Shiny makes it incredibly easy to build interactive web
applications with R.  

With version 0.4.0 of \googleVis the support for \shiny ~\cite{shiny}
apps has been added. Joe Cheng contributed the \texttt{renderGvis}
function which allows users to use \googleVis output in \shiny in a
similar way to other plotting functions. Note that \shiny version
$\ge$ 0.4.0 is required.

The following example has been taken from the help file of
\texttt{renderGvis}. It displays a scatter chart where the user can
select the data set to be displayed, see also the screen shot in
Figure~\ref{fig:shiny}. 

<<eval=FALSE>>=
# server.R
library(googleVis)

shinyServer(function(input, output) {
  datasetInput <- reactive({
    switch(input$dataset,
           "rock" = rock,
           "pressure" = pressure,
           "cars" = cars)
  })
  
  output$view <- renderGvis({
    gvisScatterChart(datasetInput())
  })
})

# ui.R
shinyUI(pageWithSidebar(
  headerPanel("googleVis on Shiny"),
  sidebarPanel(
    selectInput("dataset", "Choose a dataset:", 
                choices = c("rock", "pressure", "cars"))
  ),
  mainPanel(
    htmlOutput("view")
  )
))
@ 

\begin{figure}[ht]
  \centering
  \includegraphics[width=0.8\textwidth]{./figures/shiny.pdf}
  \caption{Screen shot a \shiny app with \googleVis output.}
  \label{fig:shiny}
\end{figure}

You can run the example locally with the following statement.
<<eval=FALSE>>=
library(shiny) ## Version >= 0.4.0 required
runApp(system.file("shiny/", package="googleVis"))
@ 

Further examples have been published on Markus' blog:
\url{http://www.magesblog.co.uk/search/label/shiny} 

\section{Using \googleVis with \knitr}\label{sec:knitr}
Using \googleVis with
\knitr\footnote{\url{http://yihui.name/knitr/}}~\cite{knitr} is a
convenient way of creating interactive reproducible reports. The
approach taken by \knitr is similar to Sweave, you can combine R
code with text and formatting tags. However, \knitr can also export to
HTML, which is required to  embed \googleVis charts.

To include \googleVis output into a \knitr document you have 
to set the chunk option \texttt{results} to \texttt{'asis'} and print the chart 
element only, as demonstrated in the following example:
\begin{verbatim}
```{r results='asis'}
M <- gvisMotionChart(Fruits, "Fruit", "Year",
                     options=list(width=550, height=450))
print(M, 'chart')
```
\end{verbatim}
A little example was published in a blog post: 
\url{http://www.magesblog.co.uk/2012/05/interactive-reports-in-r-with-knitr-and.html}

Version 0.3.2 of \googleVis introduced \texttt{'tag'} as a new argument to
the plot function \texttt{plot.gvis}, see also
page~\pageref{sec:Options}. This argument is by default set to
\texttt{NULL} and can be set globally outside the plot function via
\texttt{options()}.  

The argument \texttt{tag} influences the behaviour of the plot
function. The \texttt{tag} parameter can be the same as for the print
function \texttt{print.gvis}. Indeed, setting
\texttt{options(gvis.plot.tag = 'chart')} will change the behaviour of
plot to print, so \texttt{plot(x)} will no longer open a browser
window, but produce the same output as \texttt{print(x, tag='chart')},
if \texttt{x} is a gvis-object. 

Hence, setting the option \texttt{gvis.plot.tag} in a \knitr markdown
Rmd-file to \texttt{'chart'} will automatically turn all following
plot statements into html output, see the example below and Figure~\ref{fig:markdown}. 

\begin{figure}[ht]
  \centering
  \includegraphics[width=0.7\textwidth]{./figures/MarkdownExample.pdf}
  \caption{Screen shot of the markdown  example output} 
  \label{fig:markdown}
\end{figure}

\begin{verbatim}
# Markdown example with knitr and googleVis
===========================================
This is a little Markdown example file.
Set the googleVis options first.
In this case change the behaviour of plot.gvis
```{r setOptions, message=FALSE}
library(googleVis)
op <- options(gvis.plot.tag='chart')
```
The following plot statements will automatically return  the HTML
required for the 'knitted' output. 

## Combo chart
```{r ComboExample, results='asis', tidy=FALSE}
## Add the mean
CityPopularity$Mean=mean(CityPopularity$Popularity)
CC <-  (CityPopularity, xvar='City',
          yvar=c('Mean', 'Popularity'),
          options=list(seriesType='bars',
                       width=450, height=300,
                       title='City Popularity',
                       series='{0: {type:\"line\"}}'))
plot(CC)
```
Example of gvisComboChart with R code shown above.

## Place two charts next to each other
```{r gvisMergeExample, results='asis', echo=FALSE}
Geo <- gvisGeoChart(Exports, locationvar='Country', colorvar='Profit', 
                    options=list(height=300, width=350)) 
Tbl <- gvisTable(Exports, options=list(height=300, width=200))
plot(gvisMerge(Geo, Tbl, horizontal=TRUE))
``````
Example of a gvisGeoChart with gvisTable and R code hidden.

## Motion Chart
```{r MotionChartExample, results='asis', tidy=FALSE}
M <- gvisMotionChart(Fruits, 'Fruit', 'Year',
         options=list(width=400, height=350))
plot(M)
```
Please note that the Motion Chart is only displayed when hosted on a
web server, or is placed in a directory which has been added to the 
trusted sources in the [security settings of Macromedia]
(http://www.macromedia.com/support/documentation/en/flashplayer/help/settings_manager04.html). 
See the googleVis package vignette for more details. 

```{r resetOptions}
## Set options back to original options
options(op)
```
\end{verbatim}

Note that you can use the \texttt{options()} command in your \knitr
file to switch between an interactive mode, where you are likely to
experiment, via copying and pasting R code into the console and
running \texttt{knit} on the whole file.

A more comprehensive example is given in the help file to \texttt{?plot.gvis}.

\section{Using \googleVis in presentations}\label{sec:presentations}

The Google Chart Tools are designed for web pages, so it should
be no surprise that it can be difficult or impossible to embed \googleVis 
output in traditional presentation software like MS PowerPoint\footnote{For 
MS PowerPoint on MS Windows the plug-in
\href{http://skp.mvps.org/liveweb.htm}{liveweb} provides the
  functionality to insert web pages into a PowerPoint slide and
  refresh the pages real-time during slide show.}, Google Docs,
OpenOffice Impress or Apple Keynote. 

The easiest way is to include screen shots into the slide with links to
the live web pages. But this approach requires the presenter to switch
between applications during her talk. This can be fun, but quite often
it is not. 

An alternative would be to build the presentation as a web page itself.  

A popular approach here is the \texttt{slidify} package by Ramnath Vaidyanathan, 
\cite{slidify} that builds on the knitr Markdown approach of the previous 
section. An example of a \texttt{slidify} presentation is the \googleVis 
tutorial given at the useR! conference in 2013, \cite{googleVisTutorial}.

\begin{figure}[h]
  \centering
  \includegraphics[width=0.5\textwidth]{./figures/googleVisTutorial2013.png}
  \caption{\googleVis tutorial at the useR! 2013 conference: \url{http://decastillo.github.io/googleVis_Tutorial}} 
  \label{fig:slidify}
\end{figure}

Slidify provides a choice of different layout frameworks and syntax highlighting options. Additionally, slidify slides can be published from R online, e.g. 
on GitHub.
% 
% \section{Using \googleVis with RStudio}
% 
% RStudio is popular a free and open source integrated development environment 
% for R. With verion 0.98.441 RStudio introduced a viewer pane that allows users 
% to display HTML files within RStudio's IDE.
% 
% \googleVis will use the Viewer pane in RStudio (version >= 0.98.441) 
% to display non-Flash charts by default. Flash charts and merged gvis-objects are
% displayed in the default browser. The setting is controlled
% via the option \texttt{googleVis.viewer}. By default it will have
% the value of \texttt{getOption("viewer")}.
% 
% Set \texttt{options("googleVis.viewer"=NULL)} and the googleVis
% plot function will open all output in the standard browser.
% 

\section{Beyond R}
In this section we present ideas which go beyond the usual coding in
R and are somewhat experimental.

\subsection{Registering to catch events}

Google visualisations can fire and receive
events~\footnote{\url{http://code.google.com/apis/chart/interactive/docs/reference.html\#addlistener}}. 
It exposes the following two JavaScript methods: 
\begin{itemize}
\item \texttt{google.visualization.events.trigger()} fires an event,
\item \texttt{google.visualization.events.addListener()} listens for events.
\end{itemize}

Here is an example of registering to receive the selection event from
the Google documentation:
\begin{verbatim}
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);
google.visualization.events.addListener(table, 'select', selectHandler);

function selectHandler() {
  alert('A table row was selected');
}
\end{verbatim}

We will only deal with this special case of a 'select' event of the
'addListner' method. This event is available for most visualisations
and acts on user interactions, e.g. user selection clicks.

The 'addListener' method expects JavaScript code, which can be embedded
into a gvis-object via \texttt{options} as (undocumented) parameter
\texttt{gvis.listener.jscode}. 

Here are some examples:

Look up the selected item in Wikipedia:
<<eval=FALSE>>=
jscode <- "window.open('http://en.wikipedia.org/wiki/' 
                  + data.getValue(chart.getSelection()[0].row,0)); "

J1 <- gvisGeoMap(Exports, locationvar='Country', numvar='Profit',
                 options=list(dataMode="regions", gvis.listener.jscode=jscode))
plot(J1)
@ 
In the same way we can use the code in other charts, e.g. org- or line chart:                 
<<eval=FALSE>>=
plot(gvisOrgChart(Regions,  options=list(gvis.listener.jscode=jscode)))
plot(gvisLineChart(Regions[,c(1,3)], options=list(gvis.listener.jscode=jscode)))
@
In the following more advanced example the selected value of a table is
displayed in a message box:
<<eval=FALSE>>=
jscode <- "
       var sel = chart.getSelection();
       var row = sel[0].row;
       var text = data.getValue(row,1);
       alert(text);
"
J2 <- gvisTable(Population, options=list(gvis.listener.jscode=jscode))
plot(J2)
@ 
For more details see the \texttt{demo(EventListener)} and
\href{https://developers.google.com/chart/interactive/docs/reference}{Google
  Charts Reference}.

\section{Frequent ask questions -- FAQ}
\subsection{Can I use googleVis output in PDF files?}
No, not directly. 

The Google Charts API is designed for dynamic web
output on your screen and not on paper. See also the
section~\ref{sec:presentations}, page~\pageref{sec:presentations},
which covers how to use \googleVis in presentations. 

Note that this vignette uses screen shots to include
examples of \googleVis charts.

For further details see Google's online documentation on 
\href{https://developers.google.com/chart/interactive/docs/printing}{printing 
PNG charts}.

\subsection{Can I change the colour of the bubbles in motion charts?}

No, unfortunately not.

The colours are set by the Google Charts API and cannot be changed
by the user.

\subsection{Can I change the icons in Maps?}

No, not via \texttt{gvisMap}.

However, you can upload your data to a Google Fusion Table and link it
to a second table which defines the icons. See the Google Fusion Table
support page for more details: \url{http://support.google.com/fusiontables/answer/2679986?hl=en}

\subsection{Why can't I see motion charts when I open them from a local directory?}

See section~\ref{sec:DisplayLocally} on page~\pageref{sec:DisplayLocally}

\subsection{Why can't I see motion charts on my iPad/iPhone?}

Motion charts (also geo maps and annotated time lines) are rendered in
your browser using Flash, unlike most other charts which use
HTML5. Unfortunately, Flash is not directly supported on iOS devices
such as iPads and iPhones. 

\subsection{How can I set axes limits with googleVis?}

Unfortunately, there are no arguments such as \texttt{ylim} and \texttt{xlim}. 
Instead, the Google Charts axes options are set via \texttt{hAxes} and 
\texttt{vAxes}, with h and v indicating the horizontal and vertical axis. 
More precisely, we have to set  \texttt{viewWindowMode : 'explicit'} and set 
the \texttt{viewWindow} to the desired min and max values. 
Additionally, we have to wrap all of this in $[\{\}]$ brackets as those 
settings are sub-options of \texttt{h/vAxes}. 
There are also options \texttt{minValue} and \texttt{maxValue}, 
but they only allow you to extend the axes ranges.

Here is a minimal example, setting the y-axis limits from 0 to 10:
<<eval=FALSE>>=
library(googleVis)
dat <- data.frame(x=LETTERS[1:10], 
                  y=c(0, 4, -2, 2, 4, 3, 8, 15, 10, 4))
area1 <- gvisAreaChart(xvar="x", yvar="y", data=dat,
    	options=list(vAxes="[{viewWindowMode:'explicit',
			viewWindow:{min:0, max:10}}]",
                        width=500, height=400, 
                        title="y-limits set from 0 to 10"),
			chartid="area1ylim")
plot(area1)
@

\subsection{How can I change the look and feel of the charts?}

The charts have a lot of options which allow you to change the look
and feel of the output, see the help files for more details. However,
\googleVis provides only an interface to the Google Charts API. If
you have specific questions to the charts then please join the Google
Visualisation API newsgroup: 
\url{http://groups.google.com/group/google-visualization-api}.

For frequent ask questions regarding the API check: 
\url{https://developers.google.com/chart/interactive/faq}.

\subsection{Is it possible to use \googleVis in corporate work?}
Review the Google Terms of Service
(\url{https://developers.google.com/terms/}) and get in touch with
your colleagues in IT / Legal. If in doubt contact Google
directly. 

\subsection{Bugs and issues}

Should you find any issues or bugs with googleVis, then please drop
us a line or add them to our issues list: 
\url{https://github.com/mages/googleVis/issues}


\subsection{Citation}
Please cite R and \googleVis if you use it in your work or publications. Use
<<eval=FALSE>>=
citation("googleVis")
@
and
<<eval=FALSE>>=
citation()
@ 
for  bib-entries and information on how to cite the software.

%%\clearpage

\bibliographystyle{alpha}
\bibliography{googleVis}
\addcontentsline{toc}{section}{References} 

\end{document}
