tikzDevice-package: Support for native LaTeX output of R graphics

In Sharpie/RTikZDevice: R Graphics Output in LaTeX Format

Description

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

Details

Package:	tikzDevice
Type:	Package
Version:	0.6.3
Date:	2011-11-13
License:	GPL 2 or greater
LazyLoad:	yes

Options That Affect Package Behavior

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.

Font Size Calculations

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:

    \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.

Unicode

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

Author(s)

Cameron Bracken: [e-mail]

Charlie Sharpsteen: [e-mail]

Submit bug reports to: [e-mail]

References

The TikZ and PGF Packages: Manual for version 2.00
http://sourceforge.net/projects/pgf
Till Tanatu, February 20, 2008

See Also

tikz

Sharpie/RTikZDevice documentation built on May 9, 2019, 7:07 p.m.