1. install LyX and R as well as a working LaTeX toolkit such as MikTeX or TeXLive or MacTeX;
2. run source('http://yihui.name/en/wp-content/uploads/2010/10/lyx-pgfsweave-config.R') in R under Windows or Ubuntu or Mac; I tried my best to automatically configure LaTeX, R and LyX;
3. restart LyX as instructed, and you can enjoy pgfSweave in LyX now — either play with my demo (click to download), or DIY: create a new document, change the document class to article (Sweave noweb) from Document –> Settings, switch the environment to Scrap from the top-left drop list, start your Sweave code chunks like
   <<test>>= rnorm(10) @
   and click the PDF button to compile this document. Done. Take a look at this video if you feel confused.

This works for MikTeX under Windows (Server 2003 / Win7), and TeXLive 2009 under Ubuntu 10.10, MacTeX 2010 under Mac OS; R 2.12.0 or 2.11.1; LyX 1.6.x. Gregor Gorjanc published an interesting article “Using Sweave with LyX” in R News in 2008, which (I believe) makes it much easier to use Sweave. I use command-line tools a lot every day, but I am still “GUI-addicted”. (I don’t want to comment more about Microsoft Word here.) LyX is a somewhat WYSIWYG tool based on LaTeX, and on the first time I saw it I decided that Word was completely useless to me from then on. In the past, I did not like writing LaTeX documents just because I hate wasting my time on typing the raw commands. For example, I hate typing \item in an itemize environment each time I need a new item. There might be some text editors which can automatically do this tedious task, but the more serious problem is I cannot see the whole picture — in my eyes there are only commands; my imagination is limited — it is difficult for me to imagine \section{} to be a section title. However, LyX has provided a perfect solution to lazy people like me. We don’t have to write LaTeX documents from scratch, and everything is intuitive in LyX. You can clearly see the structure of your document, as well as figures (instead of \includegraphics{}), tables (instead of the gory \begin{table} numbers 1.4 & 2.2 & 3.8), headings (instead of \title{} \section{}) and math formulae (instead of $\frac{\gamma}{\alpha_{ij}}$)… In all, it is a whole lot easier and faster to write LaTeX documents in LyX. This is the main reason for an easier life of Sweave, because a Sweave document is nothing but a mixture of LaTeX and R code.

1. Introduction

Although Sweave in LyX is convenient to use, it is not a trivial task for beginners to configure and understand how it works. The video below can give you an idea on what it looks like in LyX (Chinese visitors please go to Photobucket or 56.com to watch the video):

As we can see, R code can be easily embedded into LyX. If you are familiar with Sweave, you don’t even need time to learn anything. For those who do not know Sweave well, a good place to look at is the help page ?Sweave. A Sweave document is dynamic in the sense that everything in the document can be changed by the R code (nothing is hard-coded), so we don’t need to worry too much about the specific numbers and plots in the output. Instead, we focus on the code which produces these output. In the above video, I used a LaTeX macro \Sexpr{} to output the value of pi and I don’t need to write the specific number 3.1415926 there.

2. pgfSweave

While Sweave is a great invention for reproducible research, there are other packages which can improve R’s default Sweave functionality. A brilliant one is the pgfSweave package. It was built upon the cacheSweave package to support caching R objects (to avoid unnecessary repeated computations and save time), and it also provided a mechanism to cache graphics! Beside the speed issues, a remarkable feature is the quality of graphics — it is unbeatable. I’m not exaggerating. This packages uses the tikzDevice package to produce pgf/tikz graphics which are essentially LaTeX code, in other words, the R graphics are represented in the LaTeX language so that they are treated (compiled) in the same way as the body of a LaTeX document. This will make the style of graphics completely consistent with the body of a document, e.g. the fonts.

By the way, I also like the nogin option for Sweave.sty to be the default in pgfSweave, because I really don’t like the idea of setting the size of graphics by a LaTeX macro \setkeys{Gin}{width=0.8\textwidth}. In pgfSweave, we just set the width and height naturally in the code chunk options like <<width = 5, height =4>>=.

pgfSweave comes with a command line usage like Sweave: R CMD pgfSweave your-file.Rnw. I’m not using this approach in LyX, because this requires system admin privilege to install pgfSweave. Instead, I use this way:

R -q -e "library(pgfSweave);pgfSweave('yourfile.Rnw')"

R can accept a string in its -e argument, e.g.

yihui@xie:~$ R -q -e "rnorm(5)"
> rnorm(5)
[1] -0.2970093 -0.2171444  1.5645127  0.5422097  0.7359204

Later I’ll explain how to connect LyX and R/pgfSweave in this way.

3. Configuration

To make LyX work with Sweave, we need to take these steps:

1. put the LaTeX style files such as Sweave.sty under the texmf tree
2. define the literate programming environment in LyX (literate-scrap.inc) and corresponding layouts
3. (the critical step) create converters to convert Sweave documents to LaTeX (this is done in the preferences file) and the converter is like
   R -e "library(pgfSweave);pgfSweave($$i,compile.tex=FALSE)"
   where $$i is a variable in LyX denoting the input file

Each step involves with several novel concepts for beginners. For example, you may ask “what’s a texmf tree?” “What’s a layout file? Where is it?” “Where is the preference file?” “What’s a converter?”…

I spent several hours on writing an R script trying to cover all these gory details automatically, so the configuration becomes as easy as

source('http://yihui.name/en/wp-content/uploads/2010/10/lyx-pgfsweave-config.R')

This is convenient, which is good. But I have to confess it is a really nasty script — (for Windows) it calls several system commands to help the configuration, such as initexmf or mpm, or setx to set the system PATH variable; this is a dangerous practice and some users may feel extremely uncomfortable with it. Under Mac and Linux, it tries to download and copy files to your home directory so that LaTeX and LyX will work properly. It will do no harm to your system, but I need to warn you first in the spirit of “open source”.

4. Gory Details

You are still reading… So first you have to read Gregor Gorjanc’s paper in R News and that make most things clear in this blog entry. A few more things I need to add are:

1. I modified the file literate-scrap.inc so that we can hit the Enter key to start a new line in R code, which is more natural for the users, I think. Gregor’s original definition for breaking a line was Ctrl+Enter.
2. I added another environment in LyX named ScrapCenter, which is for the code chunks that produce plots, because plots are usually centered in the page.
3. I also modified Sweave.sty to add line numbers to the code chunks in LaTeX, and the real Sweave style file I’m using is SweaveX.sty.
4. I did not add R’s texmf directory to the root directory of MikTeX; instead I copied all the files to the user directory of MikTeX (this can be a bad practice too) and I did the same thing to Mac and Ubuntu. This will make LaTeX know the style definitions for Sweave.
5. I copied LyX configurations to the user directory of LyX as well. I need to mention here that all the old configurations will be overwritten except the preferences file, with which I handled in a special way: if I could detect the Sweave configurations in the old preferences, I will not do anything, otherwise I will append the Sweave configurations (converters) to the old preferences file. This makes sense, I believe. Users do not want their preferences to be overwritten.
6. Under Mac and Windows, the path for LyX was hard-coded as LyX16, which is surely subject to changes in future when new versions of LyX come out. Linux usually stores configurations in the home directory as folders with a dot, e.g. ~/.lyx. This is good because we don’t need to worry about the version numbers.
7. pgfSweave will try to format your R code by default, e.g. add spaces and indent where appropriate when your source code is not well-formatted. This is my suggestion (and contribution), and I think this makes sense because many users just do not care about formatting R code (hence torture other people’s eyes), so let’s do it automatically with pgfSweave. Unfortunately pgfSweave has not been adapted to R 2.12.0 in this aspect — there is a tiny bug for the time being: a comment line indicating the line number will be added to the beginning of the code chunk. This is a new feature of R 2.12.0 (reporting line numbers in case of errors), and I’m still trying to figure out how to get around it.

5. Demo

After you have got everything ready, here are two demos that you can play with:

LyX and pgfSweave demo (7.6K)

I hope this is useful to the community. Please feel free to report problems during your installation and configuration.

Related Posts

• Press Enter in LyX Sweave as You Wish
• Font Families for the R PDF Device
• On the Gory Loops in R
• SyntaxHighlighter Brush for the R Language
• Auto-completion in Notepad++ for R Script