1 #LyX 2.1 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
31 \font_default_family default
32 \use_non_tex_fonts false
38 \default_output_format default
40 \bibtex_command default
41 \index_command default
42 \paperfontsize default
47 \use_package amsmath 1
48 \use_package amssymb 1
50 \use_package mathdots 1
51 \use_package mathtools 0
53 \use_package stackrel 0
54 \use_package stmaryrd 0
55 \use_package undertilde 0
57 \cite_engine_type numerical
61 \paperorientation portrait
75 \paragraph_separation indent
76 \paragraph_indentation default
77 \quotes_language english
80 \paperpagestyle default
81 \tracking_changes false
90 \begin_layout Standard
94 \begin_layout Plain Layout
98 SweaveOpts{prefix=TRUE,prefix.string=sweave-prefix,keep.source=FALSE}
106 \begin_layout Standard
110 \begin_layout Plain Layout
114 maxwidth was defined in the preamble; see document settings
117 \begin_layout Plain Layout
132 Using Sweave with LyX
140 \begin_layout Plain Layout
141 Department of Statistics, Iowa State University.
143 \begin_inset CommandInset href
145 name "xie@yihui.name"
146 target "xie@yihui.name"
160 \begin_layout Plain Layout
173 \begin_layout Plain Layout
185 \begin_layout Standard
186 Sweave is a tool in the R language (
187 \begin_inset Flex URL
190 \begin_layout Plain Layout
192 http://www.r-project.org
197 ) for dynamic report generation using the ideas of literate programming.
198 R code can be mixed into a LaTeX document, and will be executed in R when
199 the document is compiled; the results are written into the TeX output.
202 \begin_layout Standard
203 Since LyX 2.0, Sweave can be used out of the box with any document class
213 module to a LyX document from
215 Document\SpecialChar \menuseparator
216 Settings\SpecialChar \menuseparator
220 In this manual, we demonstrate some common features of Sweave and explain
221 how the module works.
222 A PDF version of this manual can be found at
223 \begin_inset Flex URL
226 \begin_layout Plain Layout
228 https://github.com/downloads/yihui/lyx/sweave.pdf
236 \begin_layout Section
240 \begin_layout Standard
245 module depends on the executable
249 , so it has to be in the
253 variable of the system.
254 It is usually not a problem for Linux and Mac OS users, but may be confusing
255 to Windows users; if you do not understand what is
259 under Windows, you may either use the R script
264 \begin_inset Flex URL
267 \begin_layout Plain Layout
269 https://github.com/yihui/lyx
274 to change it automatically (not recommended; you should learn
280 Tools\SpecialChar \menuseparator
281 Preferences\SpecialChar \menuseparator
282 Paths\SpecialChar \menuseparator
285 to add the bin path of R (recommended), which is often like
297 and you can find it in R:
300 \begin_layout Standard
304 \begin_layout Plain Layout
306 <<where-is-R-bin,eval=FALSE>>=
309 \begin_layout Plain Layout
314 \begin_layout Plain Layout
324 \begin_layout Standard
325 After you have done these changes, you need to reconfigure LyX by
327 Tools\SpecialChar \menuseparator
343 module will be unavailable.
344 It is recommended to use the latest version of R, since Sweave is still
346 Another dependency is introduced by the LaTeX style file
350 which is shipped with R under this path (it is not on CTAN):
353 \begin_layout Standard
357 \begin_layout Plain Layout
359 <<sweave-sty,eval=FALSE>>=
362 \begin_layout Plain Layout
364 file.path(R.home('share'), 'texmf', 'tex', 'latex')
367 \begin_layout Plain Layout
377 \begin_layout Standard
378 MikTeX users may add the texmf directory to the list of root directories
379 in MikTeX through MikTeX settings.
401 , it will directly copy from R, so the Sweave module works even if you do
402 not know where is this style file.
405 \begin_layout Section
409 \begin_layout Standard
410 Before we write an Sweave document, we can set some Sweave options; the
417 in Sweave and it can be inserted in a LyX document by
419 Insert\SpecialChar \menuseparator
420 Custom Insets\SpecialChar \menuseparator
423 , or just use TeX code to write it (
425 Insert\SpecialChar \menuseparator
429 For example, we can set a global option
433 in the beginning of a document to suppress all R code (by default, both
434 R code and its output will show up in the LaTeX document).
438 \begin_layout Standard
439 To write R code in LyX, you can first switch to the
443 environment in the layout styles list (droplist in the top-left corner
444 in the toolbar), or you can simply open a TeX code environment and write
445 Sweave code chunks in it.
446 The latter approach is recommended since it is more stable.
449 \begin_layout Standard
450 Some R options can be useful to the Sweave output as well, e.g.
460 The former option can adjust the width of the output, and the latter can
461 avoid a common problem with quotes.
462 Users are encouraged to read the Sweave manual in R for more details.
465 \begin_layout Standard
469 \begin_layout Plain Layout
471 <<setup, keep.source=TRUE>>=
474 \begin_layout Plain Layout
476 ## the option 'digits' can set the (approximate) number of digits
479 \begin_layout Plain Layout
481 options(width = 70, useFancyQuotes = FALSE, digits = 4)
484 \begin_layout Plain Layout
489 \begin_layout Plain Layout
491 <<sweave-manual, eval=FALSE, keep.source=TRUE>>=
494 \begin_layout Plain Layout
496 ## view the Sweave vignette (requires R >= 2.13.0)
499 \begin_layout Plain Layout
501 vignette("Sweave", package = "utils")
504 \begin_layout Plain Layout
514 \begin_layout Standard
515 A simple example that will run in any S engine:
518 \begin_layout Standard
522 \begin_layout Plain Layout
524 <<print-integers, keep.source=TRUE>>=
527 \begin_layout Plain Layout
529 ## the integers from 1 to 10 are
532 \begin_layout Plain Layout
537 \begin_layout Plain Layout
542 \begin_layout Plain Layout
544 <<hide-results, results=hide>>=
547 \begin_layout Plain Layout
549 ## intentionally hide the output by setting results=hide
552 \begin_layout Plain Layout
557 \begin_layout Plain Layout
567 \begin_layout Standard
568 We can also emulate a simple calculator:
571 \begin_layout Standard
575 \begin_layout Plain Layout
580 \begin_layout Plain Layout
585 \begin_layout Plain Layout
590 \begin_layout Plain Layout
600 \begin_layout Standard
601 Now we look at some Gaussian data:
604 \begin_layout Standard
608 \begin_layout Plain Layout
613 \begin_layout Plain Layout
615 set.seed(123) # for reproducibility
618 \begin_layout Plain Layout
623 \begin_layout Plain Layout
628 \begin_layout Plain Layout
633 \begin_layout Plain Layout
643 \begin_layout Standard
644 Note that we can easily integrate some numbers into standard text; this
645 is done with the command
651 , and the corresponding LyX menu is
653 Insert\SpecialChar \menuseparator
654 Custom Insets\SpecialChar \menuseparator
657 , or alternatively just use TeX code.
658 For example, the third element of the vector
663 \begin_inset Flex S/R expression
666 \begin_layout Plain Layout
679 \begin_inset Formula $p$
682 -value of the test is
683 \begin_inset Flex S/R expression
686 \begin_layout Plain Layout
688 format.pval(t1$p.value)
694 You can round these numbers using functions like
702 \begin_layout Standard
712 Now we look at a summary of the
733 \begin_layout Standard
737 \begin_layout Plain Layout
742 \begin_layout Plain Layout
747 \begin_layout Plain Layout
757 \begin_layout Standard
758 \begin_inset Float table
763 \begin_layout Plain Layout
764 \begin_inset Caption Standard
766 \begin_layout Plain Layout
767 Quantiles of the first four variables in the
772 \begin_inset CommandInset label
774 name "tab:xtable-demo"
786 \begin_layout Plain Layout
791 \begin_layout Plain Layout
795 \begin_layout Plain Layout
797 <<xtable-demo,results=tex,echo=FALSE>>=
800 \begin_layout Plain Layout
802 if (require('xtable')) {
805 \begin_layout Plain Layout
807 print(xtable(sapply(iris[,-5], quantile)), floating=FALSE)
810 \begin_layout Plain Layout
812 } else cat('the xtable package is not available! please install.packages("xtable"
816 \begin_layout Plain Layout
831 \begin_layout Standard
832 Usually people do not like such
833 \begin_inset Quotes eld
837 \begin_inset Quotes erd
840 output, and we can polish these messy numbers with the
846 \begin_inset CommandInset ref
848 reference "tab:xtable-demo"
852 is an example demonstrating how to use the
856 package with Sweave; note the chunk option
860 makes sure that the R output is written out as raw LaTeX code instead of
861 being wrapped in a special environment (
868 \begin_layout Standard
870 \begin_inset CommandInset ref
872 reference "fig:iris-pairs"
877 \begin_inset CommandInset ref
879 reference "fig:iris-boxplots"
883 are two simple examples of producing graphics output with Sweave.
886 \begin_layout Standard
887 \begin_inset Float figure
892 \begin_layout Plain Layout
894 \begin_inset Note Note
897 \begin_layout Plain Layout
898 Both eps and pdf are set to true so that both latex and pdflatex work.
899 In practice, you would probably just choose one.
908 \begin_layout Plain Layout
910 <<iris-pairs,fig=TRUE,width=4.5,height=4.5,eps=TRUE,pdf=TRUE>>=
913 \begin_layout Plain Layout
915 pairs(iris, col = iris$Species)
918 \begin_layout Plain Layout
928 \begin_layout Plain Layout
929 \begin_inset Caption Standard
931 \begin_layout Plain Layout
932 Scatter plot matrix of the
937 \begin_inset CommandInset label
939 name "fig:iris-pairs"
956 \begin_layout Standard
957 \begin_inset Float figure
962 \begin_layout Plain Layout
967 \begin_layout Plain Layout
969 <<iris-boxplots,fig=TRUE,width=7,height=2,keep.source=F,eps=T,pdf=T>>=
972 \begin_layout Plain Layout
974 par(mar=c(4,5,.1,.3), las=1)
977 \begin_layout Plain Layout
979 boxplot(Sepal.Length~Species,data=iris,horizontal=TRUE,xlab='Sepal.Length')
982 \begin_layout Plain Layout
992 \begin_layout Plain Layout
993 \begin_inset Caption Standard
995 \begin_layout Plain Layout
996 Boxplots of sepal length grouped by species.
997 \begin_inset CommandInset label
999 name "fig:iris-boxplots"
1016 \begin_layout Standard
1017 We can also export all the R code in an Sweave document as a single R script
1020 File\SpecialChar \menuseparator
1021 Export\SpecialChar \menuseparator
1024 ), which is done via
1031 \begin_layout Section
1039 \begin_layout Standard
1044 module declares that a LyX document contains literate programming components
1045 with R, so that LyX will handle such documents according to the specific
1046 converters (see the Customization manual).
1055 converter, which essentially consists of an R script
1064 This script takes an
1068 document from LyX and call Sweave to process it to a TeX document, then
1069 LyX takes care of the rest of work.
1072 \begin_layout Standard
1073 The converter from the
1077 format to LaTeX is a call to R via the command line as:
1080 \begin_layout Standard
1084 \begin_layout Plain Layout
1091 \begin_layout Plain Layout
1093 Rscript --no-save --no-restore $$s/scripts/lyxsweave.R $$p$$i $$p$$o $$e
1097 \begin_layout Plain Layout
1109 \begin_layout Standard
1110 The LyX library directory
1114 can be found from the menu
1116 Help\SpecialChar \menuseparator
1120 All the rest of options passed to R are explained in the R script, and
1121 the LyX Customization manual also has detailed explanations about
1138 General users do not need to know clearly what they mean, but here we need
1139 to explain a few issues in the R code:
1142 \begin_layout Enumerate
1143 the encoding string of the LyX document is passed to R as an command line
1144 option; possible values are
1153 The encoding is used for R to read the
1160 \begin_layout Enumerate
1161 the R code chunks in the Sweave document are executed under the directory
1162 of the LyX document (if you are not sure, put
1166 in a code chunk to see what is the current working directory).
1167 In this case, you can put data files under the same directory and use relative
1168 paths in R to guarantee reproducibility, i.e.
1169 we do not need to write hard-coded paths which may not exist in other systems.
1172 \begin_layout Enumerate
1173 if LaTeX cannot find
1177 , this R script will copy it to the temporary directory automatically where
1178 the LaTeX compilation takes place.
1181 \begin_layout Enumerate
1182 Sweave will use the filename of the Rnw file as the prefix string for the
1183 graphics output by default; one known issue (
1184 \begin_inset CommandInset href
1187 target "http://www.lyx.org/trac/ticket/7551"
1191 ) is that if the filename (without extension) contains dots, LaTeX can fail
1192 to deal with such files in
1199 Therefore, we have set the default value of the prefix to be the filename
1200 with all the dots being replaced by
1201 \begin_inset Quotes eld
1205 \begin_inset Quotes erd
1209 We can also solve this problem in Sweave directly: set the Sweave option
1214 to be a character string without dots, and this option will override the
1218 \begin_layout Standard
1219 We have pre-specified an option
1223 for the Sweave package.
1224 This option stops Sweave from loading these two packages:
1227 \begin_layout Standard
1231 \begin_layout Plain Layout
1238 \begin_layout Plain Layout
1242 RequirePackage[T1]{fontenc}
1245 \begin_layout Plain Layout
1252 \begin_layout Plain Layout
1264 \begin_layout Standard
1265 LyX can deal with the font encoding by default, so there is no need to ask
1266 Sweave to do this (furthermore, this may bring clashes of package options);
1267 besides, the users can load the
1271 package by themselves in the preamble if needed.
1274 \begin_layout Section
1278 \begin_layout Standard
1279 Since LyX 2.0, we can see the detailed information during compilation via
1282 View\SpecialChar \menuseparator
1286 This is extremely helpful for trouble shooting -- the process of R will
1287 be shown in the message panel, and we will be able to know which chunk
1288 goes wrong in cases of errors.
1289 For example, when you compile this document, you can see messages like
1293 \begin_layout Standard
1297 \begin_layout Plain Layout
1304 \begin_layout Plain Layout
1306 17:58:47.868: Processing code chunks with options ...
1309 \begin_layout Plain Layout
1311 17:58:47.885: 1 : echo keep.source term verbatim (label=setup)
1314 \begin_layout Plain Layout
1316 17:58:47.889: 2 : echo keep.source (label=sweave-manual)
1319 \begin_layout Plain Layout
1321 17:58:47.908: 3 : echo keep.source term verbatim (label=print-integers)
1324 \begin_layout Plain Layout
1329 \begin_layout Plain Layout
1331 17:58:47.941: Loading required package: xtable
1334 \begin_layout Plain Layout
1336 17:58:47.976: 9 : echo term verbatim pdf (label=iris-pairs)
1339 \begin_layout Plain Layout
1344 \begin_layout Plain Layout
1346 17:58:48.116: You can now run (pdf)latex on 'sweave.tex'
1349 \begin_layout Plain Layout
1361 \begin_layout Standard
1367 If any chunk causes an error in R, you will see the error message here
1371 \begin_layout Standard
1372 Another known issue is the Sweave code chunk may fail when we change the
1373 alignment of the chunk paragraph in LyX (using
1377 ), because LyX may add a macro like
1383 before the code chunk without adding a new line, which will lead to a code
1387 \begin_layout Standard
1391 \begin_layout Plain Layout
1398 \begin_layout Plain Layout
1402 centering{}<<xtable-demo,results=tex,echo=FALSE>>=
1405 \begin_layout Plain Layout
1417 \begin_layout Standard
1418 This is not a legitimate Sweave code chunk, since
1422 must start in a new line with nothing before it.
1423 Therefore we recommend you to double check the real source code via
1425 View\SpecialChar \menuseparator
1428 when changing the alignment of a chunk paragraph, and make sure
1432 appears in a new line.
1433 This explains why we manually added an empty line in the code chunk in
1435 \begin_inset CommandInset ref
1437 reference "tab:xtable-demo"
1444 \begin_layout Section
1448 \begin_layout Standard
1449 The homepage of Sweave is at
1450 \begin_inset Flex URL
1453 \begin_layout Plain Layout
1455 http://www.stat.uni-muenchen.de/~leisch/Sweave/
1461 The CRAN task view on
1462 \begin_inset Quotes eld
1465 Reproducible Research
1466 \begin_inset Quotes erd
1469 has a list of Sweave-related packages which can be potentially useful;
1471 \begin_inset Flex URL
1474 \begin_layout Plain Layout
1476 http://cran.r-project.org/web/views/ReproducibleResearch.html
1482 Questions about LyX and Sweave can be posted to the LyX mailing list (
1483 \begin_inset Flex URL
1486 \begin_layout Plain Layout
1488 http://www.lyx.org/MailingLists
1494 More LyX examples are provided at
1495 \begin_inset Flex URL
1498 \begin_layout Plain Layout
1500 https://github.com/yihui/lyx
1508 \begin_layout Section
1512 \begin_layout Subsection
1513 How to use Sweave with beamer?
1516 \begin_layout Standard
1517 You will end up with LaTeX errors if you use Sweave in normal beamer slides
1518 in LyX; the reason is the beamer frame that contains verbatim R code.
1519 The solution is to use a
1527 , or to pass the option
1531 to the frame title via
1533 Insert\SpecialChar \menuseparator
1539 \begin_layout Subsection
1540 Can I define my own R script to compile the Rnw document?
1543 \begin_layout Standard
1545 First you need to understand how the R script
1549 /scripts/lyxsweave.R
1551 works, which was introduced previously, and we recommend you to read the
1552 R source code as well (on how R takes the paths and uses
1556 to handle the Rnw document).
1557 Then you put your customized
1571 Help\SpecialChar \menuseparator
1575 Note LyX will check the
1579 before going to its own
1587 is found in the user directory, it will be used.
1588 It is not recommended to hack the script under the LyX library directory
1589 directly, since updating LyX will override you modified script (the user
1590 directory will not be affected).
1593 \begin_layout Standard
1594 Beside the support for the official Sweave in R, the
1598 package is also supported, which is an alternative tool to Sweave; the
1599 corresponding module is named