R/LaTeX Driver for Sweave

Description

A driver for Sweave that translates R code chunks in LaTeX files by “running them”, i.e., parse() and eval() each.

Usage

RweaveLatex()

RweaveLatexSetup(file, syntax, output = NULL, quiet = FALSE,
                 debug = FALSE, stylepath, ...)

Arguments

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 as last line before the ‘⁠\begin{document}⁠’ statement. 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’ loads the ‘⁠graphicx⁠’ LaTeX package and sets the width of all included graphics to:
‘⁠\setkeys{Gin}{width=0.8\textwidth}⁠’.

This setting (defined in the ‘⁠graphicx⁠’ package) 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 ‘⁠[nofontenc]⁠’ option, which skips the default inclusion of ‘⁠\usepackage[T1]{fontenc}⁠’ for pdfTeX processing.

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 in non-UTF-8 locales (note that pdfTeX assumes UTF-8 by default since 2018). Either set options(useFancyQuotes = FALSE) or arrange that LaTeX is aware of the encoding used 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 used in the header of a code chunk.

engine:

character string ("R"). Only chunks with engine equal to "R" or "S" are processed.

echo:

logical (TRUE). Include R code in the output file?

keep.source:

logical (TRUE). When echoing, if TRUE the original source is copied to the file. Otherwise, deparsed source is echoed.

eval:

logical (TRUE). If FALSE, 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). If TRUE, this forces auto-printing of all expressions.

term:

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.

split:

logical (FALSE). If TRUE, 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). 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.

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 (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).

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 if fig = FALSE.

pdf:

logical (TRUE), indicating whether PDF figures should be generated. Ignored if fig = FALSE.

pdf.version, pdf.encoding, pdf.compress:

passed to pdf to set the version, encoding and compression (or not). Defaults taken from pdf.options().

png:

logical (FALSE), indicating whether PNG figures should be generated. Ignored if fig = FALSE. Only available in \R \ge 2.13.0.

jpeg:

logical (FALSE), indicating whether JPEG figures should be generated. Ignored if fig = FALSE. Only available in \R \ge 2.13.0.

grdevice:

character (NULL): see section ‘Custom Graphics Devices’. Ignored if fig = FALSE. Only available in \R \ge 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.

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.

Author(s)

Friedrich Leisch and R-core

See Also

‘Sweave User Manual’, a vignette in the utils package.

Sweave, Rtangle