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 \default_output_format default
42 \bibtex_command default
43 \index_command default
44 \paperfontsize default
49 \use_package amsmath 1
50 \use_package amssymb 1
53 \use_package mathdots 1
54 \use_package mathtools 0
56 \use_package stackrel 0
57 \use_package stmaryrd 0
58 \use_package undertilde 0
60 \cite_engine_type default
64 \paperorientation portrait
78 \paragraph_separation indent
79 \paragraph_indentation default
80 \quotes_language english
83 \paperpagestyle default
84 \tracking_changes true
89 \author 2047637253 "Guillaume Munch"
94 \begin_layout Standard
96 \change_inserted 2047637253 1483897614
97 \begin_inset Note Note
100 \begin_layout Plain Layout
102 \change_inserted 2047637253 1483897614
103 \begin_inset Flex Sweave Options
106 \begin_layout Plain Layout
108 \change_inserted 2047637253 1483897614
110 prefix=TRUE,prefix.string=sweave-prefix,keep.source=FALSE
125 \begin_layout Standard
129 \begin_layout Plain Layout
133 maxwidth was defined in the preamble; see document settings
136 \begin_layout Plain Layout
151 Using Sweave with \SpecialChar LyX
160 \begin_layout Plain Layout
161 Department of Statistics, Iowa State University.
163 \begin_inset CommandInset href
165 name "xie@yihui.name"
166 target "xie@yihui.name"
180 \begin_layout Plain Layout
193 \begin_layout Plain Layout
205 \begin_layout Standard
206 Sweave is a tool in the R language (
207 \begin_inset Flex URL
210 \begin_layout Plain Layout
212 http://www.r-project.org
217 ) for dynamic report generation using the ideas of literate programming.
218 R code can be mixed into a \SpecialChar LaTeX
219 document, and will be executed in R when the
220 document is compiled; the results are written into the \SpecialChar TeX
224 \begin_layout Standard
225 Since \SpecialChar LyX
226 2.0, Sweave can be used out of the box with any document class using
236 module to a \SpecialChar LyX
239 Document\SpecialChar menuseparator
240 Settings\SpecialChar menuseparator
244 In this manual, we demonstrate some common features of Sweave and explain
245 how the module works.
246 A PDF version of this manual can be found at
247 \begin_inset Flex URL
250 \begin_layout Plain Layout
252 https://github.com/downloads/yihui/lyx/sweave.pdf
258 \change_inserted 2047637253 1483898587
262 \begin_layout Standard
264 \change_inserted 2047637253 1483899123
265 Since \SpecialChar LyX
266 2.3, it is necessary to enable the use of
272 Preferences\SpecialChar menuseparator
273 File Handling\SpecialChar menuseparator
276 in order to compile with Sweave.
281 \begin_layout Section
285 \begin_layout Standard
290 module depends on the executable
294 , so it has to be in the
298 variable of the system.
299 It is usually not a problem for Linux and Mac OS users, but may be confusing
300 to Windows users; if you do not understand what is
304 under Windows, you may either use the R script
309 \begin_inset Flex URL
312 \begin_layout Plain Layout
314 https://github.com/yihui/lyx
319 to change it automatically (not recommended; you should learn
325 Tools\SpecialChar menuseparator
326 Preferences\SpecialChar menuseparator
327 Paths\SpecialChar menuseparator
330 to add the bin path of R (recommended), which is often like
342 and you can find it in R:
345 \begin_layout Standard
347 \change_inserted 2047637253 1483897627
348 \begin_inset Flex Chunk
351 \begin_layout Plain Layout
353 \change_inserted 2047637253 1483897627
355 \begin_inset Argument 1
358 \begin_layout Plain Layout
360 \change_inserted 2047637253 1483897627
361 where-is-R-bin,eval=FALSE
369 \begin_layout Plain Layout
371 \change_inserted 2047637253 1483897627
383 \begin_layout Standard
384 After you have done these changes, you need to reconfigure \SpecialChar LyX
387 Tools\SpecialChar menuseparator
403 module will be unavailable.
404 It is recommended to use the latest version of R, since Sweave is still
406 Another dependency is introduced by the \SpecialChar LaTeX
411 which is shipped with R under this path (it is not on CTAN):
414 \begin_layout Standard
416 \change_inserted 2047637253 1483897639
417 \begin_inset Flex Chunk
420 \begin_layout Plain Layout
422 \change_inserted 2047637253 1483897639
424 \begin_inset Argument 1
427 \begin_layout Plain Layout
429 \change_inserted 2047637253 1483897639
430 sweave-sty,eval=FALSE
438 \begin_layout Plain Layout
440 \change_inserted 2047637253 1483897639
442 file.path(R.home('share'), 'texmf', 'tex', 'latex')
452 \begin_layout Standard
454 users may add the texmf directory to the list of root directories in
456 through Mik\SpecialChar TeX
480 , it will directly copy from R, so the Sweave module works even if you do
481 not know where is this style file.
484 \begin_layout Section
488 \begin_layout Standard
489 Before we write an Sweave document, we can set some Sweave options; the
496 in Sweave and it can be inserted in a \SpecialChar LyX
499 Insert\SpecialChar menuseparator
500 Custom Insets\SpecialChar menuseparator
503 , or just use \SpecialChar TeX
506 Insert\SpecialChar menuseparator
511 For example, we can set a global option
515 in the beginning of a document to suppress all R code (by default, both
516 R code and its output will show up in the \SpecialChar LaTeX
521 \begin_layout Standard
522 To write R code in \SpecialChar LyX
524 \change_inserted 2047637253 1483898412
526 \change_deleted 2047637253 1483898419
534 \change_inserted 2047637253 1483898437
537 Insert\SpecialChar menuseparator
538 Custom Insets\SpecialChar menuseparator
540 \change_deleted 2047637253 1483898459
543 environment in the layout styles list (droplist in the top-left corner in
546 , or you can simply open a \SpecialChar TeX
547 code environment and write Sweave code chunks
550 \change_deleted 2047637253 1483898024
551 The latter approach is recommended since it is more stable.
552 \change_inserted 2047637253 1483961753
553 However, \SpecialChar LyX
554 provides a summary of all the
558 insets in the document in the
560 Navigate\SpecialChar menuseparator
565 View\SpecialChar menuseparator
573 \begin_layout Standard
574 Some R options can be useful to the Sweave output as well, e.g.
584 The former option can adjust the width of the output, and the latter can
585 avoid a common problem with quotes.
586 Users are encouraged to read the Sweave manual in R for more details.
589 \begin_layout Standard
591 \change_inserted 2047637253 1483897653
592 \begin_inset Flex Chunk
595 \begin_layout Plain Layout
597 \change_inserted 2047637253 1483897653
599 \begin_inset Argument 1
602 \begin_layout Plain Layout
604 \change_inserted 2047637253 1483897653
605 setup, keep.source=TRUE
613 \begin_layout Plain Layout
615 \change_inserted 2047637253 1483897653
617 ## the option 'digits' can set the (approximate) number of digits
620 \begin_layout Plain Layout
622 \change_inserted 2047637253 1483897653
624 options(width = 70, useFancyQuotes = FALSE, digits = 4)
632 \begin_layout Standard
634 \change_inserted 2047637253 1483897653
635 \begin_inset Flex Chunk
638 \begin_layout Plain Layout
640 \change_inserted 2047637253 1483897653
642 \begin_inset Argument 1
645 \begin_layout Plain Layout
647 \change_inserted 2047637253 1483897653
648 sweave-manual, eval=FALSE, keep.source=TRUE
656 \begin_layout Plain Layout
658 \change_inserted 2047637253 1483897653
660 ## view the Sweave vignette (requires R >= 2.13.0)
663 \begin_layout Plain Layout
665 \change_inserted 2047637253 1483897653
667 vignette("Sweave", package = "utils")
677 \begin_layout Standard
678 A simple example that will run in any S engine:
681 \begin_layout Standard
683 \change_inserted 2047637253 1483897659
684 \begin_inset Flex Chunk
687 \begin_layout Plain Layout
689 \change_inserted 2047637253 1483897659
691 \begin_inset Argument 1
694 \begin_layout Plain Layout
696 \change_inserted 2047637253 1483897659
697 print-integers, keep.source=TRUE
705 \begin_layout Plain Layout
707 \change_inserted 2047637253 1483897659
709 ## the integers from 1 to 10 are
712 \begin_layout Plain Layout
714 \change_inserted 2047637253 1483897659
724 \begin_layout Standard
726 \change_inserted 2047637253 1483897659
727 \begin_inset Flex Chunk
730 \begin_layout Plain Layout
732 \change_inserted 2047637253 1483897659
734 \begin_inset Argument 1
737 \begin_layout Plain Layout
739 \change_inserted 2047637253 1483897659
740 hide-results, results=hide
748 \begin_layout Plain Layout
750 \change_inserted 2047637253 1483897659
752 ## intentionally hide the output by setting results=hide
755 \begin_layout Plain Layout
757 \change_inserted 2047637253 1483897659
769 \begin_layout Standard
770 We can also emulate a simple calculator:
773 \begin_layout Standard
775 \change_inserted 2047637253 1483897665
776 \begin_inset Flex Chunk
779 \begin_layout Plain Layout
781 \change_inserted 2047637253 1483897665
783 \begin_inset Argument 1
786 \begin_layout Plain Layout
788 \change_inserted 2047637253 1483897665
797 \begin_layout Plain Layout
799 \change_inserted 2047637253 1483897665
804 \begin_layout Plain Layout
806 \change_inserted 2047637253 1483897665
818 \begin_layout Standard
819 Now we look at some Gaussian data:
822 \begin_layout Standard
824 \change_inserted 2047637253 1483897670
825 \begin_inset Flex Chunk
828 \begin_layout Plain Layout
830 \change_inserted 2047637253 1483897670
832 \begin_inset Argument 1
835 \begin_layout Plain Layout
837 \change_inserted 2047637253 1483897670
846 \begin_layout Plain Layout
848 \change_inserted 2047637253 1483897670
850 set.seed(123) # for reproducibility
853 \begin_layout Plain Layout
855 \change_inserted 2047637253 1483897670
860 \begin_layout Plain Layout
862 \change_inserted 2047637253 1483897670
867 \begin_layout Plain Layout
869 \change_inserted 2047637253 1483897670
881 \begin_layout Standard
882 Note that we can easily integrate some numbers into standard text; this
883 is done with the command
889 , and the corresponding \SpecialChar LyX
892 Insert\SpecialChar menuseparator
893 Custom Insets\SpecialChar menuseparator
896 , or alternatively just use \SpecialChar TeX
898 For example, the third element of the vector
903 \begin_inset Flex S/R expression
906 \begin_layout Plain Layout
919 \begin_inset Formula $p$
922 -value of the test is
923 \begin_inset Flex S/R expression
926 \begin_layout Plain Layout
928 format.pval(t1$p.value)
934 You can round these numbers using functions like
942 \begin_layout Standard
952 Now we look at a summary of the
973 \begin_layout Standard
975 \change_inserted 2047637253 1483897677
976 \begin_inset Flex Chunk
979 \begin_layout Plain Layout
981 \change_inserted 2047637253 1483897677
983 \begin_inset Argument 1
986 \begin_layout Plain Layout
988 \change_inserted 2047637253 1483897677
997 \begin_layout Plain Layout
999 \change_inserted 2047637253 1483897677
1011 \begin_layout Standard
1012 \begin_inset Float table
1017 \begin_layout Plain Layout
1018 \begin_inset Caption Standard
1020 \begin_layout Plain Layout
1021 Quantiles of the first four variables in the
1026 \begin_inset CommandInset label
1028 name "tab:xtable-demo"
1038 \change_inserted 2047637253 1483897685
1040 \begin_inset Flex Chunk
1043 \begin_layout Plain Layout
1045 \change_inserted 2047637253 1483897698
1047 \begin_inset Argument 1
1050 \begin_layout Plain Layout
1052 \change_inserted 2047637253 1483897692
1053 xtable-demo,results=tex,echo=FALSE
1063 \begin_layout Plain Layout
1065 \change_inserted 2047637253 1483897699
1067 if (require('xtable')) {
1070 \begin_layout Plain Layout
1072 \change_inserted 2047637253 1483897699
1074 print(xtable(sapply(iris[,-5], quantile)), floating=FALSE)
1077 \begin_layout Plain Layout
1079 \change_inserted 2047637253 1483897699
1081 } else cat('the xtable package is not available! please install.packages("xtable"
1099 \begin_layout Standard
1100 Usually people do not like such
1101 \begin_inset Quotes eld
1105 \begin_inset Quotes erd
1108 output, and we can polish these messy numbers with the
1114 \begin_inset CommandInset ref
1116 reference "tab:xtable-demo"
1120 is an example demonstrating how to use the
1124 package with Sweave; note the chunk option
1128 makes sure that the R output is written out as raw \SpecialChar LaTeX
1129 code instead of being
1130 wrapped in a special environment (
1137 \begin_layout Standard
1139 \begin_inset CommandInset ref
1141 reference "fig:iris-pairs"
1146 \begin_inset CommandInset ref
1148 reference "fig:iris-boxplots"
1152 are two simple examples of producing graphics output with Sweave.
1155 \begin_layout Standard
1156 \begin_inset Float figure
1161 \begin_layout Plain Layout
1163 \begin_inset Note Note
1166 \begin_layout Plain Layout
1167 Both eps and pdf are set to true so that both latex and pdflatex work.
1168 In practice, you would probably just choose one.
1176 \begin_layout Plain Layout
1179 \change_inserted 2047637253 1483897765
1180 \begin_inset Flex Chunk
1183 \begin_layout Plain Layout
1185 \change_inserted 2047637253 1483897772
1187 \begin_inset Argument 1
1190 \begin_layout Plain Layout
1192 \change_inserted 2047637253 1483897770
1193 iris-pairs,fig=TRUE,width=4.5,height=4.5,eps=TRUE,pdf=TRUE
1203 \begin_layout Plain Layout
1205 \change_inserted 2047637253 1483897776
1207 pairs(iris, col = iris$Species)
1219 \begin_layout Plain Layout
1220 \begin_inset Caption Standard
1222 \begin_layout Plain Layout
1223 Scatter plot matrix of the
1228 \begin_inset CommandInset label
1230 name "fig:iris-pairs"
1247 \begin_layout Standard
1248 \begin_inset Float figure
1253 \begin_layout Plain Layout
1256 \change_inserted 2047637253 1483897883
1257 \begin_inset Flex Chunk
1260 \begin_layout Plain Layout
1262 \change_inserted 2047637253 1483897883
1264 \begin_inset Argument 1
1267 \begin_layout Plain Layout
1269 \change_inserted 2047637253 1483897883
1270 iris-boxplots,fig=TRUE,width=7,height=2,keep.source=F,eps=T,pdf=T
1278 \begin_layout Plain Layout
1280 \change_inserted 2047637253 1483897883
1282 par(mar=c(4,5,.1,.3), las=1)
1285 \begin_layout Plain Layout
1287 \change_inserted 2047637253 1483897883
1289 boxplot(Sepal.Length~Species,data=iris,horizontal=TRUE,xlab='Sepal.Length')
1299 \begin_layout Plain Layout
1300 \begin_inset Caption Standard
1302 \begin_layout Plain Layout
1303 Boxplots of sepal length grouped by species.
1304 \begin_inset CommandInset label
1306 name "fig:iris-boxplots"
1323 \begin_layout Standard
1324 We can also export all the R code in an Sweave document as a single R script
1327 File\SpecialChar menuseparator
1328 Export\SpecialChar menuseparator
1331 ), which is done via
1336 \change_inserted 2047637253 1483898877
1340 \begin_layout Section
1348 \begin_layout Standard
1353 module declares that a \SpecialChar LyX
1354 document contains literate programming components
1355 with R, so that \SpecialChar LyX
1356 will handle such documents according to the specific converter
1357 s (see the Customization manual).
1366 converter, which essentially consists of an R script
1374 directory of \SpecialChar LyX
1376 This script takes an
1380 document from \SpecialChar LyX
1381 and call Sweave to process it to a \SpecialChar TeX
1382 document, then \SpecialChar LyX
1384 care of the rest of work.
1387 \begin_layout Standard
1388 The converter from the
1392 format to \SpecialChar LaTeX
1393 is a call to R via the command line as:
1396 \begin_layout Standard
1400 \begin_layout Plain Layout
1407 \begin_layout Plain Layout
1409 Rscript --no-save --no-restore $$s/scripts/lyxsweave.R $$p$$i $$p$$o $$e
1413 \begin_layout Plain Layout
1425 \begin_layout Standard
1426 The \SpecialChar LyX
1431 can be found from the menu
1433 Help\SpecialChar menuseparator
1434 About \SpecialChar LyX
1438 All the rest of options passed to R are explained in the R script, and
1439 the \SpecialChar LyX
1440 Customization manual also has detailed explanations about
1457 General users do not need to know clearly what they mean, but here we need
1458 to explain a few issues in the R code:
1461 \begin_layout Enumerate
1462 the encoding string of the \SpecialChar LyX
1463 document is passed to R as an command line option;
1473 The encoding is used for R to read the
1480 \begin_layout Enumerate
1481 the R code chunks in the Sweave document are executed under the directory
1482 of the \SpecialChar LyX
1483 document (if you are not sure, put
1487 in a code chunk to see what is the current working directory).
1488 In this case, you can put data files under the same directory and use relative
1489 paths in R to guarantee reproducibility, i.e.
1490 we do not need to write hard-coded paths which may not exist in other systems.
1493 \begin_layout Enumerate
1494 if \SpecialChar LaTeX
1499 , this R script will copy it to the temporary directory automatically where
1500 the \SpecialChar LaTeX
1501 compilation takes place.
1504 \begin_layout Enumerate
1505 Sweave will use the filename of the Rnw file as the prefix string for the
1506 graphics output by default; one known issue (
1507 \begin_inset CommandInset href
1510 target "http://www.lyx.org/trac/ticket/7551"
1514 ) is that if the filename (without extension) contains dots, \SpecialChar LaTeX
1516 deal with such files in
1523 Therefore, we have set the default value of the prefix to be the filename
1524 with all the dots being replaced by
1525 \begin_inset Quotes eld
1529 \begin_inset Quotes erd
1533 We can also solve this problem in Sweave directly: set the Sweave option
1538 to be a character string without dots, and this option will override the
1542 \begin_layout Standard
1543 We have pre-specified an option
1547 for the Sweave package.
1548 This option stops Sweave from loading these two packages:
1551 \begin_layout Standard
1555 \begin_layout Plain Layout
1562 \begin_layout Plain Layout
1566 RequirePackage[T1]{fontenc}
1569 \begin_layout Plain Layout
1576 \begin_layout Plain Layout
1588 \begin_layout Standard
1590 can deal with the font encoding by default, so there is no need to ask
1591 Sweave to do this (furthermore, this may bring clashes of package options);
1592 besides, the users can load the
1596 package by themselves in the preamble if needed.
1599 \begin_layout Section
1603 \begin_layout Standard
1604 Since \SpecialChar LyX
1605 2.0, we can see the detailed information during compilation via
1607 View\SpecialChar menuseparator
1611 This is extremely helpful for trouble shooting – the process of R will
1612 be shown in the message panel, and we will be able to know which chunk
1613 goes wrong in cases of errors.
1614 For example, when you compile this document, you can see messages like
1618 \begin_layout Standard
1622 \begin_layout Plain Layout
1629 \begin_layout Plain Layout
1631 17:58:47.868: Processing code chunks with options ...
1634 \begin_layout Plain Layout
1636 17:58:47.885: 1 : echo keep.source term verbatim (label=setup)
1639 \begin_layout Plain Layout
1641 17:58:47.889: 2 : echo keep.source (label=sweave-manual)
1644 \begin_layout Plain Layout
1646 17:58:47.908: 3 : echo keep.source term verbatim (label=print-integers)
1649 \begin_layout Plain Layout
1654 \begin_layout Plain Layout
1656 17:58:47.941: Loading required package: xtable
1659 \begin_layout Plain Layout
1661 17:58:47.976: 9 : echo term verbatim pdf (label=iris-pairs)
1664 \begin_layout Plain Layout
1669 \begin_layout Plain Layout
1671 17:58:48.116: You can now run (pdf)latex on 'sweave.tex'
1674 \begin_layout Plain Layout
1686 \begin_layout Standard
1692 If any chunk causes an error in R, you will see the error message here
1696 \begin_layout Standard
1698 \change_deleted 2047637253 1483899012
1702 \change_inserted 2047637253 1483898966
1703 with the \SpecialChar TeX
1706 is the Sweave code chunk may fail when we change the alignment of the chunk
1707 paragraph in \SpecialChar LyX
1712 ), because \SpecialChar LyX
1713 may add a macro like
1719 before the code chunk without adding a new line, which will lead to a code
1723 \begin_layout Standard
1727 \begin_layout Plain Layout
1734 \begin_layout Plain Layout
1738 centering{}<<xtable-demo,results=tex,echo=FALSE>>=
1741 \begin_layout Plain Layout
1753 \begin_layout Standard
1754 This is not a legitimate Sweave code chunk, since
1758 must start in a new line with nothing before it.
1760 \change_inserted 2047637253 1483899083
1761 This does not happen when using the Chunk inset instead of the \SpecialChar TeX
1767 \change_deleted 2047637253 1483898988
1768 Therefore we recommend you to double check the real source code via
1770 View\SpecialChar menuseparator
1773 when changing the alignment of a chunk paragraph, and make sure
1777 appears in a new line.
1778 This explains why we manually added an empty line in the code chunk in
1780 \begin_inset CommandInset ref
1782 reference "tab:xtable-demo"
1791 \begin_layout Section
1795 \begin_layout Standard
1796 The homepage of Sweave is at
1797 \begin_inset Flex URL
1800 \begin_layout Plain Layout
1802 http://www.stat.uni-muenchen.de/~leisch/Sweave/
1808 The CRAN task view on
1809 \begin_inset Quotes eld
1812 Reproducible Research
1813 \begin_inset Quotes erd
1816 has a list of Sweave-related packages which can be potentially useful;
1818 \begin_inset Flex URL
1821 \begin_layout Plain Layout
1823 http://cran.r-project.org/web/views/ReproducibleResearch.html
1829 Questions about \SpecialChar LyX
1830 and Sweave can be posted to the \SpecialChar LyX
1832 \begin_inset Flex URL
1835 \begin_layout Plain Layout
1837 http://www.lyx.org/MailingLists
1843 More \SpecialChar LyX
1844 examples are provided at
1845 \begin_inset Flex URL
1848 \begin_layout Plain Layout
1850 https://github.com/yihui/lyx
1858 \begin_layout Section
1862 \begin_layout Subsection
1863 How to use Sweave with beamer?
1866 \begin_layout Standard
1867 You will end up with \SpecialChar LaTeX
1868 errors if you use Sweave in normal beamer slides in
1870 ; the reason is the beamer frame that contains verbatim R code.
1871 The solution is to use a
1879 , or to pass the option
1883 to the frame title via
1885 Insert\SpecialChar menuseparator
1891 \begin_layout Subsection
1892 Can I define my own R script to compile the Rnw document?
1895 \begin_layout Standard
1897 First you need to understand how the R script
1901 /scripts/lyxsweave.R
1903 works, which was introduced previously, and we recommend you to read the
1904 R source code as well (on how R takes the paths and uses
1908 to handle the Rnw document).
1909 Then you put your customized
1923 Help\SpecialChar menuseparator
1924 About \SpecialChar LyX
1928 Note \SpecialChar LyX
1933 before going to its own
1941 is found in the user directory, it will be used.
1942 It is not recommended to hack the script under the \SpecialChar LyX
1943 library directory directly,
1944 since updating \SpecialChar LyX
1945 will override you modified script (the user directory will
1949 \begin_layout Standard
1950 Beside the support for the official Sweave in R, the
1954 package is also supported, which is an alternative tool to Sweave; the
1955 corresponding module is named