1 #LyX 2.4 created this file. For more info see https://www.lyx.org/
5 \save_transient_properties true
6 \origin /systemlyxdir/examples/Modules/
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 no
26 \language_package auto
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_typewriter_osf false
39 \font_sf_scale 100 100
40 \font_tt_scale 100 100
42 \use_dash_ligatures false
44 \default_output_format default
46 \bibtex_command default
47 \index_command default
48 \paperfontsize default
53 \use_package amsmath 1
54 \use_package amssymb 1
57 \use_package mathdots 1
58 \use_package mathtools 1
60 \use_package stackrel 1
61 \use_package stmaryrd 1
62 \use_package undertilde 1
64 \cite_engine_type default
68 \paperorientation portrait
84 \paragraph_separation indent
85 \paragraph_indentation default
87 \math_numbering_side default
92 \paperpagestyle default
93 \tracking_changes false
94 \postpone_fragile_content false
103 \begin_layout Standard
104 \begin_inset Note Note
107 \begin_layout Plain Layout
108 \begin_inset Flex Sweave Options
111 \begin_layout Plain Layout
113 prefix=TRUE,prefix.string=sweave-prefix,keep.source=FALSE
126 \begin_layout Standard
130 \begin_layout Plain Layout
134 maxwidth was defined in the preamble; see document settings
137 \begin_layout Plain Layout
152 Using Sweave with \SpecialChar LyX
161 \begin_layout Plain Layout
162 Department of Statistics, Iowa State University.
164 \begin_inset CommandInset href
166 name "xie@yihui.name"
167 target "xie@yihui.name"
182 \begin_layout Plain Layout
195 \begin_layout Plain Layout
207 \begin_layout Standard
208 Sweave is a tool in the R language (
209 \begin_inset Flex URL
212 \begin_layout Plain Layout
214 http://www.r-project.org
219 ) for dynamic report generation using the ideas of literate programming.
220 R code can be mixed into a \SpecialChar LaTeX
221 document, and will be executed in R when the
222 document is compiled; the results are written into the \SpecialChar TeX
226 \begin_layout Standard
227 Since \SpecialChar LyX
228 2.0, Sweave can be used out of the box with any document class using
238 module to a \SpecialChar LyX
241 Document\SpecialChar menuseparator
242 Settings\SpecialChar menuseparator
246 In this manual, we demonstrate some common features of Sweave and explain
247 how the module works.
248 A PDF version of this manual can be found at
249 \begin_inset Flex URL
252 \begin_layout Plain Layout
254 https://github.com/downloads/yihui/lyx/sweave.pdf
262 \begin_layout Standard
263 Since \SpecialChar LyX
264 2.3, it is necessary to enable the use of
270 Preferences\SpecialChar menuseparator
271 File Handling\SpecialChar menuseparator
274 in order to compile with Sweave.
277 \begin_layout Section
281 \begin_layout Standard
286 module depends on the executable
290 , so it has to be in the
294 variable of the system.
295 It is usually not a problem for Linux and Mac OS users, but may be confusing
296 to Windows users; if you do not understand what is
300 under Windows, you may either use the R script
305 \begin_inset Flex URL
308 \begin_layout Plain Layout
310 https://github.com/yihui/lyx
315 to change it automatically (not recommended; you should learn
321 Tools\SpecialChar menuseparator
322 Preferences\SpecialChar menuseparator
323 Paths\SpecialChar menuseparator
326 to add the bin path of R (recommended), which is often like
338 and you can find it in R:
341 \begin_layout Standard
342 \begin_inset Flex Chunk
345 \begin_layout Plain Layout
347 \begin_inset Argument 1
350 \begin_layout Plain Layout
352 where-is-R-bin,eval=FALSE
360 \begin_layout Plain Layout
370 \begin_layout Standard
371 After you have done these changes, you need to reconfigure \SpecialChar LyX
374 Tools\SpecialChar menuseparator
390 module will be unavailable.
391 It is recommended to use the latest version of R, since Sweave is still
393 Another dependency is introduced by the \SpecialChar LaTeX
398 which is shipped with R under this path (it is not on CTAN):
401 \begin_layout Standard
402 \begin_inset Flex Chunk
405 \begin_layout Plain Layout
407 \begin_inset Argument 1
410 \begin_layout Plain Layout
412 sweave-sty,eval=FALSE
420 \begin_layout Plain Layout
422 file.path(R.home('share'), 'texmf', 'tex', 'latex')
430 \begin_layout Standard
432 users may add the texmf directory to the list of root directories in
434 through Mik\SpecialChar TeX
458 , it will directly copy from R, so the Sweave module works even if you do
459 not know where is this style file.
462 \begin_layout Section
466 \begin_layout Standard
467 Before we write an Sweave document, we can set some Sweave options; the
474 in Sweave and it can be inserted in a \SpecialChar LyX
477 Insert\SpecialChar menuseparator
478 Custom Insets\SpecialChar menuseparator
481 , or just use \SpecialChar TeX
484 Insert\SpecialChar menuseparator
489 For example, we can set a global option
493 in the beginning of a document to suppress all R code (by default, both
494 R code and its output will show up in the \SpecialChar LaTeX
499 \begin_layout Standard
500 To write R code in \SpecialChar LyX
501 , you can first insert
507 Insert\SpecialChar menuseparator
508 Custom Insets\SpecialChar menuseparator
511 , or you can simply open a \SpecialChar TeX
512 code environment and write Sweave code chunks
514 However, \SpecialChar LyX
515 provides a summary of all the
519 insets in the document in the
521 Navigate\SpecialChar menuseparator
526 View\SpecialChar menuseparator
532 \begin_layout Standard
533 Some R options can be useful to the Sweave output as well, e.g.
543 The former option can adjust the width of the output, and the latter can
544 avoid a common problem with quotes.
545 Users are encouraged to read the Sweave manual in R for more details.
548 \begin_layout Standard
549 \begin_inset Flex Chunk
552 \begin_layout Plain Layout
554 \begin_inset Argument 1
557 \begin_layout Plain Layout
559 setup, keep.source=TRUE
567 \begin_layout Plain Layout
569 ## the option 'digits' can set the (approximate) number of digits
572 \begin_layout Plain Layout
574 options(width = 70, useFancyQuotes = FALSE, digits = 4)
582 \begin_layout Standard
583 \begin_inset Flex Chunk
586 \begin_layout Plain Layout
588 \begin_inset Argument 1
591 \begin_layout Plain Layout
593 sweave-manual, eval=FALSE, keep.source=TRUE
601 \begin_layout Plain Layout
603 ## view the Sweave vignette (requires R >= 2.13.0)
606 \begin_layout Plain Layout
608 vignette("Sweave", package = "utils")
616 \begin_layout Standard
617 A simple example that will run in any S engine:
620 \begin_layout Standard
621 \begin_inset Flex Chunk
624 \begin_layout Plain Layout
626 \begin_inset Argument 1
629 \begin_layout Plain Layout
631 print-integers, keep.source=TRUE
639 \begin_layout Plain Layout
641 ## the integers from 1 to 10 are
644 \begin_layout Plain Layout
654 \begin_layout Standard
655 \begin_inset Flex Chunk
658 \begin_layout Plain Layout
660 \begin_inset Argument 1
663 \begin_layout Plain Layout
665 hide-results, results=hide
673 \begin_layout Plain Layout
675 ## intentionally hide the output by setting results=hide
678 \begin_layout Plain Layout
688 \begin_layout Standard
689 We can also emulate a simple calculator:
692 \begin_layout Standard
693 \begin_inset Flex Chunk
696 \begin_layout Plain Layout
698 \begin_inset Argument 1
701 \begin_layout Plain Layout
711 \begin_layout Plain Layout
716 \begin_layout Plain Layout
726 \begin_layout Standard
727 Now we look at some Gaussian data:
730 \begin_layout Standard
731 \begin_inset Flex Chunk
734 \begin_layout Plain Layout
736 \begin_inset Argument 1
739 \begin_layout Plain Layout
749 \begin_layout Plain Layout
751 set.seed(123) # for reproducibility
754 \begin_layout Plain Layout
759 \begin_layout Plain Layout
764 \begin_layout Plain Layout
774 \begin_layout Standard
775 Note that we can easily integrate some numbers into standard text; this
776 is done with the command
782 , and the corresponding \SpecialChar LyX
785 Insert\SpecialChar menuseparator
786 Custom Insets\SpecialChar menuseparator
789 , or alternatively just use \SpecialChar TeX
791 For example, the third element of the vector
796 \begin_inset Flex S/R expression
799 \begin_layout Plain Layout
812 \begin_inset Formula $p$
815 -value of the test is
816 \begin_inset Flex S/R expression
819 \begin_layout Plain Layout
821 format.pval(t1$p.value)
827 You can round these numbers using functions like
835 \begin_layout Standard
845 Now we look at a summary of the
866 \begin_layout Standard
867 \begin_inset Flex Chunk
870 \begin_layout Plain Layout
872 \begin_inset Argument 1
875 \begin_layout Plain Layout
885 \begin_layout Plain Layout
895 \begin_layout Standard
896 \begin_inset Float table
901 \begin_layout Plain Layout
902 \begin_inset Caption Standard
904 \begin_layout Plain Layout
905 Quantiles of the first four variables in the
910 \begin_inset CommandInset label
912 name "tab:xtable-demo"
922 \begin_inset Flex Chunk
925 \begin_layout Plain Layout
927 \begin_inset Argument 1
930 \begin_layout Plain Layout
932 xtable-demo,results=tex,echo=FALSE
940 \begin_layout Plain Layout
942 if (require('xtable')) {
945 \begin_layout Plain Layout
947 print(xtable(sapply(iris[,-5], quantile)), floating=FALSE)
950 \begin_layout Plain Layout
952 } else cat('the xtable package is not available! please install.packages("xtable"
966 \begin_layout Standard
967 Usually people do not like such
968 \begin_inset Quotes eld
972 \begin_inset Quotes erd
975 output, and we can polish these messy numbers with the
981 \begin_inset CommandInset ref
983 reference "tab:xtable-demo"
987 is an example demonstrating how to use the
991 package with Sweave; note the chunk option
995 makes sure that the R output is written out as raw \SpecialChar LaTeX
996 code instead of being
997 wrapped in a special environment (
1004 \begin_layout Standard
1006 \begin_inset CommandInset ref
1008 reference "fig:iris-pairs"
1013 \begin_inset CommandInset ref
1015 reference "fig:iris-boxplots"
1019 are two simple examples of producing graphics output with Sweave.
1022 \begin_layout Standard
1023 \begin_inset Float figure
1028 \begin_layout Plain Layout
1030 \begin_inset Note Note
1033 \begin_layout Plain Layout
1034 Both eps and pdf are set to true so that both latex and pdflatex work.
1035 In practice, you would probably just choose one.
1043 \begin_layout Plain Layout
1045 \begin_inset Flex Chunk
1048 \begin_layout Plain Layout
1050 \begin_inset Argument 1
1053 \begin_layout Plain Layout
1055 iris-pairs,fig=TRUE,width=4.5,height=4.5,eps=TRUE,pdf=TRUE
1063 \begin_layout Plain Layout
1065 pairs(iris, col = iris$Species)
1073 \begin_layout Plain Layout
1074 \begin_inset Caption Standard
1076 \begin_layout Plain Layout
1077 Scatter plot matrix of the
1082 \begin_inset CommandInset label
1084 name "fig:iris-pairs"
1101 \begin_layout Standard
1102 \begin_inset Float figure
1107 \begin_layout Plain Layout
1109 \begin_inset Flex Chunk
1112 \begin_layout Plain Layout
1114 \begin_inset Argument 1
1117 \begin_layout Plain Layout
1119 iris-boxplots,fig=TRUE,width=7,height=2,keep.source=F,eps=T,pdf=T
1127 \begin_layout Plain Layout
1129 par(mar=c(4,5,.1,.3), las=1)
1132 \begin_layout Plain Layout
1134 boxplot(Sepal.Length~Species,data=iris,horizontal=TRUE,xlab='Sepal.Length')
1142 \begin_layout Plain Layout
1143 \begin_inset Caption Standard
1145 \begin_layout Plain Layout
1146 Boxplots of sepal length grouped by species.
1147 \begin_inset CommandInset label
1149 name "fig:iris-boxplots"
1166 \begin_layout Standard
1167 We can also export all the R code in an Sweave document as a single R script
1170 File\SpecialChar menuseparator
1171 Export\SpecialChar menuseparator
1174 ), which is done via
1181 \begin_layout Section
1189 \begin_layout Standard
1194 module declares that a \SpecialChar LyX
1195 document contains literate programming components
1196 with R, so that \SpecialChar LyX
1197 will handle such documents according to the specific converter
1198 s (see the Customization manual).
1207 converter, which essentially consists of an R script
1215 directory of \SpecialChar LyX
1217 This script takes an
1221 document from \SpecialChar LyX
1222 and call Sweave to process it to a \SpecialChar TeX
1223 document, then \SpecialChar LyX
1225 care of the rest of work.
1228 \begin_layout Standard
1229 The converter from the
1233 format to \SpecialChar LaTeX
1234 is a call to R via the command line as:
1237 \begin_layout Standard
1241 \begin_layout Plain Layout
1248 \begin_layout Plain Layout
1250 Rscript --no-save --no-restore $$s/scripts/lyxsweave.R $$p$$i $$p$$o $$e
1254 \begin_layout Plain Layout
1266 \begin_layout Standard
1267 The \SpecialChar LyX
1272 can be found from the menu
1274 Help\SpecialChar menuseparator
1275 About \SpecialChar LyX
1279 All the rest of options passed to R are explained in the R script, and
1280 the \SpecialChar LyX
1281 Customization manual also has detailed explanations about
1298 General users do not need to know clearly what they mean, but here we need
1299 to explain a few issues in the R code:
1302 \begin_layout Enumerate
1303 the encoding string of the \SpecialChar LyX
1304 document is passed to R as an command line option;
1314 The encoding is used for R to read the
1321 \begin_layout Enumerate
1322 the R code chunks in the Sweave document are executed under the directory
1323 of the \SpecialChar LyX
1324 document (if you are not sure, put
1328 in a code chunk to see what is the current working directory).
1329 In this case, you can put data files under the same directory and use relative
1330 paths in R to guarantee reproducibility, i.e.
1331 we do not need to write hard-coded paths which may not exist in other systems.
1334 \begin_layout Enumerate
1335 if \SpecialChar LaTeX
1340 , this R script will copy it to the temporary directory automatically where
1341 the \SpecialChar LaTeX
1342 compilation takes place.
1345 \begin_layout Enumerate
1346 Sweave will use the filename of the Rnw file as the prefix string for the
1347 graphics output by default; one known issue (
1348 \begin_inset CommandInset href
1351 target "https://www.lyx.org/trac/ticket/7551"
1356 ) is that if the filename (without extension) contains dots, \SpecialChar LaTeX
1358 deal with such files in
1365 Therefore, we have set the default value of the prefix to be the filename
1366 with all the dots being replaced by
1367 \begin_inset Quotes eld
1371 \begin_inset Quotes erd
1375 We can also solve this problem in Sweave directly: set the Sweave option
1380 to be a character string without dots, and this option will override the
1384 \begin_layout Standard
1385 We have pre-specified an option
1389 for the Sweave package.
1390 This option stops Sweave from loading these two packages:
1393 \begin_layout Standard
1397 \begin_layout Plain Layout
1404 \begin_layout Plain Layout
1408 RequirePackage[T1]{fontenc}
1411 \begin_layout Plain Layout
1418 \begin_layout Plain Layout
1430 \begin_layout Standard
1432 can deal with the font encoding by default, so there is no need to ask
1433 Sweave to do this (furthermore, this may bring clashes of package options);
1434 besides, the users can load the
1438 package by themselves in the preamble if needed.
1441 \begin_layout Section
1445 \begin_layout Standard
1446 Since \SpecialChar LyX
1447 2.0, we can see the detailed information during compilation via
1449 View\SpecialChar menuseparator
1453 This is extremely helpful for trouble shooting – the process of R will
1454 be shown in the message panel, and we will be able to know which chunk
1455 goes wrong in cases of errors.
1456 For example, when you compile this document, you can see messages like
1460 \begin_layout Standard
1464 \begin_layout Plain Layout
1471 \begin_layout Plain Layout
1473 17:58:47.868: Processing code chunks with options ...
1476 \begin_layout Plain Layout
1478 17:58:47.885: 1 : echo keep.source term verbatim (label=setup)
1481 \begin_layout Plain Layout
1483 17:58:47.889: 2 : echo keep.source (label=sweave-manual)
1486 \begin_layout Plain Layout
1488 17:58:47.908: 3 : echo keep.source term verbatim (label=print-integers)
1491 \begin_layout Plain Layout
1496 \begin_layout Plain Layout
1498 17:58:47.941: Loading required package: xtable
1501 \begin_layout Plain Layout
1503 17:58:47.976: 9 : echo term verbatim pdf (label=iris-pairs)
1506 \begin_layout Plain Layout
1511 \begin_layout Plain Layout
1513 17:58:48.116: You can now run (pdf)latex on 'sweave.tex'
1516 \begin_layout Plain Layout
1528 \begin_layout Standard
1534 If any chunk causes an error in R, you will see the error message here
1538 \begin_layout Standard
1539 Another issue with the \SpecialChar TeX
1540 code environment is the Sweave code chunk may fail
1541 when we change the alignment of the chunk paragraph in \SpecialChar LyX
1546 ), because \SpecialChar LyX
1547 may add a macro like
1553 before the code chunk without adding a new line, which will lead to a code
1557 \begin_layout Standard
1561 \begin_layout Plain Layout
1568 \begin_layout Plain Layout
1572 centering{}<<xtable-demo,results=tex,echo=FALSE>>=
1575 \begin_layout Plain Layout
1587 \begin_layout Standard
1588 This is not a legitimate Sweave code chunk, since
1592 must start in a new line with nothing before it.
1593 This does not happen when using the Chunk inset instead of the \SpecialChar TeX
1599 \begin_layout Section
1603 \begin_layout Standard
1604 The user manual of Sweave is at
1605 \begin_inset Flex URL
1608 \begin_layout Plain Layout
1610 https://stat.ethz.ch/R-manual/R-devel/library/utils/doc/Sweave.pdf
1616 The CRAN task view on
1617 \begin_inset Quotes eld
1620 Reproducible Research
1621 \begin_inset Quotes erd
1624 has a list of Sweave-related packages which can be potentially useful;
1626 \begin_inset Flex URL
1629 \begin_layout Plain Layout
1631 http://cran.r-project.org/web/views/ReproducibleResearch.html
1637 Questions about \SpecialChar LyX
1638 and Sweave can be posted to the \SpecialChar LyX
1640 \begin_inset Flex URL
1643 \begin_layout Plain Layout
1645 https://www.lyx.org/MailingLists
1651 More \SpecialChar LyX
1652 examples are provided at
1653 \begin_inset Flex URL
1656 \begin_layout Plain Layout
1658 https://github.com/yihui/lyx
1666 \begin_layout Section
1670 \begin_layout Subsection
1671 How to use Sweave with beamer?
1674 \begin_layout Standard
1675 You will end up with \SpecialChar LaTeX
1676 errors if you use Sweave in normal beamer slides in
1678 ; the reason is the beamer frame that contains verbatim R code.
1679 The solution is to use a
1687 , or to pass the option
1691 to the frame title via
1693 Insert\SpecialChar menuseparator
1699 \begin_layout Subsection
1700 Can I define my own R script to compile the Rnw document?
1703 \begin_layout Standard
1705 First you need to understand how the R script
1709 /scripts/lyxsweave.R
1711 works, which was introduced previously, and we recommend you to read the
1712 R source code as well (on how R takes the paths and uses
1716 to handle the Rnw document).
1717 Then you put your customized
1731 Help\SpecialChar menuseparator
1732 About \SpecialChar LyX
1736 Note \SpecialChar LyX
1741 before going to its own
1749 is found in the user directory, it will be used.
1750 It is not recommended to hack the script under the \SpecialChar LyX
1751 library directory directly,
1752 since updating \SpecialChar LyX
1753 will override you modified script (the user directory will
1757 \begin_layout Standard
1758 Beside the support for the official Sweave in R, the
1762 package is also supported, which is an alternative tool to Sweave; the
1763 corresponding module is named