1 #LyX 2.3 created this file. For more info see http://www.lyx.org/
5 \save_transient_properties true
6 \origin /systemlyxdir/examples/
9 %% maxwidth is the original width if it's less than linewidth
10 %% otherwise use linewidth (to make sure the graphics do not exceed the margin)
12 \ifdim\Gin@nat@width>\linewidth
20 \use_default_options true
24 \maintain_unincluded_children false
26 \language_package auto
27 \inputencoding default
29 \font_roman "palatino" "default"
30 \font_sans "lmss" "default"
31 \font_typewriter "lmtt" "default"
32 \font_math "auto" "auto"
33 \font_default_family default
34 \use_non_tex_fonts false
37 \font_sf_scale 100 100
38 \font_tt_scale 100 100
40 \use_dash_ligatures false
42 \default_output_format default
44 \bibtex_command default
45 \index_command default
46 \paperfontsize default
51 \use_package amsmath 1
52 \use_package amssymb 1
55 \use_package mathdots 1
56 \use_package mathtools 0
58 \use_package stackrel 0
59 \use_package stmaryrd 0
60 \use_package undertilde 0
62 \cite_engine_type default
66 \paperorientation portrait
81 \paragraph_separation indent
82 \paragraph_indentation default
84 \math_numbering_side default
89 \paperpagestyle default
90 \tracking_changes false
99 \begin_layout Standard
100 \begin_inset Note Note
103 \begin_layout Plain Layout
104 \begin_inset Flex Sweave Options
107 \begin_layout Plain Layout
109 prefix=TRUE,prefix.string=sweave-prefix,keep.source=FALSE
122 \begin_layout Standard
126 \begin_layout Plain Layout
130 maxwidth was defined in the preamble; see document settings
133 \begin_layout Plain Layout
148 Using Sweave with \SpecialChar LyX
157 \begin_layout Plain Layout
158 Department of Statistics, Iowa State University.
160 \begin_inset CommandInset href
162 name "xie@yihui.name"
163 target "xie@yihui.name"
178 \begin_layout Plain Layout
191 \begin_layout Plain Layout
203 \begin_layout Standard
204 Sweave is a tool in the R language (
205 \begin_inset Flex URL
208 \begin_layout Plain Layout
210 http://www.r-project.org
215 ) for dynamic report generation using the ideas of literate programming.
216 R code can be mixed into a \SpecialChar LaTeX
217 document, and will be executed in R when the
218 document is compiled; the results are written into the \SpecialChar TeX
222 \begin_layout Standard
223 Since \SpecialChar LyX
224 2.0, Sweave can be used out of the box with any document class using
234 module to a \SpecialChar LyX
237 Document\SpecialChar menuseparator
238 Settings\SpecialChar menuseparator
242 In this manual, we demonstrate some common features of Sweave and explain
243 how the module works.
244 A PDF version of this manual can be found at
245 \begin_inset Flex URL
248 \begin_layout Plain Layout
250 https://github.com/downloads/yihui/lyx/sweave.pdf
258 \begin_layout Standard
259 Since \SpecialChar LyX
260 2.3, it is necessary to enable the use of
266 Preferences\SpecialChar menuseparator
267 File Handling\SpecialChar menuseparator
270 in order to compile with Sweave.
273 \begin_layout Section
277 \begin_layout Standard
282 module depends on the executable
286 , so it has to be in the
290 variable of the system.
291 It is usually not a problem for Linux and Mac OS users, but may be confusing
292 to Windows users; if you do not understand what is
296 under Windows, you may either use the R script
301 \begin_inset Flex URL
304 \begin_layout Plain Layout
306 https://github.com/yihui/lyx
311 to change it automatically (not recommended; you should learn
317 Tools\SpecialChar menuseparator
318 Preferences\SpecialChar menuseparator
319 Paths\SpecialChar menuseparator
322 to add the bin path of R (recommended), which is often like
334 and you can find it in R:
337 \begin_layout Standard
338 \begin_inset Flex Chunk
341 \begin_layout Plain Layout
343 \begin_inset Argument 1
346 \begin_layout Plain Layout
347 where-is-R-bin,eval=FALSE
355 \begin_layout Plain Layout
365 \begin_layout Standard
366 After you have done these changes, you need to reconfigure \SpecialChar LyX
369 Tools\SpecialChar menuseparator
385 module will be unavailable.
386 It is recommended to use the latest version of R, since Sweave is still
388 Another dependency is introduced by the \SpecialChar LaTeX
393 which is shipped with R under this path (it is not on CTAN):
396 \begin_layout Standard
397 \begin_inset Flex Chunk
400 \begin_layout Plain Layout
402 \begin_inset Argument 1
405 \begin_layout Plain Layout
406 sweave-sty,eval=FALSE
414 \begin_layout Plain Layout
416 file.path(R.home('share'), 'texmf', 'tex', 'latex')
424 \begin_layout Standard
426 users may add the texmf directory to the list of root directories in
428 through Mik\SpecialChar TeX
452 , it will directly copy from R, so the Sweave module works even if you do
453 not know where is this style file.
456 \begin_layout Section
460 \begin_layout Standard
461 Before we write an Sweave document, we can set some Sweave options; the
468 in Sweave and it can be inserted in a \SpecialChar LyX
471 Insert\SpecialChar menuseparator
472 Custom Insets\SpecialChar menuseparator
475 , or just use \SpecialChar TeX
478 Insert\SpecialChar menuseparator
483 For example, we can set a global option
487 in the beginning of a document to suppress all R code (by default, both
488 R code and its output will show up in the \SpecialChar LaTeX
493 \begin_layout Standard
494 To write R code in \SpecialChar LyX
495 , you can first insert
501 Insert\SpecialChar menuseparator
502 Custom Insets\SpecialChar menuseparator
505 , or you can simply open a \SpecialChar TeX
506 code environment and write Sweave code chunks
508 However, \SpecialChar LyX
509 provides a summary of all the
513 insets in the document in the
515 Navigate\SpecialChar menuseparator
520 View\SpecialChar menuseparator
526 \begin_layout Standard
527 Some R options can be useful to the Sweave output as well, e.g.
537 The former option can adjust the width of the output, and the latter can
538 avoid a common problem with quotes.
539 Users are encouraged to read the Sweave manual in R for more details.
542 \begin_layout Standard
543 \begin_inset Flex Chunk
546 \begin_layout Plain Layout
548 \begin_inset Argument 1
551 \begin_layout Plain Layout
552 setup, keep.source=TRUE
560 \begin_layout Plain Layout
562 ## the option 'digits' can set the (approximate) number of digits
565 \begin_layout Plain Layout
567 options(width = 70, useFancyQuotes = FALSE, digits = 4)
575 \begin_layout Standard
576 \begin_inset Flex Chunk
579 \begin_layout Plain Layout
581 \begin_inset Argument 1
584 \begin_layout Plain Layout
585 sweave-manual, eval=FALSE, keep.source=TRUE
593 \begin_layout Plain Layout
595 ## view the Sweave vignette (requires R >= 2.13.0)
598 \begin_layout Plain Layout
600 vignette("Sweave", package = "utils")
608 \begin_layout Standard
609 A simple example that will run in any S engine:
612 \begin_layout Standard
613 \begin_inset Flex Chunk
616 \begin_layout Plain Layout
618 \begin_inset Argument 1
621 \begin_layout Plain Layout
622 print-integers, keep.source=TRUE
630 \begin_layout Plain Layout
632 ## the integers from 1 to 10 are
635 \begin_layout Plain Layout
645 \begin_layout Standard
646 \begin_inset Flex Chunk
649 \begin_layout Plain Layout
651 \begin_inset Argument 1
654 \begin_layout Plain Layout
655 hide-results, results=hide
663 \begin_layout Plain Layout
665 ## intentionally hide the output by setting results=hide
668 \begin_layout Plain Layout
678 \begin_layout Standard
679 We can also emulate a simple calculator:
682 \begin_layout Standard
683 \begin_inset Flex Chunk
686 \begin_layout Plain Layout
688 \begin_inset Argument 1
691 \begin_layout Plain Layout
700 \begin_layout Plain Layout
705 \begin_layout Plain Layout
715 \begin_layout Standard
716 Now we look at some Gaussian data:
719 \begin_layout Standard
720 \begin_inset Flex Chunk
723 \begin_layout Plain Layout
725 \begin_inset Argument 1
728 \begin_layout Plain Layout
737 \begin_layout Plain Layout
739 set.seed(123) # for reproducibility
742 \begin_layout Plain Layout
747 \begin_layout Plain Layout
752 \begin_layout Plain Layout
762 \begin_layout Standard
763 Note that we can easily integrate some numbers into standard text; this
764 is done with the command
770 , and the corresponding \SpecialChar LyX
773 Insert\SpecialChar menuseparator
774 Custom Insets\SpecialChar menuseparator
777 , or alternatively just use \SpecialChar TeX
779 For example, the third element of the vector
784 \begin_inset Flex S/R expression
787 \begin_layout Plain Layout
800 \begin_inset Formula $p$
803 -value of the test is
804 \begin_inset Flex S/R expression
807 \begin_layout Plain Layout
809 format.pval(t1$p.value)
815 You can round these numbers using functions like
823 \begin_layout Standard
833 Now we look at a summary of the
854 \begin_layout Standard
855 \begin_inset Flex Chunk
858 \begin_layout Plain Layout
860 \begin_inset Argument 1
863 \begin_layout Plain Layout
872 \begin_layout Plain Layout
882 \begin_layout Standard
883 \begin_inset Float table
888 \begin_layout Plain Layout
889 \begin_inset Caption Standard
891 \begin_layout Plain Layout
892 Quantiles of the first four variables in the
897 \begin_inset CommandInset label
899 name "tab:xtable-demo"
909 \begin_inset Flex Chunk
912 \begin_layout Plain Layout
914 \begin_inset Argument 1
917 \begin_layout Plain Layout
918 xtable-demo,results=tex,echo=FALSE
926 \begin_layout Plain Layout
928 if (require('xtable')) {
931 \begin_layout Plain Layout
933 print(xtable(sapply(iris[,-5], quantile)), floating=FALSE)
936 \begin_layout Plain Layout
938 } else cat('the xtable package is not available! please install.packages("xtable"
952 \begin_layout Standard
953 Usually people do not like such
954 \begin_inset Quotes eld
958 \begin_inset Quotes erd
961 output, and we can polish these messy numbers with the
967 \begin_inset CommandInset ref
969 reference "tab:xtable-demo"
973 is an example demonstrating how to use the
977 package with Sweave; note the chunk option
981 makes sure that the R output is written out as raw \SpecialChar LaTeX
982 code instead of being
983 wrapped in a special environment (
990 \begin_layout Standard
992 \begin_inset CommandInset ref
994 reference "fig:iris-pairs"
999 \begin_inset CommandInset ref
1001 reference "fig:iris-boxplots"
1005 are two simple examples of producing graphics output with Sweave.
1008 \begin_layout Standard
1009 \begin_inset Float figure
1014 \begin_layout Plain Layout
1016 \begin_inset Note Note
1019 \begin_layout Plain Layout
1020 Both eps and pdf are set to true so that both latex and pdflatex work.
1021 In practice, you would probably just choose one.
1029 \begin_layout Plain Layout
1031 \begin_inset Flex Chunk
1034 \begin_layout Plain Layout
1036 \begin_inset Argument 1
1039 \begin_layout Plain Layout
1040 iris-pairs,fig=TRUE,width=4.5,height=4.5,eps=TRUE,pdf=TRUE
1048 \begin_layout Plain Layout
1050 pairs(iris, col = iris$Species)
1058 \begin_layout Plain Layout
1059 \begin_inset Caption Standard
1061 \begin_layout Plain Layout
1062 Scatter plot matrix of the
1067 \begin_inset CommandInset label
1069 name "fig:iris-pairs"
1086 \begin_layout Standard
1087 \begin_inset Float figure
1092 \begin_layout Plain Layout
1094 \begin_inset Flex Chunk
1097 \begin_layout Plain Layout
1099 \begin_inset Argument 1
1102 \begin_layout Plain Layout
1103 iris-boxplots,fig=TRUE,width=7,height=2,keep.source=F,eps=T,pdf=T
1111 \begin_layout Plain Layout
1113 par(mar=c(4,5,.1,.3), las=1)
1116 \begin_layout Plain Layout
1118 boxplot(Sepal.Length~Species,data=iris,horizontal=TRUE,xlab='Sepal.Length')
1126 \begin_layout Plain Layout
1127 \begin_inset Caption Standard
1129 \begin_layout Plain Layout
1130 Boxplots of sepal length grouped by species.
1131 \begin_inset CommandInset label
1133 name "fig:iris-boxplots"
1150 \begin_layout Standard
1151 We can also export all the R code in an Sweave document as a single R script
1154 File\SpecialChar menuseparator
1155 Export\SpecialChar menuseparator
1158 ), which is done via
1165 \begin_layout Section
1173 \begin_layout Standard
1178 module declares that a \SpecialChar LyX
1179 document contains literate programming components
1180 with R, so that \SpecialChar LyX
1181 will handle such documents according to the specific converter
1182 s (see the Customization manual).
1191 converter, which essentially consists of an R script
1199 directory of \SpecialChar LyX
1201 This script takes an
1205 document from \SpecialChar LyX
1206 and call Sweave to process it to a \SpecialChar TeX
1207 document, then \SpecialChar LyX
1209 care of the rest of work.
1212 \begin_layout Standard
1213 The converter from the
1217 format to \SpecialChar LaTeX
1218 is a call to R via the command line as:
1221 \begin_layout Standard
1225 \begin_layout Plain Layout
1232 \begin_layout Plain Layout
1234 Rscript --no-save --no-restore $$s/scripts/lyxsweave.R $$p$$i $$p$$o $$e
1238 \begin_layout Plain Layout
1250 \begin_layout Standard
1251 The \SpecialChar LyX
1256 can be found from the menu
1258 Help\SpecialChar menuseparator
1259 About \SpecialChar LyX
1263 All the rest of options passed to R are explained in the R script, and
1264 the \SpecialChar LyX
1265 Customization manual also has detailed explanations about
1282 General users do not need to know clearly what they mean, but here we need
1283 to explain a few issues in the R code:
1286 \begin_layout Enumerate
1287 the encoding string of the \SpecialChar LyX
1288 document is passed to R as an command line option;
1298 The encoding is used for R to read the
1305 \begin_layout Enumerate
1306 the R code chunks in the Sweave document are executed under the directory
1307 of the \SpecialChar LyX
1308 document (if you are not sure, put
1312 in a code chunk to see what is the current working directory).
1313 In this case, you can put data files under the same directory and use relative
1314 paths in R to guarantee reproducibility, i.e.
1315 we do not need to write hard-coded paths which may not exist in other systems.
1318 \begin_layout Enumerate
1319 if \SpecialChar LaTeX
1324 , this R script will copy it to the temporary directory automatically where
1325 the \SpecialChar LaTeX
1326 compilation takes place.
1329 \begin_layout Enumerate
1330 Sweave will use the filename of the Rnw file as the prefix string for the
1331 graphics output by default; one known issue (
1332 \begin_inset CommandInset href
1335 target "http://www.lyx.org/trac/ticket/7551"
1340 ) is that if the filename (without extension) contains dots, \SpecialChar LaTeX
1342 deal with such files in
1349 Therefore, we have set the default value of the prefix to be the filename
1350 with all the dots being replaced by
1351 \begin_inset Quotes eld
1355 \begin_inset Quotes erd
1359 We can also solve this problem in Sweave directly: set the Sweave option
1364 to be a character string without dots, and this option will override the
1368 \begin_layout Standard
1369 We have pre-specified an option
1373 for the Sweave package.
1374 This option stops Sweave from loading these two packages:
1377 \begin_layout Standard
1381 \begin_layout Plain Layout
1388 \begin_layout Plain Layout
1392 RequirePackage[T1]{fontenc}
1395 \begin_layout Plain Layout
1402 \begin_layout Plain Layout
1414 \begin_layout Standard
1416 can deal with the font encoding by default, so there is no need to ask
1417 Sweave to do this (furthermore, this may bring clashes of package options);
1418 besides, the users can load the
1422 package by themselves in the preamble if needed.
1425 \begin_layout Section
1429 \begin_layout Standard
1430 Since \SpecialChar LyX
1431 2.0, we can see the detailed information during compilation via
1433 View\SpecialChar menuseparator
1437 This is extremely helpful for trouble shooting – the process of R will
1438 be shown in the message panel, and we will be able to know which chunk
1439 goes wrong in cases of errors.
1440 For example, when you compile this document, you can see messages like
1444 \begin_layout Standard
1448 \begin_layout Plain Layout
1455 \begin_layout Plain Layout
1457 17:58:47.868: Processing code chunks with options ...
1460 \begin_layout Plain Layout
1462 17:58:47.885: 1 : echo keep.source term verbatim (label=setup)
1465 \begin_layout Plain Layout
1467 17:58:47.889: 2 : echo keep.source (label=sweave-manual)
1470 \begin_layout Plain Layout
1472 17:58:47.908: 3 : echo keep.source term verbatim (label=print-integers)
1475 \begin_layout Plain Layout
1480 \begin_layout Plain Layout
1482 17:58:47.941: Loading required package: xtable
1485 \begin_layout Plain Layout
1487 17:58:47.976: 9 : echo term verbatim pdf (label=iris-pairs)
1490 \begin_layout Plain Layout
1495 \begin_layout Plain Layout
1497 17:58:48.116: You can now run (pdf)latex on 'sweave.tex'
1500 \begin_layout Plain Layout
1512 \begin_layout Standard
1518 If any chunk causes an error in R, you will see the error message here
1522 \begin_layout Standard
1523 Another issue with the \SpecialChar TeX
1524 code environment is the Sweave code chunk may fail
1525 when we change the alignment of the chunk paragraph in \SpecialChar LyX
1530 ), because \SpecialChar LyX
1531 may add a macro like
1537 before the code chunk without adding a new line, which will lead to a code
1541 \begin_layout Standard
1545 \begin_layout Plain Layout
1552 \begin_layout Plain Layout
1556 centering{}<<xtable-demo,results=tex,echo=FALSE>>=
1559 \begin_layout Plain Layout
1571 \begin_layout Standard
1572 This is not a legitimate Sweave code chunk, since
1576 must start in a new line with nothing before it.
1577 This does not happen when using the Chunk inset instead of the \SpecialChar TeX
1583 \begin_layout Section
1587 \begin_layout Standard
1588 The homepage of Sweave is at
1589 \begin_inset Flex URL
1592 \begin_layout Plain Layout
1594 http://www.stat.uni-muenchen.de/~leisch/Sweave/
1600 The CRAN task view on
1601 \begin_inset Quotes eld
1604 Reproducible Research
1605 \begin_inset Quotes erd
1608 has a list of Sweave-related packages which can be potentially useful;
1610 \begin_inset Flex URL
1613 \begin_layout Plain Layout
1615 http://cran.r-project.org/web/views/ReproducibleResearch.html
1621 Questions about \SpecialChar LyX
1622 and Sweave can be posted to the \SpecialChar LyX
1624 \begin_inset Flex URL
1627 \begin_layout Plain Layout
1629 http://www.lyx.org/MailingLists
1635 More \SpecialChar LyX
1636 examples are provided at
1637 \begin_inset Flex URL
1640 \begin_layout Plain Layout
1642 https://github.com/yihui/lyx
1650 \begin_layout Section
1654 \begin_layout Subsection
1655 How to use Sweave with beamer?
1658 \begin_layout Standard
1659 You will end up with \SpecialChar LaTeX
1660 errors if you use Sweave in normal beamer slides in
1662 ; the reason is the beamer frame that contains verbatim R code.
1663 The solution is to use a
1671 , or to pass the option
1675 to the frame title via
1677 Insert\SpecialChar menuseparator
1683 \begin_layout Subsection
1684 Can I define my own R script to compile the Rnw document?
1687 \begin_layout Standard
1689 First you need to understand how the R script
1693 /scripts/lyxsweave.R
1695 works, which was introduced previously, and we recommend you to read the
1696 R source code as well (on how R takes the paths and uses
1700 to handle the Rnw document).
1701 Then you put your customized
1715 Help\SpecialChar menuseparator
1716 About \SpecialChar LyX
1720 Note \SpecialChar LyX
1725 before going to its own
1733 is found in the user directory, it will be used.
1734 It is not recommended to hack the script under the \SpecialChar LyX
1735 library directory directly,
1736 since updating \SpecialChar LyX
1737 will override you modified script (the user directory will
1741 \begin_layout Standard
1742 Beside the support for the official Sweave in R, the
1746 package is also supported, which is an alternative tool to Sweave; the
1747 corresponding module is named