R Hackathon 1/R Vignette HowTo

From Phyloinformatics
Jump to: navigation, search

R vignettes: Sweave

  • R has two kinds of documentation: manual pages and vignettes. Manual pages are typically brief reminders -- they can (and should) contain examples, but don't give much context and are rarely useful when starting from scratch.
  • Vignettes are longer documents designed to showcase typical uses of a package. They are written in Sweave, which is itself based on LaTeX (but see below). An Sweave document is essentially a LaTeX file with code chunks that begin with a line containing only

<<>>= (in the simplest case) and end with a line containing only at @ symbol. When you run the Sweave() command from inside R, it runs the code in the code chunks. Depending on the options contained within the double-angle-brackets, R creates a processed version of the original file that may contain formatted versions of the code, figures produced by the code, tables of values produced by the code, etc. For example, a code chunk that starts with <<echo=FALSE,fig=TRUE>>= (and contains R code that produces a figure) will not include the code in the processed document but will include the resulting figure.

  • To write vignettes, you need to know enough R to write the code chunks and enough LaTeX to write the rest of the document. There are various helper applications for learning/writing LaTeX, but I don't know any of them very well (TeXshop [MacOS], Lyx [Linux, Windows, Mac]); these helper applications may have extensions that understand Sweave, but all you really need them to do is understand that a .Rnw file should be treated as a (La)TeX file. Many of the code editors for R (Emacs/ESS, Tinn-R, etc.) understand Sweave files.
    • TexShop for Mac systems is a great LaTeX editor that knows to open .Rnw files. I'd recommend installing the MacTex distribution which is a one-click install of LaTeX, TexShop and a bunch of other stuff for Mac users. If you've installed MacTex and R, you can quickly generate PDFs of R vignettes by typing Sweave("filename.Rnw") in R, using TexShop to open the resulting filename.tex that is created in your R working directory, and then command-T to typeset the file as a PDF. There's probably a way to do all of this in one step from within R or within TexShop but I don't know it offhand. --Skembel 19:39, 19 November 2007 (EST)
    • I don't know whether we have a need for equivalent Windows friendly front-ends, and don't know too much about them, but here's a list of free TeX front ends for Window
  • The contributed package odfWeave allows vignettes to be written in ODF (Open Document Format) instead of LaTeX: that is, the base file would be an ODF document with code chunks set off by <<>>= and @. Open Office will write ODF files; so will MS Word, in principle, with a plugin provided by Sun [see below]. So, apparently, it should be possible to write vignettes in MS Word (!). I haven't tried this and don't know if it will work with the standard package-building stuff in R or not. I don't think it will work with the package building, without significant (and probably not worth it) hacking efforts; probably finding good LaTeX tools is the best time investment. --Bbolker 13:22, 1 December 2007 (EST)

Examples

  • Sweave-formatted vignette files typically have the .Rnw or .Snw extension. From R, the vignette() command will list the vignettes available on your system. The Sweave files for a vignette typically reside in the $RHOME/library/packagename/doc/ directory.
  • The grid package includes several vignettes. Here is the Sweave code Media:Grid.Snw.txt and resulting PDF vignette Media:grid.pdf.
  • Jari Oksanen's vegan package for ecologists contains several vignettes. Here is the Sweave code Media:Intro-vegan.Rnw.txt and resulting PDF vignette Media:Intro-vegan.pdf.

Links

--Bbolker 15:00, 18 November 2007 (EST)