RweaveLatex
R/LaTeX Driver for Sweave
A driver for Sweave
that translates R code chunks in
LaTeX files by “running them”, i.e., parse()
and
eval()
each.
- Keywords
- utilities
Usage
RweaveLatex()RweaveLatexSetup(file, syntax, output = NULL, quiet = FALSE,
debug = FALSE, stylepath, …)
Arguments
- file
Name of Sweave source file. See the description of the corresponding argument of
Sweave
.- syntax
An object of class
SweaveSyntax
.- output
Name of output file. The default is to remove extension
.nw
,.Rnw
or.Snw
and to add extension.tex
. Any directory paths infile
are also removed such that the output is created in the current working directory.- quiet
If
TRUE
all progress messages are suppressed.- debug
If
TRUE
, input and output of all code chunks is copied to the console.- stylepath
See ‘Details’.
- …
named values for the options listed in ‘Supported Options’.
Details
The LaTeX 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 LaTeX 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 LaTeX
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 LaTeX 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 LaTeX 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
.
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.
- engine:
character string (
"R"
). Only chunks withengine
equal to"R"
or"S"
are processed.- echo:
logical (
TRUE
). Include R code in the output file?- keep.source:
logical (
TRUE
). When echoing, ifkeep.source == TRUE
the original source is copied to the file. Otherwise, deparsed source is echoed.- eval:
logical (
TRUE
). IfFALSE
, the code chunk is not evaluated, and hence no text nor graphical output produced.- results:
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 LaTeX markup and included as is. If"hide"
then all output is completely suppressed (but the code executed during the weave). Values can be abbreviated.- print:
logical (
FALSE
). IfTRUE
, this forces auto-printing of all expressions.- term:
logical (
TRUE
). IfTRUE
, visibility of values emulates an interactive R session: values of assignments are not printed, values of single objects are printed. IfFALSE
, output comes only from explicitprint
or similar statements.- split:
logical (
FALSE
). IfTRUE
, text output is written to separate files for each code chunk.- strip.white:
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.
- prefix:
logical (
TRUE
). IfTRUE
generated filenames of figures and output all have the common prefix given by theprefix.string
option: otherwise only unlabelled chunks use the prefix.- prefix.string:
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.
- include:
logical (
TRUE
), indicating whether input statements for text output (ifsplit = TRUE
) and \includegraphics statements for figures should be auto-generated. Useinclude = FALSE
if the output should appear in a different place than the code chunk (by placing the input line manually).- fig:
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.- eps:
logical (
FALSE
), indicating whether EPS figures should be generated. Ignored iffig = FALSE
.- pdf:
logical (
TRUE
), indicating whether PDF figures should be generated. Ignored iffig = FALSE
.- pdf.version, pdf.encoding, pdf.compress:
passed to
pdf
to set the version, encoding and compression (or not). Defaults taken frompdf.options()
.- png:
logical (
FALSE
), indicating whether PNG figures should be generated. Ignored iffig = FALSE
. Only available in R >= 2.13.0.- jpeg:
logical (
FALSE
), indicating whether JPEG figures should be generated. Ignored iffig = FALSE
. Only available in R >= 2.13.0.- grdevice:
character (
NULL
): see section ‘Custom Graphics Devices’. Ignored iffig = FALSE
. Only available in R >= 2.13.0.- width:
numeric (6), width of figures in inches. See ‘Details’.
- height:
numeric (6), height of figures in inches. See ‘Details’.
- resolution:
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.- concordance:
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.- figs.only:
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.
Custom Graphics Devices
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.
Hook Functions
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.
See Also
‘Sweave User Manual’, a vignette in the utils package.