A driver for Sweave that translates R code chunks in
files by “running them”, i.e., parse() and
eval() each.
RweaveLatex()RweaveLatexSetup(file, syntax, output = NULL, quiet = FALSE,
debug = FALSE, stylepath, …)
Name of Sweave source file. See the description of the
corresponding argument of Sweave.
An object of class SweaveSyntax.
Name of output file. The default is to remove extension
.nw, .Rnw or .Snw and to add
extension .tex. Any directory paths in
file are also removed such that the output is
created in the current working directory.
If TRUE all progress messages are suppressed.
If TRUE, input and output of all code
chunks is copied to the console.
See ‘Details’.
named values for the options listed in ‘Supported Options’.
RweaveLatex supports the following options for code chunks (the
values in parentheses show the default values). Character string
values should be quoted when passed from Sweave through
… but not when use in the header of a code chunk.
character string ("R"). Only chunks with
engine equal to "R" or "S" are processed.
logical (TRUE). Include R code in the output
file?
logical (TRUE). When echoing, if
TRUE the original source is copied to the file. Otherwise,
deparsed source is echoed.
logical (TRUE). If FALSE, the code chunk
is not evaluated, and hence no text nor graphical output
produced.
character string ("verbatim"). If
"verbatim", the output of R commands is included in the
verbatim-like Soutput environment. If "tex", the
output is taken to be already proper markup and included as
is. If "hide" then all output is completely suppressed
(but the code executed during the weave). Values can be abbreviated.
logical (FALSE). If TRUE, this forces
auto-printing of all expressions.
logical (TRUE). If TRUE, visibility of
values emulates an interactive R session: values of assignments
are not printed, values of single objects are printed. If
FALSE, output comes only from explicit print
or similar statements.
logical (FALSE). If TRUE, text output
is written to separate files for each code chunk.
character string ("true"). If
"true", blank lines at the beginning and end of output are
removed. If "all", then all blank lines are removed from
the output. If "false" then blank lines are retained.
A ‘blank line’ is one that is empty or includes only whitespace (spaces and tabs).
Note that blank lines in a code chunk will usually produce a prompt string rather than a blank line on output.
logical (TRUE). If TRUE generated
filenames of figures and output all have the common prefix given
by the prefix.string option: otherwise only unlabelled
chunks use the prefix.
a character string, default is the name of the source file (without extension). Note that this is used as part of filenames, so needs to be portable.
logical (TRUE), indicating whether input
statements for text output (if split = TRUE) and
\includegraphics statements for figures should be
auto-generated. Use include = FALSE if the output should
appear in a different place than the code chunk (by placing the
input line manually).
logical (FALSE), indicating whether the code
chunk produces graphical output. Note that only one figure per
code chunk can be processed this way. The labels for figure
chunks are used as part of the file names, so should preferably be
alphanumeric.
logical (FALSE), indicating whether EPS figures
should be generated. Ignored if fig = FALSE.
logical (TRUE), indicating whether PDF figures
should be generated. Ignored if fig = FALSE.
passed to
pdf to set the version, encoding and compression (or
not). Defaults taken from pdf.options().
logical (FALSE), indicating whether PNG figures
should be generated. Ignored if fig = FALSE.
Only available in \(\R \ge 2.13.0\).
logical (FALSE), indicating whether JPEG figures
should be generated. Ignored if fig = FALSE.
Only available in \(\R \ge 2.13.0\).
character (NULL): see section
‘Custom Graphics Devices’. Ignored if fig = FALSE.
Only available in \(\R \ge 2.13.0\).
numeric (6), width of figures in inches. See ‘Details’.
numeric (6), height of figures in inches. See ‘Details’.
numeric (300), resolution in pixels per inch:
used for PNG and JPEG graphics. Note that the default is a fairly
high value, appropriate for high-quality plots. Something like
100 is a better choice for package vignettes.
logical (FALSE). Write a concordance
file to link the input line numbers to the output line numbers.
This is an experimental feature; see the source code for the
output format, which is subject to change in future releases.
logical (FALSE).
By default each figure chunk is run once, then re-run for each
selected type of graphics. That will open a default graphics
device for the first figure chunk and use that device for the first
evaluation of all subsequent chunks. If this option is true, the
figure chunk is run only for each selected type of graphics, for
which a new graphics device is opened and then closed.
In addition, users can specify further options, either in the header of an individual code section or in a \SweaveOpts{} line in the document. For unknown options, their type is set at first use.
If option grdevice is supplied for a code chunk with both
fig and eval true, the following call is made
get(options$grdevice, envir = .GlobalEnv)(name=, width=,
height=, options)
which should open a graphics device. The chunk's code is then
evaluated and dev.off is called. Normally a function of
the name given will have been defined earlier in the Sweave document, e.g.
<<results=hide>>=
my.Swd <- function(name, width, height, ...)
grDevices::png(filename = paste(name, "png", sep = "."),
width = width, height = height, res = 100,
units = "in", type = "quartz", bg = "transparent")
@
Alternatively for R >= 3.4.0, if the function exists in a package
(rather than the .GlobalEnv) it can be used by setting
grdevice = "pkg::my.Swd" (or with ::: instead of
:: if the function is not exported).
Currently only one custom device can be used for each chunk, but different devices can be used for different chunks.
A replacement for dev.off can be provided as a function
with suffix .off, e.g.my.Swd.off() or
pkg::my.Swd.off(), respectively.
Before each code chunk is evaluated, zero or more hook functions can
be executed. If getOption("SweaveHooks") is set, it is taken
to be a named list of hook functions. For each logical option of a
code chunk (echo, print, …) a hook can be
specified, which is executed if and only if the respective option is
TRUE. Hooks must be named elements of the list returned by
getOption("SweaveHooks") and be functions taking no arguments.
E.g., if option "SweaveHooks" is defined as
list(fig = foo), and foo is a function, then it would be
executed before the code in each figure chunk. This is especially
useful to set defaults for the graphical parameters in a series of
figure chunks.
Note that the user is free to define new Sweave logical options and
associate arbitrary hooks with them. E.g., one could define a hook
function for a new option called clean that removes all objects
in the workspace. Then all code chunks specified with
clean = TRUE would start operating on an empty workspace.
The file generated needs to contain the line
\usepackage{Sweave}, and if this is not present in the
Sweave source file (possibly in a comment), it is inserted by the
RweaveLatex driver. If stylepath = TRUE, a hard-coded
path to the file Sweave.sty in the R installation is set in
place of Sweave. The hard-coded path makes the file less
portable, but avoids the problem of installing the current version of
Sweave.sty to some place in your TeX input path. However, TeX
may not be able to process the hard-coded path if it contains spaces
(as it often will under Windows) or TeX special characters.
The default for stylepath is now taken from the environment
variable SWEAVE_STYLEPATH_DEFAULT, or is FALSE it that is
unset or empty. If set, it should be exactly TRUE or
FALSE: any other values are taken as FALSE.
The simplest way for frequent Sweave users to ensure that
Sweave.sty is in the TeX input path is to add
R_HOME/share/texmf as a ‘texmf tree’ (‘root
directory’ in the parlance of the ‘MiKTeX settings’ utility).
By default, Sweave.sty sets the width of all included graphics to:
\setkeys{Gin}{width=0.8\textwidth}.
This setting affects the width size option passed to the \includegraphics{} directive for each plot file and in turn impacts the scaling of your plot files as they will appear in your final document.
Thus, for example, you may set width=3 in your figure chunk and
the generated graphics files will be set to 3 inches in
width. However, the width of your graphic in your final document will
be set to 0.8\textwidth and the height dimension will be
scaled accordingly. Fonts and symbols will be similarly scaled in the
final document.
You can adjust the default value by including the
\setkeys{Gin}{width=...} directive in your .Rnw file
after the \begin{document} directive and changing the
width option value as you prefer, using standard
measurement values.
If you wish to override this default behavior entirely, you can add a
\usepackage[nogin]{Sweave} directive in your preamble. In this
case, no size/scaling options will be passed to the
\includegraphics{} directive and the height and
width options will determine both the runtime generated graphic
file sizes and the size of the graphics in your final document.
Sweave.sty also supports the [noae] option, which
suppresses the use of the ae package, the use of which may
interfere with certain encoding and typeface selections. If you have
problems in the rendering of certain character sets, try this option.
It also supports the [inconsolata] option, to render monospaced
text in inconsolata, the font used by default for R help
pages.
The use of fancy quotes (see sQuote) can cause problems
when setting R output. Either set
options(useFancyQuotes = FALSE) or arrange that is
aware of the encoding used (by a \usepackage[utf8]{inputenc}
declaration: Windows users of Sweave from Rgui.exe
will need to replace utf8 by cp1252 or similar) and
ensure that typewriter fonts containing directional quotes are used.
Some graphics drivers do not include .png or .jpg
in the list of known extensions. To enable them, add something like
\DeclareGraphicsExtensions{.png,.pdf,.jpg} to the preamble of
your document or check the behavior of your graphics driver. When
both pdf and png are TRUE both files will be
produced by Sweave, and their order in the
DeclareGraphicsExtensions list determines which will be used by
pdflatex.
‘Sweave User Manual’, a vignette in the utils package.