R Hackathon 1/R Vignette HowTo

From Phyloinformatics
Revision as of 11:10, 19 November 2007 by Bco (talk)
Jump to: navigation, search

R vignettes: Sweave

(I just wrote a whole bunch of stuff about vignettes and Sweave and then clicked away to check something and lost about five paragraphs of work. How frustrating!)

Very briefly, then:

  • 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.
  • 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.

Links:

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