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 1
58 \use_package stackrel 1
59 \use_package stmaryrd 1
60 \use_package undertilde 1
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
348 where-is-R-bin,eval=FALSE
356 \begin_layout Plain Layout
366 \begin_layout Standard
367 After you have done these changes, you need to reconfigure \SpecialChar LyX
370 Tools\SpecialChar menuseparator
386 module will be unavailable.
387 It is recommended to use the latest version of R, since Sweave is still
389 Another dependency is introduced by the \SpecialChar LaTeX
394 which is shipped with R under this path (it is not on CTAN):
397 \begin_layout Standard
398 \begin_inset Flex Chunk
401 \begin_layout Plain Layout
403 \begin_inset Argument 1
406 \begin_layout Plain Layout
408 sweave-sty,eval=FALSE
416 \begin_layout Plain Layout
418 file.path(R.home('share'), 'texmf', 'tex', 'latex')
426 \begin_layout Standard
428 users may add the texmf directory to the list of root directories in
430 through Mik\SpecialChar TeX
454 , it will directly copy from R, so the Sweave module works even if you do
455 not know where is this style file.
458 \begin_layout Section
462 \begin_layout Standard
463 Before we write an Sweave document, we can set some Sweave options; the
470 in Sweave and it can be inserted in a \SpecialChar LyX
473 Insert\SpecialChar menuseparator
474 Custom Insets\SpecialChar menuseparator
477 , or just use \SpecialChar TeX
480 Insert\SpecialChar menuseparator
485 For example, we can set a global option
489 in the beginning of a document to suppress all R code (by default, both
490 R code and its output will show up in the \SpecialChar LaTeX
495 \begin_layout Standard
496 To write R code in \SpecialChar LyX
497 , you can first insert
503 Insert\SpecialChar menuseparator
504 Custom Insets\SpecialChar menuseparator
507 , or you can simply open a \SpecialChar TeX
508 code environment and write Sweave code chunks
510 However, \SpecialChar LyX
511 provides a summary of all the
515 insets in the document in the
517 Navigate\SpecialChar menuseparator
522 View\SpecialChar menuseparator
528 \begin_layout Standard
529 Some R options can be useful to the Sweave output as well, e.g.
539 The former option can adjust the width of the output, and the latter can
540 avoid a common problem with quotes.
541 Users are encouraged to read the Sweave manual in R for more details.
544 \begin_layout Standard
545 \begin_inset Flex Chunk
548 \begin_layout Plain Layout
550 \begin_inset Argument 1
553 \begin_layout Plain Layout
555 setup, keep.source=TRUE
563 \begin_layout Plain Layout
565 ## the option 'digits' can set the (approximate) number of digits
568 \begin_layout Plain Layout
570 options(width = 70, useFancyQuotes = FALSE, digits = 4)
578 \begin_layout Standard
579 \begin_inset Flex Chunk
582 \begin_layout Plain Layout
584 \begin_inset Argument 1
587 \begin_layout Plain Layout
589 sweave-manual, eval=FALSE, keep.source=TRUE
597 \begin_layout Plain Layout
599 ## view the Sweave vignette (requires R >= 2.13.0)
602 \begin_layout Plain Layout
604 vignette("Sweave", package = "utils")
612 \begin_layout Standard
613 A simple example that will run in any S engine:
616 \begin_layout Standard
617 \begin_inset Flex Chunk
620 \begin_layout Plain Layout
622 \begin_inset Argument 1
625 \begin_layout Plain Layout
627 print-integers, keep.source=TRUE
635 \begin_layout Plain Layout
637 ## the integers from 1 to 10 are
640 \begin_layout Plain Layout
650 \begin_layout Standard
651 \begin_inset Flex Chunk
654 \begin_layout Plain Layout
656 \begin_inset Argument 1
659 \begin_layout Plain Layout
661 hide-results, results=hide
669 \begin_layout Plain Layout
671 ## intentionally hide the output by setting results=hide
674 \begin_layout Plain Layout
684 \begin_layout Standard
685 We can also emulate a simple calculator:
688 \begin_layout Standard
689 \begin_inset Flex Chunk
692 \begin_layout Plain Layout
694 \begin_inset Argument 1
697 \begin_layout Plain Layout
707 \begin_layout Plain Layout
712 \begin_layout Plain Layout
722 \begin_layout Standard
723 Now we look at some Gaussian data:
726 \begin_layout Standard
727 \begin_inset Flex Chunk
730 \begin_layout Plain Layout
732 \begin_inset Argument 1
735 \begin_layout Plain Layout
745 \begin_layout Plain Layout
747 set.seed(123) # for reproducibility
750 \begin_layout Plain Layout
755 \begin_layout Plain Layout
760 \begin_layout Plain Layout
770 \begin_layout Standard
771 Note that we can easily integrate some numbers into standard text; this
772 is done with the command
778 , and the corresponding \SpecialChar LyX
781 Insert\SpecialChar menuseparator
782 Custom Insets\SpecialChar menuseparator
785 , or alternatively just use \SpecialChar TeX
787 For example, the third element of the vector
792 \begin_inset Flex S/R expression
795 \begin_layout Plain Layout
808 \begin_inset Formula $p$
811 -value of the test is
812 \begin_inset Flex S/R expression
815 \begin_layout Plain Layout
817 format.pval(t1$p.value)
823 You can round these numbers using functions like
831 \begin_layout Standard
841 Now we look at a summary of the
862 \begin_layout Standard
863 \begin_inset Flex Chunk
866 \begin_layout Plain Layout
868 \begin_inset Argument 1
871 \begin_layout Plain Layout
881 \begin_layout Plain Layout
891 \begin_layout Standard
892 \begin_inset Float table
897 \begin_layout Plain Layout
898 \begin_inset Caption Standard
900 \begin_layout Plain Layout
901 Quantiles of the first four variables in the
906 \begin_inset CommandInset label
908 name "tab:xtable-demo"
918 \begin_inset Flex Chunk
921 \begin_layout Plain Layout
923 \begin_inset Argument 1
926 \begin_layout Plain Layout
928 xtable-demo,results=tex,echo=FALSE
936 \begin_layout Plain Layout
938 if (require('xtable')) {
941 \begin_layout Plain Layout
943 print(xtable(sapply(iris[,-5], quantile)), floating=FALSE)
946 \begin_layout Plain Layout
948 } else cat('the xtable package is not available! please install.packages("xtable"
962 \begin_layout Standard
963 Usually people do not like such
964 \begin_inset Quotes eld
968 \begin_inset Quotes erd
971 output, and we can polish these messy numbers with the
977 \begin_inset CommandInset ref
979 reference "tab:xtable-demo"
983 is an example demonstrating how to use the
987 package with Sweave; note the chunk option
991 makes sure that the R output is written out as raw \SpecialChar LaTeX
992 code instead of being
993 wrapped in a special environment (
1000 \begin_layout Standard
1002 \begin_inset CommandInset ref
1004 reference "fig:iris-pairs"
1009 \begin_inset CommandInset ref
1011 reference "fig:iris-boxplots"
1015 are two simple examples of producing graphics output with Sweave.
1018 \begin_layout Standard
1019 \begin_inset Float figure
1024 \begin_layout Plain Layout
1026 \begin_inset Note Note
1029 \begin_layout Plain Layout
1030 Both eps and pdf are set to true so that both latex and pdflatex work.
1031 In practice, you would probably just choose one.
1039 \begin_layout Plain Layout
1041 \begin_inset Flex Chunk
1044 \begin_layout Plain Layout
1046 \begin_inset Argument 1
1049 \begin_layout Plain Layout
1051 iris-pairs,fig=TRUE,width=4.5,height=4.5,eps=TRUE,pdf=TRUE
1059 \begin_layout Plain Layout
1061 pairs(iris, col = iris$Species)
1069 \begin_layout Plain Layout
1070 \begin_inset Caption Standard
1072 \begin_layout Plain Layout
1073 Scatter plot matrix of the
1078 \begin_inset CommandInset label
1080 name "fig:iris-pairs"
1097 \begin_layout Standard
1098 \begin_inset Float figure
1103 \begin_layout Plain Layout
1105 \begin_inset Flex Chunk
1108 \begin_layout Plain Layout
1110 \begin_inset Argument 1
1113 \begin_layout Plain Layout
1115 iris-boxplots,fig=TRUE,width=7,height=2,keep.source=F,eps=T,pdf=T
1123 \begin_layout Plain Layout
1125 par(mar=c(4,5,.1,.3), las=1)
1128 \begin_layout Plain Layout
1130 boxplot(Sepal.Length~Species,data=iris,horizontal=TRUE,xlab='Sepal.Length')
1138 \begin_layout Plain Layout
1139 \begin_inset Caption Standard
1141 \begin_layout Plain Layout
1142 Boxplots of sepal length grouped by species.
1143 \begin_inset CommandInset label
1145 name "fig:iris-boxplots"
1162 \begin_layout Standard
1163 We can also export all the R code in an Sweave document as a single R script
1166 File\SpecialChar menuseparator
1167 Export\SpecialChar menuseparator
1170 ), which is done via
1177 \begin_layout Section
1185 \begin_layout Standard
1190 module declares that a \SpecialChar LyX
1191 document contains literate programming components
1192 with R, so that \SpecialChar LyX
1193 will handle such documents according to the specific converter
1194 s (see the Customization manual).
1203 converter, which essentially consists of an R script
1211 directory of \SpecialChar LyX
1213 This script takes an
1217 document from \SpecialChar LyX
1218 and call Sweave to process it to a \SpecialChar TeX
1219 document, then \SpecialChar LyX
1221 care of the rest of work.
1224 \begin_layout Standard
1225 The converter from the
1229 format to \SpecialChar LaTeX
1230 is a call to R via the command line as:
1233 \begin_layout Standard
1237 \begin_layout Plain Layout
1244 \begin_layout Plain Layout
1246 Rscript --no-save --no-restore $$s/scripts/lyxsweave.R $$p$$i $$p$$o $$e
1250 \begin_layout Plain Layout
1262 \begin_layout Standard
1263 The \SpecialChar LyX
1268 can be found from the menu
1270 Help\SpecialChar menuseparator
1271 About \SpecialChar LyX
1275 All the rest of options passed to R are explained in the R script, and
1276 the \SpecialChar LyX
1277 Customization manual also has detailed explanations about
1294 General users do not need to know clearly what they mean, but here we need
1295 to explain a few issues in the R code:
1298 \begin_layout Enumerate
1299 the encoding string of the \SpecialChar LyX
1300 document is passed to R as an command line option;
1310 The encoding is used for R to read the
1317 \begin_layout Enumerate
1318 the R code chunks in the Sweave document are executed under the directory
1319 of the \SpecialChar LyX
1320 document (if you are not sure, put
1324 in a code chunk to see what is the current working directory).
1325 In this case, you can put data files under the same directory and use relative
1326 paths in R to guarantee reproducibility, i.e.
1327 we do not need to write hard-coded paths which may not exist in other systems.
1330 \begin_layout Enumerate
1331 if \SpecialChar LaTeX
1336 , this R script will copy it to the temporary directory automatically where
1337 the \SpecialChar LaTeX
1338 compilation takes place.
1341 \begin_layout Enumerate
1342 Sweave will use the filename of the Rnw file as the prefix string for the
1343 graphics output by default; one known issue (
1344 \begin_inset CommandInset href
1347 target "http://www.lyx.org/trac/ticket/7551"
1352 ) is that if the filename (without extension) contains dots, \SpecialChar LaTeX
1354 deal with such files in
1361 Therefore, we have set the default value of the prefix to be the filename
1362 with all the dots being replaced by
1363 \begin_inset Quotes eld
1367 \begin_inset Quotes erd
1371 We can also solve this problem in Sweave directly: set the Sweave option
1376 to be a character string without dots, and this option will override the
1380 \begin_layout Standard
1381 We have pre-specified an option
1385 for the Sweave package.
1386 This option stops Sweave from loading these two packages:
1389 \begin_layout Standard
1393 \begin_layout Plain Layout
1400 \begin_layout Plain Layout
1404 RequirePackage[T1]{fontenc}
1407 \begin_layout Plain Layout
1414 \begin_layout Plain Layout
1426 \begin_layout Standard
1428 can deal with the font encoding by default, so there is no need to ask
1429 Sweave to do this (furthermore, this may bring clashes of package options);
1430 besides, the users can load the
1434 package by themselves in the preamble if needed.
1437 \begin_layout Section
1441 \begin_layout Standard
1442 Since \SpecialChar LyX
1443 2.0, we can see the detailed information during compilation via
1445 View\SpecialChar menuseparator
1449 This is extremely helpful for trouble shooting – the process of R will
1450 be shown in the message panel, and we will be able to know which chunk
1451 goes wrong in cases of errors.
1452 For example, when you compile this document, you can see messages like
1456 \begin_layout Standard
1460 \begin_layout Plain Layout
1467 \begin_layout Plain Layout
1469 17:58:47.868: Processing code chunks with options ...
1472 \begin_layout Plain Layout
1474 17:58:47.885: 1 : echo keep.source term verbatim (label=setup)
1477 \begin_layout Plain Layout
1479 17:58:47.889: 2 : echo keep.source (label=sweave-manual)
1482 \begin_layout Plain Layout
1484 17:58:47.908: 3 : echo keep.source term verbatim (label=print-integers)
1487 \begin_layout Plain Layout
1492 \begin_layout Plain Layout
1494 17:58:47.941: Loading required package: xtable
1497 \begin_layout Plain Layout
1499 17:58:47.976: 9 : echo term verbatim pdf (label=iris-pairs)
1502 \begin_layout Plain Layout
1507 \begin_layout Plain Layout
1509 17:58:48.116: You can now run (pdf)latex on 'sweave.tex'
1512 \begin_layout Plain Layout
1524 \begin_layout Standard
1530 If any chunk causes an error in R, you will see the error message here
1534 \begin_layout Standard
1535 Another issue with the \SpecialChar TeX
1536 code environment is the Sweave code chunk may fail
1537 when we change the alignment of the chunk paragraph in \SpecialChar LyX
1542 ), because \SpecialChar LyX
1543 may add a macro like
1549 before the code chunk without adding a new line, which will lead to a code
1553 \begin_layout Standard
1557 \begin_layout Plain Layout
1564 \begin_layout Plain Layout
1568 centering{}<<xtable-demo,results=tex,echo=FALSE>>=
1571 \begin_layout Plain Layout
1583 \begin_layout Standard
1584 This is not a legitimate Sweave code chunk, since
1588 must start in a new line with nothing before it.
1589 This does not happen when using the Chunk inset instead of the \SpecialChar TeX
1595 \begin_layout Section
1599 \begin_layout Standard
1600 The user manual of Sweave is at
1601 \begin_inset Flex URL
1604 \begin_layout Plain Layout
1606 https://stat.ethz.ch/R-manual/R-devel/library/utils/doc/Sweave.pdf
1612 The CRAN task view on
1613 \begin_inset Quotes eld
1616 Reproducible Research
1617 \begin_inset Quotes erd
1620 has a list of Sweave-related packages which can be potentially useful;
1622 \begin_inset Flex URL
1625 \begin_layout Plain Layout
1627 http://cran.r-project.org/web/views/ReproducibleResearch.html
1633 Questions about \SpecialChar LyX
1634 and Sweave can be posted to the \SpecialChar LyX
1636 \begin_inset Flex URL
1639 \begin_layout Plain Layout
1641 http://www.lyx.org/MailingLists
1647 More \SpecialChar LyX
1648 examples are provided at
1649 \begin_inset Flex URL
1652 \begin_layout Plain Layout
1654 https://github.com/yihui/lyx
1662 \begin_layout Section
1666 \begin_layout Subsection
1667 How to use Sweave with beamer?
1670 \begin_layout Standard
1671 You will end up with \SpecialChar LaTeX
1672 errors if you use Sweave in normal beamer slides in
1674 ; the reason is the beamer frame that contains verbatim R code.
1675 The solution is to use a
1683 , or to pass the option
1687 to the frame title via
1689 Insert\SpecialChar menuseparator
1695 \begin_layout Subsection
1696 Can I define my own R script to compile the Rnw document?
1699 \begin_layout Standard
1701 First you need to understand how the R script
1705 /scripts/lyxsweave.R
1707 works, which was introduced previously, and we recommend you to read the
1708 R source code as well (on how R takes the paths and uses
1712 to handle the Rnw document).
1713 Then you put your customized
1727 Help\SpecialChar menuseparator
1728 About \SpecialChar LyX
1732 Note \SpecialChar LyX
1737 before going to its own
1745 is found in the user directory, it will be used.
1746 It is not recommended to hack the script under the \SpecialChar LyX
1747 library directory directly,
1748 since updating \SpecialChar LyX
1749 will override you modified script (the user directory will
1753 \begin_layout Standard
1754 Beside the support for the official Sweave in R, the
1758 package is also supported, which is an alternative tool to Sweave; the
1759 corresponding module is named