1 #LyX 2.0 created this file. For more info see http://www.lyx.org/
7 %% maxwidth is the original width if it's less than linewidth
8 %% otherwise use linewidth (to make sure the graphics do not exceed the margin)
10 \ifdim\Gin@nat@width>\linewidth
18 \use_default_options true
22 \maintain_unincluded_children false
24 \language_package auto
25 \inputencoding default
30 \font_default_family default
31 \use_non_tex_fonts false
38 \default_output_format default
40 \bibtex_command default
41 \index_command default
42 \paperfontsize default
54 \paperorientation portrait
67 \paragraph_separation indent
68 \paragraph_indentation default
69 \quotes_language english
72 \paperpagestyle default
73 \tracking_changes false
82 \begin_layout Standard
86 \begin_layout Plain Layout
90 SweaveOpts{prefix=TRUE,prefix.string=sweave-prefix,keep.source=FALSE}
98 \begin_layout Standard
102 \begin_layout Plain Layout
106 maxwidth was defined in the preamble; see document settings
109 \begin_layout Plain Layout
124 Using Sweave with LyX
132 \begin_layout Plain Layout
133 Department of Statistics, Iowa State University.
135 \begin_inset CommandInset href
137 name "xie@yihui.name"
138 target "xie@yihui.name"
152 \begin_layout Plain Layout
165 \begin_layout Plain Layout
177 \begin_layout Standard
178 Sweave is a tool in the R language (
179 \begin_inset Flex URL
182 \begin_layout Plain Layout
184 http://www.r-project.org
189 ) for dynamic report generation using the ideas of literate programming.
190 R code can be mixed into a LaTeX document, and will be executed in R when
191 the document is compiled; the results are written into the TeX output.
194 \begin_layout Standard
195 Since LyX 2.0, Sweave can be used out of the box with any document class
200 module, which means we no longer need to modify the
204 file manually or add special layouts such as
206 literate-article.layout
217 module to a LyX document from
219 Document\SpecialChar \menuseparator
220 Settings\SpecialChar \menuseparator
224 In this manual, we demonstrate some common features of Sweave and explain
225 how the module works.
226 A PDF version of this manual can be found at
227 \begin_inset Flex URL
230 \begin_layout Plain Layout
232 https://github.com/downloads/yihui/lyx/sweave.pdf
240 \begin_layout Section
244 \begin_layout Standard
249 module depends on the executable
253 , so it has to be in the
257 variable of the system.
258 It is usually not a problem for Linux and Mac OS users, but may be confusing
259 to Windows users; if you do not understand what is
263 under Windows, you may either use the R script
268 \begin_inset Flex URL
271 \begin_layout Plain Layout
273 https://github.com/yihui/lyx
278 to change it automatically (not recommended; you should learn
284 Tools\SpecialChar \menuseparator
285 Preferences\SpecialChar \menuseparator
286 Paths\SpecialChar \menuseparator
289 to add the bin path of R (recommended), which is often like
301 and you can find it in R:
304 \begin_layout Standard
308 \begin_layout Plain Layout
310 <<where-is-R-bin,eval=FALSE>>=
313 \begin_layout Plain Layout
318 \begin_layout Plain Layout
328 \begin_layout Standard
329 After you have done these changes, you need to reconfigure LyX by
331 Tools\SpecialChar \menuseparator
347 module will be unavailable.
348 It is recommended to use the latest version of R, since Sweave is still
350 Another dependency is introduced by the LaTeX style file
354 which is shipped with R under this path (it is not on CTAN):
357 \begin_layout Standard
361 \begin_layout Plain Layout
363 <<sweave-sty,eval=FALSE>>=
366 \begin_layout Plain Layout
368 file.path(R.home('share'), 'texmf', 'tex', 'latex')
371 \begin_layout Plain Layout
381 \begin_layout Standard
382 MikTeX users may add the texmf directory to the list of root directories
383 in MikTeX through MikTeX settings.
405 , it will directly copy from R, so the Sweave module works even if you do
406 not know where is this style file.
409 \begin_layout Section
413 \begin_layout Standard
414 Before we write an Sweave document, we can set some Sweave options; the
421 in Sweave and it can be inserted in a LyX document by
423 Insert\SpecialChar \menuseparator
424 Custom Insets\SpecialChar \menuseparator
427 , or just use TeX code to write it (
429 Insert\SpecialChar \menuseparator
433 For example, we can set a global option
437 in the beginning of a document to suppress all R code (by default, both
438 R code and its output will show up in the LaTeX document).
442 \begin_layout Standard
443 To write R code in LyX, you can first switch to the
447 environment in the layout styles list (droplist in the top-left corner
448 in the toolbar), or you can simply open a TeX code environment and write
449 Sweave code chunks in it.
450 The latter approach is recommended since it is more stable.
453 \begin_layout Standard
454 Some R options can be useful to the Sweave output as well, e.g.
464 The former option can adjust the width of the output, and the latter can
465 avoid a common problem with quotes.
466 Users are encouraged to read the Sweave manual in R for more details.
469 \begin_layout Standard
473 \begin_layout Plain Layout
475 <<setup, keep.source=TRUE>>=
478 \begin_layout Plain Layout
480 ## the option 'digits' can set the (approximate) number of digits
483 \begin_layout Plain Layout
485 options(width = 70, useFancyQuotes = FALSE, digits = 4)
488 \begin_layout Plain Layout
493 \begin_layout Plain Layout
495 <<sweave-manual, eval=FALSE, keep.source=TRUE>>=
498 \begin_layout Plain Layout
500 ## view the Sweave vignette (requires R >= 2.13.0)
503 \begin_layout Plain Layout
505 vignette("Sweave", package = "utils")
508 \begin_layout Plain Layout
518 \begin_layout Standard
519 A simple example that will run in any S engine:
522 \begin_layout Standard
526 \begin_layout Plain Layout
528 <<print-integers, keep.source=TRUE>>=
531 \begin_layout Plain Layout
533 ## the integers from 1 to 10 are
536 \begin_layout Plain Layout
541 \begin_layout Plain Layout
546 \begin_layout Plain Layout
548 <<hide-results, results=hide>>=
551 \begin_layout Plain Layout
553 ## intentionally hide the output by setting results=hide
556 \begin_layout Plain Layout
561 \begin_layout Plain Layout
571 \begin_layout Standard
572 We can also emulate a simple calculator:
575 \begin_layout Standard
579 \begin_layout Plain Layout
584 \begin_layout Plain Layout
589 \begin_layout Plain Layout
594 \begin_layout Plain Layout
604 \begin_layout Standard
605 Now we look at some Gaussian data:
608 \begin_layout Standard
612 \begin_layout Plain Layout
617 \begin_layout Plain Layout
619 set.seed(123) # for reproducibility
622 \begin_layout Plain Layout
627 \begin_layout Plain Layout
632 \begin_layout Plain Layout
637 \begin_layout Plain Layout
647 \begin_layout Standard
648 Note that we can easily integrate some numbers into standard text; this
649 is done with the command
655 , and the corresponding LyX menu is
657 Insert\SpecialChar \menuseparator
658 Custom Insets\SpecialChar \menuseparator
661 , or alternatively just use TeX code.
662 For example, the third element of the vector
667 \begin_inset Flex S/R expression
670 \begin_layout Plain Layout
683 \begin_inset Formula $p$
686 -value of the test is
687 \begin_inset Flex S/R expression
690 \begin_layout Plain Layout
692 format.pval(t1$p.value)
698 You can round these numbers using functions like
706 \begin_layout Standard
716 Now we look at a summary of the
737 \begin_layout Standard
741 \begin_layout Plain Layout
746 \begin_layout Plain Layout
751 \begin_layout Plain Layout
761 \begin_layout Standard
762 \begin_inset Float table
767 \begin_layout Plain Layout
770 \begin_layout Plain Layout
771 Quantiles of the first four variables in the
776 \begin_inset CommandInset label
778 name "tab:xtable-demo"
790 \begin_layout Plain Layout
795 \begin_layout Plain Layout
799 \begin_layout Plain Layout
801 <<xtable-demo,results=tex,echo=FALSE>>=
804 \begin_layout Plain Layout
806 if (require('xtable')) {
809 \begin_layout Plain Layout
811 print(xtable(sapply(iris[,-5], quantile)), floating=FALSE)
814 \begin_layout Plain Layout
816 } else cat('the xtable package is not available! please install.packages("xtable"
820 \begin_layout Plain Layout
835 \begin_layout Standard
836 Usually people do not like such
837 \begin_inset Quotes eld
841 \begin_inset Quotes erd
844 output, and we can polish these messy numbers with the
850 \begin_inset CommandInset ref
852 reference "tab:xtable-demo"
856 is an example demonstrating how to use the
860 package with Sweave; note the chunk option
864 makes sure that the R output is written out as raw LaTeX code instead of
865 being wrapped in a special environment (
872 \begin_layout Standard
874 \begin_inset CommandInset ref
876 reference "fig:iris-pairs"
881 \begin_inset CommandInset ref
883 reference "fig:iris-boxplots"
887 are two simple examples of producing graphics output with Sweave.
890 \begin_layout Standard
891 \begin_inset Float figure
896 \begin_layout Plain Layout
901 \begin_layout Plain Layout
903 <<iris-pairs,fig=TRUE,width=4.5,height=4.5>>=
906 \begin_layout Plain Layout
908 pairs(iris, col = iris$Species)
911 \begin_layout Plain Layout
921 \begin_layout Plain Layout
924 \begin_layout Plain Layout
925 Scatter plot matrix of the
930 \begin_inset CommandInset label
932 name "fig:iris-pairs"
949 \begin_layout Standard
950 \begin_inset Float figure
955 \begin_layout Plain Layout
960 \begin_layout Plain Layout
962 <<iris-boxplots,fig=TRUE,width=7,height=2,keep.source=F>>=
965 \begin_layout Plain Layout
967 par(mar=c(4,5,.1,.3), las=1)
970 \begin_layout Plain Layout
972 boxplot(Sepal.Length~Species,data=iris,horizontal=TRUE,xlab='Sepal.Length')
975 \begin_layout Plain Layout
985 \begin_layout Plain Layout
988 \begin_layout Plain Layout
989 Boxplots of sepal length grouped by species.
990 \begin_inset CommandInset label
992 name "fig:iris-boxplots"
1009 \begin_layout Standard
1010 We can also export all the R code in an Sweave document as a single R script
1013 File\SpecialChar \menuseparator
1014 Export\SpecialChar \menuseparator
1017 ), which is done via
1024 \begin_layout Section
1032 \begin_layout Standard
1037 module declares that a LyX document contains literate programming components
1038 with R, so that LyX will handle such documents according to the specific
1039 converters (see the Customization manual).
1048 converter, which essentially consists of an R script
1057 This script takes an
1061 document from LyX and call Sweave to process it to a TeX document, then
1062 LyX takes care of the rest of work.
1065 \begin_layout Standard
1066 The converter from the
1070 format to LaTeX is a call to R via the command line as:
1073 \begin_layout Standard
1077 \begin_layout Plain Layout
1084 \begin_layout Plain Layout
1086 Rscript --no-save --no-restore $$s/scripts/lyxsweave.R $$p$$i $$p$$o $$e
1090 \begin_layout Plain Layout
1102 \begin_layout Standard
1103 The LyX library directory
1107 can be found from the menu
1109 Help\SpecialChar \menuseparator
1113 All the rest of options passed to R are explained in the R script, and
1114 the LyX Customization manual also has detailed explanations about
1131 General users do not need to know clearly what they mean, but here we need
1132 to explain a few issues in the R code:
1135 \begin_layout Enumerate
1136 the encoding string of the LyX document is passed to R as an command line
1137 option; possible values are
1146 The encoding is used for R to read the
1153 \begin_layout Enumerate
1154 the R code chunks in the Sweave document are executed under the directory
1155 of the LyX document (if you are not sure, put
1159 in a code chunk to see what is the current working directory).
1160 In this case, you can put data files under the same directory and use relative
1161 paths in R to guarantee reproducibility, i.e.
1162 we do not need to write hard-coded paths which may not exist in other systems.
1165 \begin_layout Enumerate
1166 if LaTeX cannot find
1170 , this R script will copy it to the temporary directory automatically where
1171 the LaTeX compilation takes place.
1174 \begin_layout Enumerate
1175 Sweave will use the filename of the Rnw file as the prefix string for the
1176 graphics output by default; one known issue (
1177 \begin_inset CommandInset href
1180 target "http://www.lyx.org/trac/ticket/7551"
1184 ) is that if the filename (without extension) contains dots, LaTeX can fail
1185 to deal with such files in
1192 Therefore, we have set the default value of the prefix to be the filename
1193 with all the dots being replaced by
1194 \begin_inset Quotes eld
1198 \begin_inset Quotes erd
1202 We can also solve this problem in Sweave directly: set the Sweave option
1207 to be a character string without dots, and this option will override the
1211 \begin_layout Standard
1212 We have pre-specified an option
1216 for the Sweave package.
1217 This option stops Sweave from loading these two packages:
1220 \begin_layout Standard
1224 \begin_layout Plain Layout
1231 \begin_layout Plain Layout
1235 RequirePackage[T1]{fontenc}
1238 \begin_layout Plain Layout
1245 \begin_layout Plain Layout
1257 \begin_layout Standard
1258 LyX can deal with the font encoding by default, so there is no need to ask
1259 Sweave to do this (furthermore, this may bring clashes of package options);
1260 besides, the users can load the
1264 package by themselves in the preamble if needed.
1267 \begin_layout Section
1271 \begin_layout Standard
1272 Since LyX 2.0, we can see the detailed information during compilation via
1275 View\SpecialChar \menuseparator
1279 This is extremely helpful for trouble shooting -- the process of R will
1280 be shown in the message panel, and we will be able to know which chunk
1281 goes wrong in cases of errors.
1282 For example, when you compile this document, you can see messages like
1286 \begin_layout Standard
1290 \begin_layout Plain Layout
1297 \begin_layout Plain Layout
1299 17:58:47.868: Processing code chunks with options ...
1302 \begin_layout Plain Layout
1304 17:58:47.885: 1 : echo keep.source term verbatim (label=setup)
1307 \begin_layout Plain Layout
1309 17:58:47.889: 2 : echo keep.source (label=sweave-manual)
1312 \begin_layout Plain Layout
1314 17:58:47.908: 3 : echo keep.source term verbatim (label=print-integers)
1317 \begin_layout Plain Layout
1322 \begin_layout Plain Layout
1324 17:58:47.941: Loading required package: xtable
1327 \begin_layout Plain Layout
1329 17:58:47.976: 9 : echo term verbatim pdf (label=iris-pairs)
1332 \begin_layout Plain Layout
1337 \begin_layout Plain Layout
1339 17:58:48.116: You can now run (pdf)latex on 'sweave.tex'
1342 \begin_layout Plain Layout
1354 \begin_layout Standard
1360 If any chunk causes an error in R, you will see the error message here
1364 \begin_layout Standard
1365 Another known issue is the Sweave code chunk may fail when we change the
1366 alignment of the chunk paragraph in LyX (using
1370 ), because LyX may add a macro like
1376 before the code chunk without adding a new line, which will lead to a code
1380 \begin_layout Standard
1384 \begin_layout Plain Layout
1391 \begin_layout Plain Layout
1395 centering{}<<xtable-demo,results=tex,echo=FALSE>>=
1398 \begin_layout Plain Layout
1410 \begin_layout Standard
1411 This is not a legitimate Sweave code chunk, since
1415 must start in a new line with nothing before it.
1416 Therefore we recommend you to double check the real source code via
1418 View\SpecialChar \menuseparator
1421 when changing the alignment of a chunk paragraph, and make sure
1425 appears in a new line.
1426 This explains why we manually added an empty line in the code chunk in
1428 \begin_inset CommandInset ref
1430 reference "tab:xtable-demo"
1437 \begin_layout Section
1441 \begin_layout Standard
1442 The homepage of Sweave is at
1443 \begin_inset Flex URL
1446 \begin_layout Plain Layout
1448 http://www.stat.uni-muenchen.de/~leisch/Sweave/
1454 The CRAN task view on
1455 \begin_inset Quotes eld
1458 Reproducible Research
1459 \begin_inset Quotes erd
1462 has a list of Sweave-related packages which can be potentially useful;
1464 \begin_inset Flex URL
1467 \begin_layout Plain Layout
1469 http://cran.r-project.org/web/views/ReproducibleResearch.html
1475 Questions about LyX and Sweave can be posted to the LyX mailing list (
1476 \begin_inset Flex URL
1479 \begin_layout Plain Layout
1481 http://www.lyx.org/MailingLists
1487 More LyX examples are provided at
1488 \begin_inset Flex URL
1491 \begin_layout Plain Layout
1493 https://github.com/yihui/lyx
1501 \begin_layout Section
1505 \begin_layout Subsection
1506 How to use Sweave with beamer?
1509 \begin_layout Standard
1510 You will end up with LaTeX errors if you use Sweave in beamer slides in
1511 LyX; the reason is the beamer frame that contains verbatim R code and output
1517 However, currently there is no straightforward way to do this.
1518 One way is to write raw TeX code, and the other is to use the
1520 beamer-fragile.module
1523 \begin_inset CommandInset href
1526 target "http://www.lyx.org/trac/ticket/7273"
1530 (put this file under the
1534 directory of LyX user directory and reconfigure LyX).
1535 After including this module in your document, you should be able to use
1538 Insert\SpecialChar \menuseparator
1539 Custom Insets\SpecialChar \menuseparator
1542 , which is essentially
1546 begin{frame}[fragile]
1551 \begin_layout Subsection
1552 Can I define my own R script to compile the Rnw document?
1555 \begin_layout Standard
1557 First you need to understand how the R script
1561 /scripts/lyxsweave.R
1563 works, which was introduced previously, and we recommend you to read the
1564 R source code as well (on how R takes the paths and uses
1568 to handle the Rnw document).
1569 Then you put your customized
1583 Help\SpecialChar \menuseparator
1587 Note LyX will check the
1591 before going to its own
1599 is found in the user directory, it will be used.
1600 It is not recommended to hack the script under the LyX library directory
1601 directly, since updating LyX will override you modified script (the user
1602 directory will not be affected).
1605 \begin_layout Standard
1606 Beside the support for the official Sweave in R, the
1610 package is also supported, which is an alternative tool to Sweave; the
1611 corresponding module is named