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
51 \use_package mathdots 1
52 \use_package mathtools 0
54 \use_package stackrel 0
55 \use_package stmaryrd 0
56 \use_package undertilde 0
58 \cite_engine_type default
62 \paperorientation portrait
76 \paragraph_separation indent
77 \paragraph_indentation default
78 \quotes_language english
81 \paperpagestyle default
82 \tracking_changes false
91 \begin_layout Standard
95 \begin_layout Plain Layout
99 SweaveOpts{prefix=TRUE,prefix.string=sweave-prefix,keep.source=FALSE}
107 \begin_layout Standard
111 \begin_layout Plain Layout
115 maxwidth was defined in the preamble; see document settings
118 \begin_layout Plain Layout
133 Using Sweave with LyX
141 \begin_layout Plain Layout
142 Department of Statistics, Iowa State University.
144 \begin_inset CommandInset href
146 name "xie@yihui.name"
147 target "xie@yihui.name"
161 \begin_layout Plain Layout
174 \begin_layout Plain Layout
186 \begin_layout Standard
187 Sweave is a tool in the R language (
188 \begin_inset Flex URL
191 \begin_layout Plain Layout
193 http://www.r-project.org
198 ) for dynamic report generation using the ideas of literate programming.
199 R code can be mixed into a LaTeX document, and will be executed in R when
200 the document is compiled; the results are written into the TeX output.
203 \begin_layout Standard
204 Since LyX 2.0, Sweave can be used out of the box with any document class
214 module to a LyX document from
216 Document\SpecialChar \menuseparator
217 Settings\SpecialChar \menuseparator
221 In this manual, we demonstrate some common features of Sweave and explain
222 how the module works.
223 A PDF version of this manual can be found at
224 \begin_inset Flex URL
227 \begin_layout Plain Layout
229 https://github.com/downloads/yihui/lyx/sweave.pdf
237 \begin_layout Section
241 \begin_layout Standard
246 module depends on the executable
250 , so it has to be in the
254 variable of the system.
255 It is usually not a problem for Linux and Mac OS users, but may be confusing
256 to Windows users; if you do not understand what is
260 under Windows, you may either use the R script
265 \begin_inset Flex URL
268 \begin_layout Plain Layout
270 https://github.com/yihui/lyx
275 to change it automatically (not recommended; you should learn
281 Tools\SpecialChar \menuseparator
282 Preferences\SpecialChar \menuseparator
283 Paths\SpecialChar \menuseparator
286 to add the bin path of R (recommended), which is often like
298 and you can find it in R:
301 \begin_layout Standard
305 \begin_layout Plain Layout
307 <<where-is-R-bin,eval=FALSE>>=
310 \begin_layout Plain Layout
315 \begin_layout Plain Layout
325 \begin_layout Standard
326 After you have done these changes, you need to reconfigure LyX by
328 Tools\SpecialChar \menuseparator
344 module will be unavailable.
345 It is recommended to use the latest version of R, since Sweave is still
347 Another dependency is introduced by the LaTeX style file
351 which is shipped with R under this path (it is not on CTAN):
354 \begin_layout Standard
358 \begin_layout Plain Layout
360 <<sweave-sty,eval=FALSE>>=
363 \begin_layout Plain Layout
365 file.path(R.home('share'), 'texmf', 'tex', 'latex')
368 \begin_layout Plain Layout
378 \begin_layout Standard
379 MikTeX users may add the texmf directory to the list of root directories
380 in MikTeX through MikTeX settings.
402 , it will directly copy from R, so the Sweave module works even if you do
403 not know where is this style file.
406 \begin_layout Section
410 \begin_layout Standard
411 Before we write an Sweave document, we can set some Sweave options; the
418 in Sweave and it can be inserted in a LyX document by
420 Insert\SpecialChar \menuseparator
421 Custom Insets\SpecialChar \menuseparator
424 , or just use TeX code to write it (
426 Insert\SpecialChar \menuseparator
430 For example, we can set a global option
434 in the beginning of a document to suppress all R code (by default, both
435 R code and its output will show up in the LaTeX document).
439 \begin_layout Standard
440 To write R code in LyX, you can first switch to the
444 environment in the layout styles list (droplist in the top-left corner
445 in the toolbar), or you can simply open a TeX code environment and write
446 Sweave code chunks in it.
447 The latter approach is recommended since it is more stable.
450 \begin_layout Standard
451 Some R options can be useful to the Sweave output as well, e.g.
461 The former option can adjust the width of the output, and the latter can
462 avoid a common problem with quotes.
463 Users are encouraged to read the Sweave manual in R for more details.
466 \begin_layout Standard
470 \begin_layout Plain Layout
472 <<setup, keep.source=TRUE>>=
475 \begin_layout Plain Layout
477 ## the option 'digits' can set the (approximate) number of digits
480 \begin_layout Plain Layout
482 options(width = 70, useFancyQuotes = FALSE, digits = 4)
485 \begin_layout Plain Layout
490 \begin_layout Plain Layout
492 <<sweave-manual, eval=FALSE, keep.source=TRUE>>=
495 \begin_layout Plain Layout
497 ## view the Sweave vignette (requires R >= 2.13.0)
500 \begin_layout Plain Layout
502 vignette("Sweave", package = "utils")
505 \begin_layout Plain Layout
515 \begin_layout Standard
516 A simple example that will run in any S engine:
519 \begin_layout Standard
523 \begin_layout Plain Layout
525 <<print-integers, keep.source=TRUE>>=
528 \begin_layout Plain Layout
530 ## the integers from 1 to 10 are
533 \begin_layout Plain Layout
538 \begin_layout Plain Layout
543 \begin_layout Plain Layout
545 <<hide-results, results=hide>>=
548 \begin_layout Plain Layout
550 ## intentionally hide the output by setting results=hide
553 \begin_layout Plain Layout
558 \begin_layout Plain Layout
568 \begin_layout Standard
569 We can also emulate a simple calculator:
572 \begin_layout Standard
576 \begin_layout Plain Layout
581 \begin_layout Plain Layout
586 \begin_layout Plain Layout
591 \begin_layout Plain Layout
601 \begin_layout Standard
602 Now we look at some Gaussian data:
605 \begin_layout Standard
609 \begin_layout Plain Layout
614 \begin_layout Plain Layout
616 set.seed(123) # for reproducibility
619 \begin_layout Plain Layout
624 \begin_layout Plain Layout
629 \begin_layout Plain Layout
634 \begin_layout Plain Layout
644 \begin_layout Standard
645 Note that we can easily integrate some numbers into standard text; this
646 is done with the command
652 , and the corresponding LyX menu is
654 Insert\SpecialChar \menuseparator
655 Custom Insets\SpecialChar \menuseparator
658 , or alternatively just use TeX code.
659 For example, the third element of the vector
664 \begin_inset Flex S/R expression
667 \begin_layout Plain Layout
680 \begin_inset Formula $p$
683 -value of the test is
684 \begin_inset Flex S/R expression
687 \begin_layout Plain Layout
689 format.pval(t1$p.value)
695 You can round these numbers using functions like
703 \begin_layout Standard
713 Now we look at a summary of the
734 \begin_layout Standard
738 \begin_layout Plain Layout
743 \begin_layout Plain Layout
748 \begin_layout Plain Layout
758 \begin_layout Standard
759 \begin_inset Float table
764 \begin_layout Plain Layout
765 \begin_inset Caption Standard
767 \begin_layout Plain Layout
768 Quantiles of the first four variables in the
773 \begin_inset CommandInset label
775 name "tab:xtable-demo"
787 \begin_layout Plain Layout
792 \begin_layout Plain Layout
796 \begin_layout Plain Layout
798 <<xtable-demo,results=tex,echo=FALSE>>=
801 \begin_layout Plain Layout
803 if (require('xtable')) {
806 \begin_layout Plain Layout
808 print(xtable(sapply(iris[,-5], quantile)), floating=FALSE)
811 \begin_layout Plain Layout
813 } else cat('the xtable package is not available! please install.packages("xtable"
817 \begin_layout Plain Layout
832 \begin_layout Standard
833 Usually people do not like such
834 \begin_inset Quotes eld
838 \begin_inset Quotes erd
841 output, and we can polish these messy numbers with the
847 \begin_inset CommandInset ref
849 reference "tab:xtable-demo"
853 is an example demonstrating how to use the
857 package with Sweave; note the chunk option
861 makes sure that the R output is written out as raw LaTeX code instead of
862 being wrapped in a special environment (
869 \begin_layout Standard
871 \begin_inset CommandInset ref
873 reference "fig:iris-pairs"
878 \begin_inset CommandInset ref
880 reference "fig:iris-boxplots"
884 are two simple examples of producing graphics output with Sweave.
887 \begin_layout Standard
888 \begin_inset Float figure
893 \begin_layout Plain Layout
895 \begin_inset Note Note
898 \begin_layout Plain Layout
899 Both eps and pdf are set to true so that both latex and pdflatex work.
900 In practice, you would probably just choose one.
909 \begin_layout Plain Layout
911 <<iris-pairs,fig=TRUE,width=4.5,height=4.5,eps=TRUE,pdf=TRUE>>=
914 \begin_layout Plain Layout
916 pairs(iris, col = iris$Species)
919 \begin_layout Plain Layout
929 \begin_layout Plain Layout
930 \begin_inset Caption Standard
932 \begin_layout Plain Layout
933 Scatter plot matrix of the
938 \begin_inset CommandInset label
940 name "fig:iris-pairs"
957 \begin_layout Standard
958 \begin_inset Float figure
963 \begin_layout Plain Layout
968 \begin_layout Plain Layout
970 <<iris-boxplots,fig=TRUE,width=7,height=2,keep.source=F,eps=T,pdf=T>>=
973 \begin_layout Plain Layout
975 par(mar=c(4,5,.1,.3), las=1)
978 \begin_layout Plain Layout
980 boxplot(Sepal.Length~Species,data=iris,horizontal=TRUE,xlab='Sepal.Length')
983 \begin_layout Plain Layout
993 \begin_layout Plain Layout
994 \begin_inset Caption Standard
996 \begin_layout Plain Layout
997 Boxplots of sepal length grouped by species.
998 \begin_inset CommandInset label
1000 name "fig:iris-boxplots"
1017 \begin_layout Standard
1018 We can also export all the R code in an Sweave document as a single R script
1021 File\SpecialChar \menuseparator
1022 Export\SpecialChar \menuseparator
1025 ), which is done via
1032 \begin_layout Section
1040 \begin_layout Standard
1045 module declares that a LyX document contains literate programming components
1046 with R, so that LyX will handle such documents according to the specific
1047 converters (see the Customization manual).
1056 converter, which essentially consists of an R script
1065 This script takes an
1069 document from LyX and call Sweave to process it to a TeX document, then
1070 LyX takes care of the rest of work.
1073 \begin_layout Standard
1074 The converter from the
1078 format to LaTeX is a call to R via the command line as:
1081 \begin_layout Standard
1085 \begin_layout Plain Layout
1092 \begin_layout Plain Layout
1094 Rscript --no-save --no-restore $$s/scripts/lyxsweave.R $$p$$i $$p$$o $$e
1098 \begin_layout Plain Layout
1110 \begin_layout Standard
1111 The LyX library directory
1115 can be found from the menu
1117 Help\SpecialChar \menuseparator
1121 All the rest of options passed to R are explained in the R script, and
1122 the LyX Customization manual also has detailed explanations about
1139 General users do not need to know clearly what they mean, but here we need
1140 to explain a few issues in the R code:
1143 \begin_layout Enumerate
1144 the encoding string of the LyX document is passed to R as an command line
1145 option; possible values are
1154 The encoding is used for R to read the
1161 \begin_layout Enumerate
1162 the R code chunks in the Sweave document are executed under the directory
1163 of the LyX document (if you are not sure, put
1167 in a code chunk to see what is the current working directory).
1168 In this case, you can put data files under the same directory and use relative
1169 paths in R to guarantee reproducibility, i.e.
1170 we do not need to write hard-coded paths which may not exist in other systems.
1173 \begin_layout Enumerate
1174 if LaTeX cannot find
1178 , this R script will copy it to the temporary directory automatically where
1179 the LaTeX compilation takes place.
1182 \begin_layout Enumerate
1183 Sweave will use the filename of the Rnw file as the prefix string for the
1184 graphics output by default; one known issue (
1185 \begin_inset CommandInset href
1188 target "http://www.lyx.org/trac/ticket/7551"
1192 ) is that if the filename (without extension) contains dots, LaTeX can fail
1193 to deal with such files in
1200 Therefore, we have set the default value of the prefix to be the filename
1201 with all the dots being replaced by
1202 \begin_inset Quotes eld
1206 \begin_inset Quotes erd
1210 We can also solve this problem in Sweave directly: set the Sweave option
1215 to be a character string without dots, and this option will override the
1219 \begin_layout Standard
1220 We have pre-specified an option
1224 for the Sweave package.
1225 This option stops Sweave from loading these two packages:
1228 \begin_layout Standard
1232 \begin_layout Plain Layout
1239 \begin_layout Plain Layout
1243 RequirePackage[T1]{fontenc}
1246 \begin_layout Plain Layout
1253 \begin_layout Plain Layout
1265 \begin_layout Standard
1266 LyX can deal with the font encoding by default, so there is no need to ask
1267 Sweave to do this (furthermore, this may bring clashes of package options);
1268 besides, the users can load the
1272 package by themselves in the preamble if needed.
1275 \begin_layout Section
1279 \begin_layout Standard
1280 Since LyX 2.0, we can see the detailed information during compilation via
1283 View\SpecialChar \menuseparator
1287 This is extremely helpful for trouble shooting -- the process of R will
1288 be shown in the message panel, and we will be able to know which chunk
1289 goes wrong in cases of errors.
1290 For example, when you compile this document, you can see messages like
1294 \begin_layout Standard
1298 \begin_layout Plain Layout
1305 \begin_layout Plain Layout
1307 17:58:47.868: Processing code chunks with options ...
1310 \begin_layout Plain Layout
1312 17:58:47.885: 1 : echo keep.source term verbatim (label=setup)
1315 \begin_layout Plain Layout
1317 17:58:47.889: 2 : echo keep.source (label=sweave-manual)
1320 \begin_layout Plain Layout
1322 17:58:47.908: 3 : echo keep.source term verbatim (label=print-integers)
1325 \begin_layout Plain Layout
1330 \begin_layout Plain Layout
1332 17:58:47.941: Loading required package: xtable
1335 \begin_layout Plain Layout
1337 17:58:47.976: 9 : echo term verbatim pdf (label=iris-pairs)
1340 \begin_layout Plain Layout
1345 \begin_layout Plain Layout
1347 17:58:48.116: You can now run (pdf)latex on 'sweave.tex'
1350 \begin_layout Plain Layout
1362 \begin_layout Standard
1368 If any chunk causes an error in R, you will see the error message here
1372 \begin_layout Standard
1373 Another known issue is the Sweave code chunk may fail when we change the
1374 alignment of the chunk paragraph in LyX (using
1378 ), because LyX may add a macro like
1384 before the code chunk without adding a new line, which will lead to a code
1388 \begin_layout Standard
1392 \begin_layout Plain Layout
1399 \begin_layout Plain Layout
1403 centering{}<<xtable-demo,results=tex,echo=FALSE>>=
1406 \begin_layout Plain Layout
1418 \begin_layout Standard
1419 This is not a legitimate Sweave code chunk, since
1423 must start in a new line with nothing before it.
1424 Therefore we recommend you to double check the real source code via
1426 View\SpecialChar \menuseparator
1429 when changing the alignment of a chunk paragraph, and make sure
1433 appears in a new line.
1434 This explains why we manually added an empty line in the code chunk in
1436 \begin_inset CommandInset ref
1438 reference "tab:xtable-demo"
1445 \begin_layout Section
1449 \begin_layout Standard
1450 The homepage of Sweave is at
1451 \begin_inset Flex URL
1454 \begin_layout Plain Layout
1456 http://www.stat.uni-muenchen.de/~leisch/Sweave/
1462 The CRAN task view on
1463 \begin_inset Quotes eld
1466 Reproducible Research
1467 \begin_inset Quotes erd
1470 has a list of Sweave-related packages which can be potentially useful;
1472 \begin_inset Flex URL
1475 \begin_layout Plain Layout
1477 http://cran.r-project.org/web/views/ReproducibleResearch.html
1483 Questions about LyX and Sweave can be posted to the LyX mailing list (
1484 \begin_inset Flex URL
1487 \begin_layout Plain Layout
1489 http://www.lyx.org/MailingLists
1495 More LyX examples are provided at
1496 \begin_inset Flex URL
1499 \begin_layout Plain Layout
1501 https://github.com/yihui/lyx
1509 \begin_layout Section
1513 \begin_layout Subsection
1514 How to use Sweave with beamer?
1517 \begin_layout Standard
1518 You will end up with LaTeX errors if you use Sweave in normal beamer slides
1519 in LyX; the reason is the beamer frame that contains verbatim R code.
1520 The solution is to use a
1528 , or to pass the option
1532 to the frame title via
1534 Insert\SpecialChar \menuseparator
1540 \begin_layout Subsection
1541 Can I define my own R script to compile the Rnw document?
1544 \begin_layout Standard
1546 First you need to understand how the R script
1550 /scripts/lyxsweave.R
1552 works, which was introduced previously, and we recommend you to read the
1553 R source code as well (on how R takes the paths and uses
1557 to handle the Rnw document).
1558 Then you put your customized
1572 Help\SpecialChar \menuseparator
1576 Note LyX will check the
1580 before going to its own
1588 is found in the user directory, it will be used.
1589 It is not recommended to hack the script under the LyX library directory
1590 directly, since updating LyX will override you modified script (the user
1591 directory will not be affected).
1594 \begin_layout Standard
1595 Beside the support for the official Sweave in R, the
1599 package is also supported, which is an alternative tool to Sweave; the
1600 corresponding module is named