1 #LyX 2.0 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
30 \font_default_family default
31 \use_non_tex_fonts false
38 \default_output_format default
40 \bibtex_command default
41 \index_command default
42 \paperfontsize default
54 \paperorientation portrait
67 \paragraph_separation indent
68 \paragraph_indentation default
69 \quotes_language english
72 \paperpagestyle default
73 \tracking_changes false
82 \begin_layout Standard
86 \begin_layout Plain Layout
90 SweaveOpts{prefix=TRUE,prefix.string=sweave-prefix,keep.source=FALSE}
98 \begin_layout Standard
102 \begin_layout Plain Layout
106 maxwidth was defined in the preamble; see document settings
109 \begin_layout Plain Layout
124 Using Sweave with LyX
132 \begin_layout Plain Layout
133 Department of Statistics, Iowa State University.
135 \begin_inset CommandInset href
137 name "xie@yihui.name"
138 target "xie@yihui.name"
152 \begin_layout Plain Layout
165 \begin_layout Plain Layout
177 \begin_layout Standard
178 Sweave is a tool in the R language (
179 \begin_inset Flex URL
182 \begin_layout Plain Layout
184 http://www.r-project.org
189 ) for dynamic report generation using the ideas of literate programming.
190 R code can be mixed into a LaTeX document, and will be executed in R when
191 the document is compiled; the results are written into the TeX output.
194 \begin_layout Standard
195 Since LyX 2.0, Sweave can be used out of the box with any document class
200 module, which means we no longer need to modify the
204 file manually or add special layouts such as
206 literate-article.layout
217 module to a LyX document from
219 Document\SpecialChar \menuseparator
220 Settings\SpecialChar \menuseparator
224 In this manual, we demonstrate some common features of Sweave and explain
225 how the module works.
226 A PDF version of this manual can be found at
227 \begin_inset Flex URL
230 \begin_layout Plain Layout
232 https://github.com/downloads/yihui/lyx/sweave.pdf
240 \begin_layout Section
244 \begin_layout Standard
249 module depends on the executable
253 , so it has to be in the
257 variable of the system.
258 It is usually not a problem for Linux and Mac OS users, but may be confusing
259 to Windows users; if you do not understand what is
263 under Windows, you may use the R script
268 \begin_inset Flex URL
271 \begin_layout Plain Layout
273 https://github.com/yihui/lyx
278 to change it automatically (we recommend you to learn
285 \begin_layout Standard
298 module will be unavailable.
299 It is recommended to use the latest version of R, since Sweave is still
301 Another dependency is introduced by the LaTeX style file
305 which is shipped with R under this path (it is not on CTAN):
308 \begin_layout Standard
312 \begin_layout Plain Layout
314 <<sweave-sty,eval=FALSE>>=
317 \begin_layout Plain Layout
319 file.path(R.home('share'), 'texmf', 'tex', 'latex')
322 \begin_layout Plain Layout
332 \begin_layout Standard
333 MikTeX users may add the texmf directory to the list of root directories
334 in MikTeX through MikTeX settings.
356 , it will directly copy from R, so the Sweave module works even if you do
357 not know where is this style file.
360 \begin_layout Section
364 \begin_layout Standard
365 Before we write an Sweave document, we can set some Sweave options; the
372 in Sweave and it can be inserted in a LyX document by
374 Insert\SpecialChar \menuseparator
375 Custom Insets\SpecialChar \menuseparator
378 , or just use TeX code to write it (
380 Insert\SpecialChar \menuseparator
384 For example, we can set a global option
388 in the beginning of a document to suppress all R code (by default, both
389 R code and its output will show up in the LaTeX document).
393 \begin_layout Standard
394 To write R code in LyX, you can first switch to the
398 environment in the layout styles list (droplist in the top-left corner
399 in the toolbar), or you can simply open a TeX code environment and write
400 Sweave code chunks in it.
401 The latter approach is recommended since it is more stable.
404 \begin_layout Standard
405 Some R options can be useful to the Sweave output as well, e.g.
415 The former option can adjust the width of the output, and the latter can
416 avoid a common problem with quotes.
417 Users are encouraged to read the Sweave manual in R for more details.
420 \begin_layout Standard
424 \begin_layout Plain Layout
426 <<setup, keep.source=TRUE>>=
429 \begin_layout Plain Layout
431 ## the option 'digits' can set the (approximate) number of digits
434 \begin_layout Plain Layout
436 options(width = 70, useFancyQuotes = FALSE, digits = 4)
439 \begin_layout Plain Layout
444 \begin_layout Plain Layout
446 <<sweave-manual, eval=FALSE, keep.source=TRUE>>=
449 \begin_layout Plain Layout
451 ## view the Sweave vignette (requires R >= 2.13.0)
454 \begin_layout Plain Layout
456 vignette("Sweave", package = "utils")
459 \begin_layout Plain Layout
469 \begin_layout Standard
470 A simple example that will run in any S engine:
473 \begin_layout Standard
477 \begin_layout Plain Layout
479 <<print-integers, keep.source=TRUE>>=
482 \begin_layout Plain Layout
484 ## the integers from 1 to 10 are
487 \begin_layout Plain Layout
492 \begin_layout Plain Layout
497 \begin_layout Plain Layout
499 <<hide-results, results=hide>>=
502 \begin_layout Plain Layout
504 ## intentionally hide the output by setting results=hide
507 \begin_layout Plain Layout
512 \begin_layout Plain Layout
522 \begin_layout Standard
523 We can also emulate a simple calculator:
526 \begin_layout Standard
530 \begin_layout Plain Layout
535 \begin_layout Plain Layout
540 \begin_layout Plain Layout
545 \begin_layout Plain Layout
555 \begin_layout Standard
556 Now we look at some Gaussian data:
559 \begin_layout Standard
563 \begin_layout Plain Layout
568 \begin_layout Plain Layout
570 set.seed(123) # for reproducibility
573 \begin_layout Plain Layout
578 \begin_layout Plain Layout
583 \begin_layout Plain Layout
588 \begin_layout Plain Layout
598 \begin_layout Standard
599 Note that we can easily integrate some numbers into standard text; this
600 is done with the command
606 , and the corresponding LyX menu is
608 Insert\SpecialChar \menuseparator
609 Custom Insets\SpecialChar \menuseparator
612 , or alternatively just use TeX code.
613 For example, the third element of the vector
618 \begin_inset Flex S/R expression
621 \begin_layout Plain Layout
634 \begin_inset Formula $p$
637 -value of the test is
638 \begin_inset Flex S/R expression
641 \begin_layout Plain Layout
643 format.pval(t1$p.value)
649 You can round these numbers using functions like
657 \begin_layout Standard
667 Now we look at a summary of the
688 \begin_layout Standard
692 \begin_layout Plain Layout
697 \begin_layout Plain Layout
702 \begin_layout Plain Layout
712 \begin_layout Standard
713 \begin_inset Float table
718 \begin_layout Plain Layout
721 \begin_layout Plain Layout
722 Quantiles of the first four variables in the
727 \begin_inset CommandInset label
729 name "tab:xtable-demo"
741 \begin_layout Plain Layout
745 \begin_layout Plain Layout
752 \begin_layout Plain Layout
754 <<xtable-demo,results=tex,echo=FALSE>>=
757 \begin_layout Plain Layout
759 if (require('xtable')) {
762 \begin_layout Plain Layout
764 print(xtable(sapply(iris[,-5], quantile)), floating=FALSE)
767 \begin_layout Plain Layout
769 } else cat('the xtable package is not available! please install.packages("xtable"
773 \begin_layout Plain Layout
778 \begin_layout Plain Layout
795 \begin_layout Standard
796 Usually people do not like such
797 \begin_inset Quotes eld
801 \begin_inset Quotes erd
804 output, and we can polish these messy numbers with the
810 \begin_inset CommandInset ref
812 reference "tab:xtable-demo"
816 is an example demonstrating how to use the
820 package with Sweave; note the chunk option
824 makes sure that the R output is written out as raw LaTeX code instead of
825 being wrapped in a special environment (
832 \begin_layout Standard
834 \begin_inset CommandInset ref
836 reference "fig:iris-pairs"
841 \begin_inset CommandInset ref
843 reference "fig:iris-boxplots"
847 are two simple examples of producing graphics output with Sweave.
850 \begin_layout Standard
851 \begin_inset Float figure
856 \begin_layout Plain Layout
860 \begin_layout Plain Layout
867 \begin_layout Plain Layout
869 <<iris-pairs,fig=TRUE,width=4.5,height=4.5>>=
872 \begin_layout Plain Layout
874 pairs(iris, col = iris$Species)
877 \begin_layout Plain Layout
882 \begin_layout Plain Layout
894 \begin_layout Plain Layout
897 \begin_layout Plain Layout
898 Scatter plot matrix of the
903 \begin_inset CommandInset label
905 name "fig:iris-pairs"
922 \begin_layout Standard
923 \begin_inset Float figure
928 \begin_layout Plain Layout
932 \begin_layout Plain Layout
939 \begin_layout Plain Layout
941 <<iris-boxplots,fig=TRUE,width=7,height=2,keep.source=F>>=
944 \begin_layout Plain Layout
946 par(mar=c(4,5,.1,.3), las=1)
949 \begin_layout Plain Layout
951 boxplot(Sepal.Length~Species,data=iris,horizontal=TRUE,xlab='Sepal.Length')
954 \begin_layout Plain Layout
959 \begin_layout Plain Layout
971 \begin_layout Plain Layout
974 \begin_layout Plain Layout
975 Boxplots of sepal length grouped by species.
976 \begin_inset CommandInset label
978 name "fig:iris-boxplots"
995 \begin_layout Standard
996 We can also export all the R code in an Sweave document as a single R script
999 File\SpecialChar \menuseparator
1000 Export\SpecialChar \menuseparator
1003 ), which is done via
1010 \begin_layout Section
1018 \begin_layout Standard
1023 module declares that a LyX document contains literate programming components
1024 with R, so that LyX will handle such documents according to the specific
1025 converters (see the Customization manual).
1034 converter, which essentially consists of an R script
1043 This script takes an
1047 document from LyX and call Sweave to process it to a TeX document, then
1048 LyX takes care of the rest of work.
1051 \begin_layout Standard
1052 The converter from the
1056 format to LaTeX is a call to R via the command line as:
1059 \begin_layout Standard
1063 \begin_layout Plain Layout
1070 \begin_layout Plain Layout
1072 Rscript --no-save --no-restore $$s/scripts/lyxsweave.R $$p$$i $$p$$o $$e
1076 \begin_layout Plain Layout
1088 \begin_layout Standard
1089 The LyX library directory
1093 can be found from the menu
1095 Help\SpecialChar \menuseparator
1099 All the rest of options passed to R are explained in the R script, and
1100 the LyX Customization manual also has detailed explanations about
1117 General users do not need to know clearly what they mean, but here we need
1118 to explain a few issues in the R code:
1121 \begin_layout Enumerate
1122 the encoding string of the LyX document is passed to R as an command line
1123 option; possible values are
1132 The encoding is used for R to read the
1139 \begin_layout Enumerate
1140 the R code chunks in the Sweave document are executed under the directory
1141 of the LyX document (if you are not sure, put
1145 in a code chunk to see what is the current working directory).
1146 In this case, you can put data files under the same directory and use relative
1147 paths in R to guarantee reproducibility, i.e.
1148 we do not need to write hard-coded paths which may not exist in other systems.
1151 \begin_layout Enumerate
1152 if LaTeX cannot find
1156 , this R script will copy it to the temporary directory automatically where
1157 the LaTeX compilation takes place.
1160 \begin_layout Enumerate
1161 Sweave will use the filename of the Rnw file as the prefix string for the
1162 graphics output by default; one known issue (
1163 \begin_inset CommandInset href
1166 target "http://www.lyx.org/trac/ticket/7551"
1170 ) is that if the filename (without extension) contains dots, LaTeX can fail
1171 to deal with such files in
1178 Therefore, we have set the default value of the prefix to be the filename
1179 with all the dots being replaced by
1180 \begin_inset Quotes eld
1184 \begin_inset Quotes erd
1188 We can also solve this problem in Sweave directly: set the Sweave option
1193 to be a character string without dots, and this option will override the
1197 \begin_layout Standard
1198 We have pre-specified an option
1202 for the Sweave package.
1203 This option stops Sweave from loading these two packages:
1206 \begin_layout Standard
1210 \begin_layout Plain Layout
1217 \begin_layout Plain Layout
1221 RequirePackage[T1]{fontenc}
1224 \begin_layout Plain Layout
1231 \begin_layout Plain Layout
1243 \begin_layout Standard
1244 LyX can deal with the font encoding by default, so there is no need to ask
1245 Sweave to do this (furthermore, this may bring clashes of package options);
1246 besides, the users can load the
1250 package by themselves in the preamble if needed.
1253 \begin_layout Section
1257 \begin_layout Standard
1258 Since LyX 2.0, we can see the detailed information during compilation via
1261 View\SpecialChar \menuseparator
1265 This is extremely helpful for trouble shooting -- the process of R will
1266 be shown in the message panel, and we will be able to know which chunk
1267 goes wrong in cases of errors.
1268 For example, when you compile this document, you can see messages like
1272 \begin_layout Standard
1276 \begin_layout Plain Layout
1283 \begin_layout Plain Layout
1285 17:58:47.868: Processing code chunks with options ...
1288 \begin_layout Plain Layout
1290 17:58:47.885: 1 : echo keep.source term verbatim (label=setup)
1293 \begin_layout Plain Layout
1295 17:58:47.889: 2 : echo keep.source (label=sweave-manual)
1298 \begin_layout Plain Layout
1300 17:58:47.908: 3 : echo keep.source term verbatim (label=print-integers)
1303 \begin_layout Plain Layout
1308 \begin_layout Plain Layout
1310 17:58:47.941: Loading required package: xtable
1313 \begin_layout Plain Layout
1315 17:58:47.976: 9 : echo term verbatim pdf (label=iris-pairs)
1318 \begin_layout Plain Layout
1323 \begin_layout Plain Layout
1325 17:58:48.116: You can now run (pdf)latex on 'sweave.tex'
1328 \begin_layout Plain Layout
1340 \begin_layout Standard
1346 If any chunk causes an error in R, you will see the error message here
1350 \begin_layout Section
1354 \begin_layout Standard
1355 The homepage of Sweave is at
1356 \begin_inset Flex URL
1359 \begin_layout Plain Layout
1361 http://www.stat.uni-muenchen.de/~leisch/Sweave/
1367 The CRAN task view on
1368 \begin_inset Quotes eld
1371 Reproducible Research
1372 \begin_inset Quotes erd
1375 has a list of Sweave-related packages which can be potentially useful;
1377 \begin_inset Flex URL
1380 \begin_layout Plain Layout
1382 http://cran.r-project.org/web/views/ReproducibleResearch.html
1388 Questions about LyX and Sweave can be posted to the LyX mailing list (
1389 \begin_inset Flex URL
1392 \begin_layout Plain Layout
1394 http://www.lyx.org/MailingLists
1400 More LyX examples are provided at
1401 \begin_inset Flex URL
1404 \begin_layout Plain Layout
1406 https://github.com/yihui/lyx
1414 \begin_layout Section
1418 \begin_layout Subsection
1419 How to use Sweave with beamer?
1422 \begin_layout Standard
1423 You will end up with LaTeX errors if you use Sweave in beamer slides in
1424 LyX; the reason is the beamer frame that contains verbatim R code and output
1430 However, currently there is no straightforward way to do this.
1431 One way is to write raw TeX code, and the other is to use the
1433 beamer-fragile.module
1436 \begin_inset CommandInset href
1439 target "http://www.lyx.org/trac/ticket/7273"
1443 (put this file under the
1447 directory of LyX user directory and reconfigure LyX).
1448 After including this module in your document, you should be able to use
1451 Insert\SpecialChar \menuseparator
1452 Custom Insets\SpecialChar \menuseparator
1455 , which is essentially
1459 begin{frame}[fragile]
1464 \begin_layout Subsection
1465 Can I define my own R script to compile the Rnw document?
1468 \begin_layout Standard
1470 First you need to understand how the R script
1474 /scripts/lyxsweave.R
1476 works, which was introduced previously, and we recommend you to read the
1477 R source code as well (on how R takes the paths and uses
1481 to handle the Rnw document).
1482 Then you put your customized
1496 Help\SpecialChar \menuseparator
1500 Note LyX will check the
1504 before going to its own
1512 is found in the user directory, it will be used.
1513 It is not recommended to hack the script under the LyX library directory
1514 directly, since updating LyX will override you modified script (the user
1515 directory will not be affected).
1518 \begin_layout Standard
1519 Beside the support for the official Sweave in R, we have a few customized
1520 R scripts to unofficially support other R packages under
1521 \begin_inset Flex URL
1524 \begin_layout Plain Layout
1526 https://github.com/yihui/lyx
1540 The former supports cache and tikz graphics in R, and the latter is an
1541 alternative literate programming engine to Sweave which has even more features.