tikz {tikzDevice}R Documentation

TikZ Graphics Device

Description

tikz is used to open a R graphics device which supports output in the TikZ graphics language. TikZ code may be used inside a LaTeX document by specifying \usepackage{tikz} in the document header.

Usage

tikz(file = "Rplots.tex", width = 7, height = 7, 
        bg="white", fg="black", standAlone = FALSE, bareBones = FALSE, 
        documentDeclaration = getOption("tikzDocumentDeclaration"),
        packages = getOption("tikzLatexPackages"),
        footer = getOption("tikzFooter"))

Arguments

file A character string indicating the desired path to the output file.
width The width of the output figure, in inches.
height The height of the output figure, in inches.
bg The starting background color for the plot.
fg The starting foreground color for the plot.
standAlone A logical value indicating whether the resulting file should be suitable for direct processing by LaTeX. A value of FALSE indicates that the file is intended for inclusion in a larger document. See ‘Details’.
bareBones A logical value. When TRUE the figure will not be wrapped in a tikzpicture environment. This option is useful for embedding one TikZ picture within another. When TRUE multipage output will be drawn on a single page.
documentDeclaration See the section ``Options That Affect Package Behavior.''
packages See the section ``Options That Affect Package Behavior.''
footer See the section ``Options That Affect Package Behavior.''

Details

The TikZ device enables LaTeX-ready output from R graphics functions. This is done by producing code that can be understood by the TikZ graphics language. All text in a graphic output with tikz will be typeset by LaTeX and therefore will match whatever fonts are currently used in the document. This also means that LaTeX mathematics can be typeset directly into labels and annotations.

The TikZ device currently supports two modes of output depending on the value of the parameter standAlone. If standAlone is set to FALSE, the default, the resulting file will only contain the tikzpicture environment and the commands to build your graphic. Since this file is not a complete LaTeX document, it will need to be included in another LaTeX document using the \input command. For example,

\documentclass{article}
\usepackage{tikz}
\begin{document}
    \begin{figure}
        \centering
        \input{Rplots.tex}
        \caption{}
    \end{figure}
\end{document}

When standAlone is set to TRUE, the device wraps the tikzpicture environment in a complete LaTeX document suitable for direct compilation. In this mode the preview package is used to crop the resulting output to the bounding box of the graphic.

Value

tikz() returns no values.

Options That Affect Package Behavior

The tikzDevice package is currently influenced by a number of global options that may be set your R scripts, in the R console or in your 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). The defaults , if are any for a given option, are shown below the description. The global options are:

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' ).
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 documentclass declaration when standAlone == TRUE as well. as when font metrics are calculated. The default value is:
options( tikzDocumentDeclaration = "\\documentclass{article}" )
tikzFooter
A character vector. The footer to be used only when standAlone==TRUE. The default value is:
options( tikzFooter = c( "\\end{document}" ) )
tikzLatexPackages
A character vector. These are the packages which are included when using the standAlone option as well as when font metric are calculated. The default value is:
options( tikzLatexPackagesDefault = c(
        "\\usepackage{tikz}",
        "\\usepackage[active,tightpage]{preview}",
        "\\PreviewEnvironment{pgfpicture}",
        "\\setlength\\PreviewBorder{0pt}") )
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}"))
                

Note

To compile the output of tikz a working installation of LaTeX and PGF is needed. Current releases of the TikZ package are available from http://www.ctan.org. The package may also be installed through the MikTeX package manager on Windows or using the TeX Live package manager, tlmgr, on Unix/Linux/OS X. The TeX Live package manager will only be installed by default for TeX Live distributions dated 2008 and later. Both bleeding-edge and release versions of TikZ may be obtained from the project website hosted at http://sourceforge.net/projects/pgf/.

Multiple plots will be placed as separate environments in the output file.

Author(s)

Charlie Sharpsteen source@sharpsteen.net and Cameron Bracken cameron.bracken@gmail.com

References

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

See Also

pictex, getLatexCharMetrics, getLatexStrWidth, setTikzDefaults, tikzAnnotate

Examples

## Not run: 
                
## Example 1 ###################################
#Set up temporary work directory
td <- tempdir()
tf <- file.path(td,'example1.tex')
oldwd <- getwd()
setwd(td)

# Minimal plot
tikz(tf,standAlone=TRUE)
        plot(1)
dev.off()

# View the output
tools::texi2dvi(tf,pdf=T)
system(paste(getOption('pdfviewer'),file.path(td,'example1.pdf')))
setwd(oldwd)
################################################
                
## Example 2 ###################################
#Set up temporary work directory
td <- tempdir()
tf <- file.path(td,'example2.tex')
oldwd <- getwd()
setwd(td)

#LaTeX math symbol names
syms <-c('alpha','theta','tau','beta','vartheta','pi','upsilon',
                  'gamma','gamma','varpi','phi','delta','kappa','rho',
                  'varphi','epsilon','lambda','varrho','chi','varepsilon',
                  'mu','sigma','psi','zeta','nu','varsigma','omega','eta',
                  'xi','Gamma','Lambda','Sigma','Psi','Delta','Xi','Upsilon',
                  'Omega','Theta','Pi','Phi')
x <- rnorm(length(syms))
y <- rnorm(length(syms))

tikz(tf,standAlone=TRUE)
        plot(-2:2, -2:2, type = "n", axes=F, 
                        xlab='', ylab='', main='TikZ Device Example')
    text(x,y,paste('\\Large$\\',syms,'$',sep=''))
dev.off()

#View the output
tools::texi2dvi(tf,pdf=TRUE)
system(paste(getOption('pdfviewer'),file.path(td,'example2.pdf')))
setwd(oldwd)
################################################

## Example 3 ###################################
#Set up temporary work directory
td <- tempdir()
tf <- file.path(td,'example3.tex')
oldwd <- getwd()
setwd(td)

tikz(tf,standAlone=TRUE)
        plot(-2:2, -2:2, type = "n", axes=F, xlab='', ylab='', main=main)
    points(rnorm(50), rnorm(50), pch=21, 
                        bg=rainbow(50,alpha=.5), cex=10)
dev.off()

#View the output
tools::texi2dvi(tf,pdf=TRUE)
system(paste(getOption('pdfviewer'),file.path(td,'example3.pdf')))
setwd(oldwd)
################################################
## End(Not run)

[Package tikzDevice version 0.4.8 Index]