Description Details Options That Affect Package Behavior Font Size Calculations Unicode Author(s) References See Also
The tikzDevice package implements the tikz
ouput device which
generates R graphics in a LaTeX friendly format. LaTeX handles the
typesetting of all text in graphics generated by tikz
. This allows for
seamless integration between these graphics and documents that are also being
typeset by LaTeX. Using LaTeX to generate graph text also means that
LaTeX mathematics can be typeset directly into labels and
annotations
Package: | tikzDevice |
Type: | Package |
Version: | 0.6.3 |
Date: | 2011-11-13 |
License: | GPL 2 or greater |
LazyLoad: | yes |
The tikzDevice package is currently influenced by a number of global
options that may be set in R scripts, from the R console or in a
.Rprofile
file. All of the options can be set by using
options(<option> = <value>)
. These options allow for the use of
custom documentclass
declarations, LaTeX packages, and typesetting
engines (e.g. XeLaTeX or LuaLaTeX). The defaults , if are any for a given
option, are shown below the description. The global options are:
tikzDefaultEngine
Specifies which typesetting engine functions in the tikzDevice package
will prefer. Current possible values are pdftex
, xetex
or
luatex
. Respectively, these values trigger the use of the
pdflatex
, xelatex
and lualatex
compilers.
tikzLatex
Specifies the location of the LaTeX compiler to be used by
tikzDevice. Setting this option may help the package locate a
missing compiler. The default is searched for when the package is loaded,
otherwise it can be set manually. This option may be set as follows:
options( tikzLatex = '/path/to/latex/compiler' )
.
tikzXelatex
Functions similar to tikzLatex
, except this option specifies the
location of the XeLaTeX compiler.
tikzLualatex
Functions similar to tikzLatex
, except this option specifies the
location of the LuaLaTeX compiler.
tikzMetricsDictionary
When using the graphics device provided by tikzDevice, you may
notice that R appears to “lag" or “hang" when commands such as
plot()
are executed. This is because the device must query the
LaTeX compiler for string widths and font metrics. For a normal plot,
this may happen dozens or hundreds of times- hence R becomes
unresponsive for a while. The good news is that the tikz
code is
designed to cache the results of these computations so they need only be
performed once for each string or character. By default, these values are
stored in a temporary cache file which is deleted when R is shut down.
A location for a permanent cache file may be specified by setting the
value of tikzMetricsDictionary
in .Rprofile
with
options(tikzMetricsDictionary = '/path/to/dictionary/location')
.
tikzDocumentDeclaration
A string. The LaTeX documentclass declaration used in output files when
standAlone == TRUE
. tikzDocumentDeclaration
also influences
the calculation of font metrics. The default value is:
options(tikzDocumentDeclaration = "\\documentclass[10pt]{article}")
tikzLatexPackages
A character vector. These are the packages which are included when using
the pdftex
engine and tikz
is used with the the
standAlone
option as well as when font metrics are calculated.
tikzXelatexPackages
This option works like tikzLatexPackages
, except is is used when
the xetex
engine is in use.
tikzLualatexPackages
This option works like tikzXelatexPackages
, except is is used when
the luatex
engine is in use.
tikzFooter
A character vector. The footer to be used only when
standAlone==TRUE
.
tikzMetricPackages
A character vector. These are the packages which are additionally loaded when doing font metric calculations. As you see below, the font encoding is set to Type 1. This is very important so that character codes of LaTeX and R match up. The default value is:
options(tikzMetricPackages = c( "\\usepackage[utf8]{inputenc}", "\\usepackage[T1]{fontenc}", "\\usetikzlibrary{calc}" ))
tikzUnicodeMetricPackages
This vector is used when font metric calculations are performed using the
xetex
or luatex
engines. It should have the same contents
as tikzMetricPackages
with the addition of the fontspec
and
xunicode
packages.
tikzSanitizeCharacters
A character vector of special latex characters to replace. These values
should correspond to the replacement values from the
tikzReplacementCharacters
option. See
sanitizeTexString
for more details.
tikzReplacementCharacters
A character vector of replacements for special latex characters. These
values should correspond to the values from the
tikzSanitizeCharacters
option.
tikzRasterResolution
When tikz
is requested to add a raster to a graphic, the
raster is written to a PNG file which is then included into the LaTeX
code. This option controls the resolution (dpi) at which the PNG files
are created.
tikzPdftexWarnUTF
A TRUE/FALSE
value that controls whether warnings are printed if
Unicode characters are sent to a device using the pdftex
engine.
Default values for all options may be viewed or restored using the
setTikzDefaults
function.
The overarching goal of the tikzDevice
is to provide seamless
integration between text in R graphics and the text of LaTeX documents
that contain those graphics. In order to achieve this integration the device
must translate font sizes specified in R to corresponding font sizes in
LaTeX.
A major consideration is that font sizes in LaTeX are controlled by a “base
font size” that is specified at the beginning of the document; typically
10pt. Furthermore, LaTeX typically provides only a finite number of sizes
for each font. Fortunately, the TikZ graphics system allows text to be
resized using a scaling factor. The tikzDevice
calculates this
scaling factor using three inputs:
The “base font size” specified when the graphics device is created.
The “character expansion factor” parameter, specified using the
cex
argument to functions such as par
.
The “font size” parameter, specified using the ps
argument
to functions such as par
or the fontsize
argument to
functions such as gpar
.
The tricky bit is the specification of the “base font size”. By default
the tikzDevice
will attempt to determine this parameter by scaning the
value of options( "tikzDocumentDeclaration" )
using the regular
expression \d+[pt]
. For the default header of:
1 2 | \documentclass[10pt]{article}
|
This regular expression will return 10 as the base pointsize to be used by the
device. If the regular expression fails to produce a match, the value of the
pointsize
argument to the tikz
function will be used.
Using tikzDevice functions on strings containing Unicode (multibyte)
characters requires special consideration. The primary reason for this is
that pdftex
, the typesetting engine most commonly used to compile
LaTeX documents, has no native support for Unicode. Recently, two new engines
have become widely available that do support Unicode natively. These engines
are:
The xetex
engine which has been a part of standard TeX
distributions since TeX Live 2007 and MiKTeX 2.7.
The luatex
engine which is a direct sucessor to pdftex
.
LuaTeX is still considered ‘beta’ software (as of spring 2012) but is very
stable and has been included in standard TeX distributions since TeX Live
2008 and MiKTeX 2.9.
As of Version 0.6.0, the tikzDevice package includes support for the
xetex
engine provided a recent version of TeX Live or MiKTeX is
available. Support for the luatex
engine was added in Version 0.7.0.
The tikzDevice defaults to using the pdftex
engine, but this may be
changed by setting an option: option(tikzDefaultEngine = 'xetex')
.
When working with text that contains Unicode characters, we strongly
reccomend switching to the xetex
or luatex
engines. The package
will produce warning messages when multibyte characters are sent to the
pdftex
engine. Users who find these warnings annoying may disable them
by setting options(tikzPdftexWarnUTF = FALSE)
as it is possible to
send Unicode information to the pdftex
engine with the following
caveats:
The task of determining the proper mix of LaTeX packages required to
supply glyphs for Unicode characters is left entirely up to the user.
options(tikzLatexPackages)
may need to be customized in order to get
proper behavior.
The getLatexCharMetrics
function will always return 0
for ascent, descent and width when passed a character code outside the
range 32–127 when using the pdftex
engine.
When using the xetex
or luatex
engines, Unicode support is
enabled by loading the LaTeX packages fontspec
and xunicode
.
Using this setup, support for Unicode characters should be limited only by
the fonts used in the document. The font selection may be adjusted using
options(tikzXelatexPackages)
.
Cameron Bracken: cameron.bracken@gmail.com
Charlie Sharpsteen: source@sharpsteen.net
Submit bug reports to: tikzdevice-bugs@lists.r-forge.r-project.org
The TikZ and PGF Packages: Manual for version 2.00
http://sourceforge.net/projects/pgf
Till Tanatu, February 20, 2008
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.