tikzDevice (version 0.12.6)

tikz: 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 included inside a LaTeX document by specifying \usepackage{tikz} in the document header.

Usage

tikz(
  file = filename,
  filename = ifelse(onefile, "./Rplots.tex", "./Rplot%03d.tex"),
  width = 7,
  height = 7,
  onefile = TRUE,
  bg = "transparent",
  fg = "black",
  pointsize = 10,
  lwdUnit = getOption("tikzLwdUnit"),
  standAlone = FALSE,
  bareBones = FALSE,
  console = FALSE,
  sanitize = FALSE,
  engine = getOption("tikzDefaultEngine"),
  documentDeclaration = getOption("tikzDocumentDeclaration"),
  packages,
  footer = getOption("tikzFooter"),
  symbolicColors = getOption("tikzSymbolicColors"),
  colorFileName = "%s_colors.tex",
  maxSymbolicColors = getOption("tikzMaxSymbolicColors"),
  timestamp = TRUE,
  verbose = interactive()
)

Value

tikz() returns no values.

Arguments

file, filename

A character string indicating the desired path to the output file. If both arguments are used in the function call, file will be preferred.

width

The width of the output figure, in inches.

height

The height of the output figure, in inches.

onefile

Should output be directed to separate environments in a single file (default TRUE). If FALSE this option works exactly like the argument of the same name to pdf() (see there for more details).

bg

The starting background color for the plot.

fg

The starting foreground color for the plot.

pointsize

Base pointsize used in the LaTeX document. This option is only used if a valid pointsize cannot be extracted from the value of getOption("tikzDocumentDeclaration"). See the section "Font Size Calculations" in tikzDevice-package for more details.

lwdUnit

The number of pts in LaTeX that lwd = 1 in R is translated to. Defaults to 0.4 (LaTeX and TikZ default); for compatibility with R default, please use 72.27/96 (96 pixels in R is 1 inch, which is 72.27 points in TeX).

standAlone

A logical value indicating whether the output 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.

console

Should the output of tikzDevice be directed to the R console (default FALSE). This is useful for dumping tikz output directly into a LaTeX document via sink(). If TRUE, the file argument is ignored. Setting file = '' is equivalent to setting console=TRUE.

sanitize

Should special latex characters be replaced (Default FALSE). See the section "Options That Affect Package Behavior" for which characters are replaced.

engine

a string specifying which TeX engine to use. Possible values are 'pdftex', 'xetex' and 'luatex'. See the Unicode section of tikzDevice-package for details.

documentDeclaration

See the sections "Options That Affect Package Behavior" and "Font Size Calculations" of tikzDevice-package for more details.

packages

See the section "Options That Affect Package Behavior" of tikzDevice-package.

footer

See the section "Options That Affect Package Behavior" of tikzDevice-package.

symbolicColors

A logical value indicating whether colors are written as RGB values or as symbolic names in which case the need to be defined in the LaTeX document. These definitions can be generated with the following colorFileName parameter. See also the section "Options That Affect Package Behavior" of tikzDevice-package.

colorFileName

a character string indicating where the color map for symbolic colors is to be stored. It can contain a placeholder %s where the tikz filename is inserted. If the string is empty, no file is written.

maxSymbolicColors

an integer number indicating the maximal number of distinct colors to write symbolically. Any excess color will be defined as if symbolicColors was set to FALSE. See also the section "Options That Affect Package Behavior" of tikzDevice-package.

timestamp

A logical value indicating whether a timestamp is written to the TeX file.

verbose

A logical value indicating whether diagnostic messages are printed when measuring dimensions of strings. Defaults to TRUE in interactive mode only, to FALSE otherwise.

Author

Charlie Sharpsteen and Cameron Bracken

Details

The TikZ device enables LaTeX-ready output from graphics functions. This is done by encoding graphics commands using TikZ markup. 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 three modes of output depending on the value of the standAlone and bareBones arguments. If standAlone and bareBones are set to the default value of FALSE, the resulting file will only contain graphics output wrapped in a LaTeX tikzpicture environment. 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.

When bareBones is set to TRUE, the output is not wrapped in a document or a tikzpicture environment. This is useful for embedding an generated graphic within an existing TikZ picture.

In cases where both standAlone and bareBones have been set to TRUE, the standAlone option will take precedence.

When the option symbolicColors is set to TRUE, the colors will be written as symbolic names, e.g. red, gray90 and similar. If the color is not mapped to a symbolic name in R, the color will be named XXXXX when #XXXXXX is its hexadecimal color. All the color names will have to be defined in the enclosing document, which is automatically written if the path of a color file colorFileName is set.

References

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

See Also

pictex(), getLatexCharMetrics(), getLatexStrWidth(), setTikzDefaults(), tikzAnnotate(), sanitizeTexString()

Examples

if (FALSE) {

## 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 Math 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='Random Circles')
    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)
################################################
}