Difference between revisions of "R Hackathon 1/R Vignette HowTo"

From Phyloinformatics
Jump to: navigation, search
(creation)
 
Line 1: Line 1:
 
 
= R vignettes: Sweave =
 
= R vignettes: Sweave =
  
Line 8: Line 7:
 
* 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.
 
* 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 written in '''Sweave''', which is itself based on '''LaTeX''' (but see below).
+
* 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
 +
<nowiki>
 +
<<>>=
 +
</nowiki>
 +
 
 +
(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 <nowiki><<echo=FALSE,fig=TRUE>>=</nowiki> (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 <nowiki><<>>=</nowiki> 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:
 +
* [http://www.ci.tuwien.ac.at/~leisch/Sweave/  Sweave directory] including FAQ, manual, etc.
 +
* [http://www.stat.umn.edu/~charlie/Sweave/ Sweave demos] from Charlie Geyer at Univ. Minn.
 +
* [http://wiki.lyx.org/LyX/LyxWithRThroughSweave Sweave with Lyx]
 +
* [http://www.sun.com/software/star/odf_plugin/ ODF plugin for MS office], from Sun (tried to install this under Crossover Office on Linux, doesn't work)
 +
 
 +
--[[User:Bbolker|Bbolker]] 15:00, 18 November 2007 (EST)

Revision as of 16:00, 18 November 2007

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)