EVOLUTION-MANAGER

Edit File: RweaveLatex.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: R/LaTeX Driver for Sweave</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link rel="stylesheet" type="text/css" href="R.css" />
</head><body>

<table width="100%" summary="page for RweaveLatex {utils}"><tr><td>RweaveLatex {utils}</td><td style="text-align: right;">R Documentation</td></tr></table>

<h2>R/LaTeX Driver for Sweave</h2>

<h3>Description</h3>

A driver for <code><a href="Sweave.html">Sweave</a></code> that translates R code chunks in
LaTeX files by &ldquo;running them&rdquo;, i.e., <code><a href="../../base/html/parse.html">parse</a>()</code> and
<code><a href="../../base/html/eval.html">eval</a>()</code> each.

<h3>Usage</h3>

<pre>
RweaveLatex()

RweaveLatexSetup(file, syntax, output = NULL, quiet = FALSE,
 debug = FALSE, stylepath, ...)
</pre>

<h3>Arguments</h3>

<table summary="R argblock">
<tr valign="top"><td><code>file</code></td>
<td>
Name of Sweave source file. See the description of the
corresponding argument of <code><a href="Sweave.html">Sweave</a></code>.
</td></tr>
<tr valign="top"><td><code>syntax</code></td>
<td>
An object of class <code>SweaveSyntax</code>.
</td></tr>
<tr valign="top"><td><code>output</code></td>
<td>
Name of output file. The default is to remove extension
&lsquo;.nw&rsquo;, &lsquo;.Rnw&rsquo; or &lsquo;.Snw&rsquo; and to add
extension &lsquo;.tex&rsquo;. Any directory paths in
<code>file</code> are also removed such that the output is
created in the current working directory.
</td></tr>
<tr valign="top"><td><code>quiet</code></td>
<td>
If <code>TRUE</code> all progress messages are suppressed.
</td></tr>
<tr valign="top"><td><code>debug</code></td>
<td>
If <code>TRUE</code>, input and output of all code
chunks is copied to the console.
</td></tr>
<tr valign="top"><td><code>stylepath</code></td>
<td>
See &lsquo;Details&rsquo;.
</td></tr>
<tr valign="top"><td><code>...</code></td>
<td>
named values for the options listed in &lsquo;Supported
Options&rsquo;.
</td></tr>
</table>

<h3>Details</h3>

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
<code>RweaveLatex</code> driver. If <code>stylepath = TRUE</code>, a hard-coded
path to the file &lsquo;Sweave.sty&rsquo; in the R installation is set in
place of <code>Sweave</code>. The hard-coded path makes the LaTeX file less
portable, but avoids the problem of installing the current version of
&lsquo;Sweave.sty&rsquo; 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 <code>stylepath</code> is now taken from the environment
variable SWEAVE_STYLEPATH_DEFAULT, or is <code>FALSE</code> it that is
unset or empty. If set, it should be exactly <code>TRUE</code> or
<code>FALSE</code>: any other values are taken as <code>FALSE</code>.

The simplest way for frequent Sweave users to ensure that
&lsquo;Sweave.sty&rsquo; is in the TeX input path is to add
&lsquo;<var>R_HOME</var>/share/texmf&rsquo; as a &lsquo;texmf tree&rsquo; (&lsquo;root
directory&rsquo; in the parlance of the &lsquo;MiKTeX settings&rsquo; utility).

By default, &lsquo;Sweave.sty&rsquo; 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 <code>width=3</code> 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 &lsquo;.Rnw&rsquo; file
after the \begin{document} directive and changing the
<code>width</code> 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 <code>height</code> and
<code>width</code> options will determine both the runtime generated graphic
file sizes and the size of the graphics in your final document.

&lsquo;Sweave.sty&rsquo; 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 <code>inconsolata</code>, the font used by default for R help
pages.

The use of fancy quotes (see <code><a href="../../base/html/sQuote.html">sQuote</a></code>) can cause problems
when setting R output. Either set
<code><a href="../../base/html/options.html">options</a>(useFancyQuotes = FALSE)</code> or arrange that LaTeX is
aware of the encoding used (by a \usepackage[utf8]{inputenc}
declaration: Windows users of <code>Sweave</code> from <code>Rgui.exe</code>
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 <code>pdf</code> and <code>png</code> are <code>TRUE</code> both files will be
produced by <code>Sweave</code>, and their order in the
DeclareGraphicsExtensions list determines which will be used by
<code>pdflatex</code>.

<h3>Supported Options</h3>

<code>RweaveLatex</code> supports the following options for code chunks (the
values in parentheses show the default values). Character string
values should be quoted when passed from <code><a href="Sweave.html">Sweave</a></code> through
<code>...</code> but not when use in the header of a code chunk.

<dl>
<dt>engine:</dt><dd>character string (<code>"R"</code>). Only chunks with
<code>engine</code> equal to <code>"R"</code> or <code>"S"</code> are processed.
</dd>
<dt>echo:</dt><dd>logical (<code>TRUE</code>). Include R code in the output
file?
</dd>
<dt>keep.source:</dt><dd>logical (<code>TRUE</code>). When echoing, if
<code>TRUE</code> the original source is copied to the file. Otherwise,
deparsed source is echoed.
</dd> 
<dt>eval:</dt><dd>logical (<code>TRUE</code>). If <code>FALSE</code>, the code chunk
is not evaluated, and hence no text nor graphical output
produced.
</dd>
<dt>results:</dt><dd>character string (<code>"verbatim"</code>). If
<code>"verbatim"</code>, the output of R commands is included in the
verbatim-like Soutput environment. If <code>"tex"</code>, the
output is taken to be already proper LaTeX markup and included as
is. If <code>"hide"</code> then all output is completely suppressed
(but the code executed during the weave). Values can be abbreviated.
</dd>
<dt>print:</dt><dd>logical (<code>FALSE</code>). If <code>TRUE</code>, this forces
auto-printing of all expressions.
</dd>
<dt>term:</dt><dd>logical (<code>TRUE</code>). If <code>TRUE</code>, visibility of
values emulates an interactive R session: values of assignments
are not printed, values of single objects are printed. If
<code>FALSE</code>, output comes only from explicit <code><a href="../../base/html/print.html">print</a></code>
or similar statements.
</dd>
<dt>split:</dt><dd>logical (<code>FALSE</code>). If <code>TRUE</code>, text output
is written to separate files for each code chunk.
</dd>
<dt>strip.white:</dt><dd>character string (<code>"true"</code>). If
<code>"true"</code>, blank lines at the beginning and end of output are
removed. If <code>"all"</code>, then all blank lines are removed from
the output. If <code>"false"</code> then blank lines are retained.

A &lsquo;blank line&rsquo; 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.

</dd>
<dt>prefix:</dt><dd>logical (<code>TRUE</code>). If <code>TRUE</code> generated
filenames of figures and output all have the common prefix given
by the <code>prefix.string</code> option: otherwise only unlabelled
chunks use the prefix.
</dd>
<dt>prefix.string:</dt><dd>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.
</dd>
<dt>include:</dt><dd>logical (<code>TRUE</code>), indicating whether input
statements for text output (if <code>split = TRUE</code>) and
\includegraphics statements for figures should be
auto-generated. Use <code>include = FALSE</code> if the output should
appear in a different place than the code chunk (by placing the
input line manually).
</dd>
<dt>fig:</dt><dd>logical (<code>FALSE</code>), 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.
</dd>
<dt>eps:</dt><dd>logical (<code>FALSE</code>), indicating whether EPS figures
should be generated. Ignored if <code>fig = FALSE</code>.
</dd>
<dt>pdf:</dt><dd>logical (<code>TRUE</code>), indicating whether PDF figures
should be generated. Ignored if <code>fig = FALSE</code>.
</dd>
<dt>pdf.version, pdf.encoding, pdf.compress:</dt><dd>passed to
<code><a href="../../grDevices/html/pdf.html">pdf</a></code> to set the version, encoding and compression (or
not). Defaults taken from <code>pdf.options()</code>.
</dd>
<dt>png:</dt><dd>logical (<code>FALSE</code>), indicating whether PNG figures
should be generated. Ignored if <code>fig = FALSE</code>.
Only available in R &gt;= 2.13.0.
</dd>
<dt>jpeg:</dt><dd>logical (<code>FALSE</code>), indicating whether JPEG figures
should be generated. Ignored if <code>fig = FALSE</code>.
Only available in R &gt;= 2.13.0.
</dd>
<dt>grdevice:</dt><dd>character (<code>NULL</code>): see section
&lsquo;Custom Graphics Devices&rsquo;. Ignored if <code>fig = FALSE</code>.
Only available in R &gt;= 2.13.0.
</dd>
<dt>width:</dt><dd>numeric (6), width of figures in inches. See
&lsquo;Details&rsquo;.
</dd>
<dt>height:</dt><dd>numeric (6), height of figures in inches. See
&lsquo;Details&rsquo;.
</dd>
<dt>resolution:</dt><dd>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
<code>100</code> is a better choice for package vignettes.
</dd>
<dt>concordance:</dt><dd>logical (<code>FALSE</code>). 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.
</dd>
<dt>figs.only:</dt><dd>logical (<code>FALSE</code>).
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.
</dd>
</dl>

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.

<h3>Custom Graphics Devices</h3>

If option <code>grdevice</code> is supplied for a code chunk with both
<code>fig</code> and <code>eval</code> true, the following call is made

<pre> get(options$grdevice, envir = .GlobalEnv)(name=, width=,
 height=, options)
</pre>
which should open a graphics device. The chunk's code is then
evaluated and <code><a href="../../grDevices/html/dev.html">dev.off</a></code> is called. Normally a function of
the name given will have been defined earlier in the Sweave document, e.g.

<pre>&lt;&lt;results=hide&gt;&gt;=
my.Swd &lt;- function(name, width, height, ...)
 grDevices::png(filename = paste(name, "png", sep = "."),
 width = width, height = height, res = 100,
 units = "in", type = "quartz", bg = "transparent")
@
</pre>
Alternatively for R &gt;= 3.4.0, if the function exists in a package
(rather than the <code>.GlobalEnv</code>) it can be used by setting
<code>grdevice = "pkg::my.Swd"</code> (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 <code><a href="../../grDevices/html/dev.html">dev.off</a></code> can be provided as a function
with suffix <code>.off</code>, e.g. <code>my.Swd.off()</code> or
<code>pkg::my.Swd.off()</code>, respectively.

<h3>Hook Functions</h3>

Before each code chunk is evaluated, zero or more hook functions can
be executed. If <code>getOption("SweaveHooks")</code> is set, it is taken
to be a named list of hook functions. For each logical option of a
code chunk (<code>echo</code>, <code>print</code>, ...) a hook can be
specified, which is executed if and only if the respective option is
<code>TRUE</code>. Hooks must be named elements of the list returned by
<code>getOption("SweaveHooks")</code> and be functions taking no arguments.
E.g., if option <code>"SweaveHooks"</code> is defined as
<code>list(fig = foo)</code>, and <code>foo</code> 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 <code>clean</code> that removes all objects
in the workspace. Then all code chunks specified with
<code>clean = TRUE</code> would start operating on an empty workspace.

<h3>Author(s)</h3>

Friedrich Leisch and R-core

&lsquo;<a href="../doc/Sweave.pdf">Sweave User Manual</a>&rsquo;, a vignette in
the utils package.

<code><a href="Sweave.html">Sweave</a></code>, <code><a href="Rtangle.html">Rtangle</a></code>

<hr /><div style="text-align: center;">[Package utils version 3.6.0 <a href="00Index.html">Index</a>]</div>
</body></html>