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

From Phyloinformatics
Jump to: navigation, search
m (R vignettes: Sweave: added link to windows LaTeX software)
 
(One intermediate revision by the same user not shown)
Line 11: Line 11:
 
* 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.
 
* 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.
 
**[http://www.uoregon.edu/~koch/texshop/ TexShop] for Mac systems is a great LaTeX editor that knows to open .Rnw files. I'd recommend installing the [http://www.tug.org/mactex/ 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. --[[User:Skembel|Skembel]] 19:39, 19 November 2007 (EST)
 
**[http://www.uoregon.edu/~koch/texshop/ TexShop] for Mac systems is a great LaTeX editor that knows to open .Rnw files. I'd recommend installing the [http://www.tug.org/mactex/ 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. --[[User:Skembel|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 [http://www.math.vanderbilt.edu/~schectex/wincd/list_tex.htm 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 <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.
+
* 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. ''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. --[[User:Bbolker|Bbolker]] 13:22, 1 December 2007 (EST)''
  
 
'''Examples'''
 
'''Examples'''

Latest revision as of 14:29, 1 December 2007

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)