\documentclass{article}

%% R> library(pgfSweave)
%% R> pgfSweave("pgfSweave-vignette-source.Rnw",pdf=T)


% \VignetteIndexEntry{The pgfSweave Package}
% \VignetteDepends{pgfSweave}

\usepackage[nogin,noae]{Sweave}
\usepackage{pgf}
\usepackage[parfill]{parskip}
\usepackage{fancyvrb}
\usepackage[left=1.2in,right=1.2in,top=1.2in,bottom=1.2in]{geometry}
\newcommand{\lang}{\textsf}
\newcommand{\code}{\texttt}
\newcommand{\pkg}{\textbf}
\newcommand{\ques}[1]{\vspace{.5cm}\noindent{\bf\large#1}\vspace{.2cm}}

\title{The \pkg{pgfSweave} Package}
\author{Cameron Bracken and Charlie Sharpsteen}


\begin{document}


%% Cache all of the code chunks and generate external figures by default 
%% the pgfSweave defaults are pdf=FALSE and eps=FALSE and pgf=TRUE.
%% to get normal Sweave behavior set pgf=FALSE and external=FALSE 



\maketitle

The \pkg{pgfSweave} provides capabilities for ``caching'' graphics generated with \pkg{Sweave}.  This document highlights the features and usage of \pkg{pgfSweave}.  \pkg{pgfSweave} provides a new driver for \pkg{Sweave}, \code{pgfSweaveDriver} and new chunk options \code{pgf} and \code{external} on top of the \code{cache} option provided by \pkg{cacheSweave}.  This package is built directly upon \pkg{cacheSweave} and therefore also \pkg{Sweave}. 

\section{Motivation and Background} 

\pkg{Sweave} is a tool for generating ``reproducible'' documents by embedding \lang{R} or \lang{S} ``code chunks'' directly into a \LaTeX{} document.  Two main drawbacks to this approach are: 
\begin{enumerate} 
\item Code chunks with lengthy computations and plotting commands are executed every time a document is compiled  
\item Consistency in style (font, point size) in automatically generated graphics is difficult to achieve.  
\end{enumerate}

The \pkg{cacheSweave} package addresses the first issue of lengthy computations by storing the result of computations in a \pkg{filehash} databases.  This provides significant speedup of certain computations, namely those which create objects in the global environment.  Unfortunately most plotting commands do not create objects which can be cached.  This is the first issue addressed by \pkg{pgfSweave}.  So called ``caching'' of plots is achieved with the help of two tools: the \TeX{} package \pkg{pgf}\footnote{\texttt{http://sourceforge.net/projects/pgf/}}  and the command line utility \pkg{eps2pgf}\footnote{\texttt{http://sourceforge.net/projects/eps2pgf/}}.  

When we refer to the ``caching'' of an graphic we mean that if the code chunk which generated the graphic is unchanged, an image is read from a file rather than regenerated from the code.  The \TeX{} package \pkg{pgf}\footnote{Latest CVS available at \texttt{http://sourceforge.net/cvs/?group\_id=142562}} provides the ability to ``externalize graphics.''  The externalization chapter in the \pkg{pgf/Ti\textit{k}Z} manual is extremely well written, so please look there for more information.   


\section{Usage}

We assume a familiarity with the usage of \pkg{Sweave}, for more information see the \pkg{Sweave} manual\footnote{\texttt{http://www.stat.uni-muenchen.de/$\sim$leisch/Sweave/Sweave-manual.pdf}}.  This section will explain the usage of the \code{pgf} and \code{external} options and then provide a complete example.

\subsection{The \code{pgf} option}
The first new code chunk option \code{pgf}, acts the same as the \code{pdf} or \code{eps} options but instead of resulting in an \code{$\backslash$includegraphics\{\}} statement the result is an \code{$\backslash$input\{\}} statement.  For example the text and Consider the following code:

\begin{minipage}[!ht]{.5\linewidth}
Input:
\begin{Verbatim}[frame=single]
\begin{figure}[ht]
 <<pgf-option,fig=T,pgf=T,echo=F>>=
     x <- rnorm(100)
     plot(x)
 @  
\caption{caption}
\label{fig:pgf-option}
\end{figure}
\end{Verbatim}
\end{minipage}
\begin{minipage}[!ht]{.5\linewidth}
Output:
\begin{Verbatim}[frame=single]
\begin{figure}[ht]
\input{pgf-option.pgf}
\caption{caption}
\label{fig:pgf-option}
\end{figure}
\end{Verbatim}
\end{minipage}

\vspace{.5cm}
The \code{.pgf} file is generated with the \pkg{eps2pgf} utility. The \code{postscript} graphics device is used first to generate a \code{.eps} file.  Then the command
\begin{verbatim}$ java -jar /path/to/eps2pgf.jar -m directcopy graphic.eps\end{verbatim}
is run on every code chunk that has \code{fig=TRUE} and \code{pgf=TRUE}.  {\color{red}When using \pkg{pgfSweave} the \code{pgf} option is set to \code{TRUE} by default.}

\subsection{The \code{external} option}

\begin{minipage}[!ht]{.55\linewidth}
Input:
\begin{Verbatim}[frame=single]
\begin{figure}[ht]
 <<external,fig=T,pgf=T,external=T,echo=F>>=
     x <- rnorm(100)
     plot(x)
 @  
\caption{caption}
\label{fig:pgf-option}
\end{figure}
\end{Verbatim}
\end{minipage}
\begin{minipage}[!ht]{.45\linewidth}
Output:
\begin{Verbatim}[frame=single]
\begin{figure}[ht]
\beginpgfgraphicnamed{external}
\input{external.pgf}
\endpgfgraphicnamed
\caption{caption}
\label{fig:external}
\end{figure}
\end{Verbatim}
\end{minipage}


\subsection{A complete example}
At this point we will provide a complete example.  The example from the \pkg{Sweave} manual is used to highlight the differences. The two frame below show the input Sweave file \texttt{example.Rnw} and the resulting tex file \texttt{example.tex}.

\VerbatimInput[frame=single,label={pgfSweave-example-Rnw.in},labelposition=all]{pgfSweave-example-Rnw.in}

On the input file run:
\begin{Verbatim}
R> library(pgfSweave)
R> pgfSweave('example.Rnw',pdf=T)
\end{Verbatim}
And we get:

\VerbatimInput[frame=single,label={pgfSweave-example-tex.in},labelposition=all]{pgfSweave-example-tex.in}


\section{Consistency in style between graphics and text}
%% initial calculations

 In figure \ref{normalSweave} Notice the inconsistency in font and size between the default \lang{R} output and the default \LaTeX{} output.  Fonts and font sizes can be changed from \lang{R} but it is hard to be precise.  What if you decide to change the font and and point size of your entire document?  In figure \ref{pgfSweave-hist} the text is consistent with the rest of the document.

\begin{figure}[!ht]
\begin{minipage}{.45\linewidth}
\centering
\begin{Schunk}
\begin{Sinput}
> hist(a)
\end{Sinput}
\end{Schunk}
\includegraphics{figs/fig-normalSweave}
\caption{This is normal \pkg{Sweave}.}\label{normalSweave}
\end{minipage}
\begin{minipage}[!ht]{.45\linewidth}
%% pgf file will get regenerated every time slowing down the whole compilation.
%% even though cache=TRUE. 
\centering
\begin{Schunk}
\begin{Sinput}
> hist(a)
\end{Sinput}
\end{Schunk}
\beginpgfgraphicnamed{figs/fig-pgfSweave-hist}
\input{figs/fig-pgfSweave-hist.pgf}
\endpgfgraphicnamed
\caption{This is from \pkg{pgfSweave}.}\label{pgfSweave-hist}
\end{minipage}
\end{figure}

\clearpage
The example below illustrates some of the power of \pkg{pgfSweave}.  \LaTeX{} code can be directly input into captions.  This sort of thing is already available in \lang{R} but again consistency in font and text size is difficult to achieve.  

%% only compiled once
\begin{figure}[ht] 
\centering
\begin{Schunk}
\begin{Sinput}
> plot(a, b, xlab = "", ylab = "")
> title(xlab = "$\\alpha\\beta\\gamma\\delta\\epsilon\\Re \\longrightarrow\\ell\\hbar$")
> title(ylab = "{\\color{green!40!blue}\\scshape \\Large Teal Label in Small Caps}")
> title(main = "{\\large This is a plot of $\\displaystyle\\int_a^b \\frac{x}{y}dx$}")
> abline(fit)
\end{Sinput}
\end{Schunk}
\beginpgfgraphicnamed{figs/fig-third}
\input{figs/fig-third.pgf}
\endpgfgraphicnamed
\caption{Large size plot but still consistant. Also \LaTeX{} can be put directly into the titles of the plot which matches the style of your paper.  All $\backslash$'s must be escaped using this method.}
\end{figure}


\clearpage
Every part of \pkg{Sweave} and \pkg{cacheSweave} work the same but do not cache explicit print statements or they will not show up on a second compile.

\section{Frequently Asked Questions}

\ques{Can \pkg{pgfSweave} be run from the command line?}

Sure! Use:  (HOPEFULLY THIS WILL WORK IT DOES NOT YET!)
\begin{Verbatim}
R CMD pgfSweave <myfile>.Rnw
\end{Verbatim}
OR use the shell script provided in the \pkg{pgfSweave} package source in the \texttt{exec/} directory
Save the script somewhere in your \texttt{PATH} and run
\begin{Verbatim}
$ pgfsweave <yourfile>.Rnw
\end{Verbatim}



\ques{How do I set subdirectories for figures and caches?}

This is strait out of the \pkg{Sweave} and \pkg{cacheSweave} manuals (nothing new here).  For a figures subdirectory \footnote{make sure to create the directory first!} use the \code{prefix.string} option:

\begin{verbatim}\SweaveOpts{prefix.string=figs/fig}\end{verbatim}

For a caching subdirectory use a code chunk at the beginning or your document like:
\begin{verbatim}
	<<setup,echo=F>>=
	setCacheDir("cache")
	@
\end{verbatim}



\ques{Why are the width and height options being ignored?}

This is another one from \pkg{Sweave}. You must use the \code{nogin} option in \code{Sweave.sty} for the width and height parameters to actually affect the size of the image in the document:
\begin{verbatim}\usepackage[nogin]{Sweave}\end{verbatim}

\ques{latex/pdflatex is not found in R.app (Mac OS X) and [Possibly] R.exe (Windows)}

Your latex program is not in the default search path.  Put a line such as:

\begin{verbatim}Sys.setenv("PATH" = paste(Sys.getenv("PATH"),"/usr/texbin",sep=":"))\end{verbatim}
in your \verb".Rprofile" file.  
\end{document}