tikzDevice (version 0.12)

tikzAnnotate: Add Custom TikZ Code to an Active Device

Description

These functions allow custom (LaTeX) commands to be added to the output of an active tikzDevice.

Usage

tikzAnnotate(annotation, checkstate = TRUE)
tikzNode(x = NULL, y = NULL, opts = NULL, name = NULL, content = NULL,
  units = "user")
tikzCoord(x, y, name, units = "user")
tikzAnnotateGrob(annotation)
tikzNodeGrob(x = NULL, y = NULL, opts = NULL, name = NULL,
  content = NULL, units = "native")
tikzCoordGrob(x, y, name, units = "native")
grid.tikzAnnotate(annotation, draw = TRUE)
grid.tikzNode(x = NULL, y = NULL, opts = NULL, name = NULL,
  content = NULL, units = "native", draw = TRUE)
grid.tikzCoord(x, y, name, units = "native", draw = TRUE)

Arguments

annotation

A character vector, one element per line to be added to the open tikz device.

checkstate

A logical, whether to "flush" the device state prior to writing the annotation.

x

numeric, x location for a named coordinate in user coordinates

y

numeric, y location for a named coordinate in user coordinates

opts

A character string that will be used as options for a node. See the "Nodes and Edges" section of the TikZ manual for complete details.

name

Optional character string that will be used as a name for a coordinate or node. Other TikZ commands can use this name to refer to a location in a graphic.

content

A character string that will be used as the content to be displayed inside of a node. If left as NULL a coordinate will be created instead of a node. If a node with empty content is truely desired, pass an empty string "".

units

Character string specifying the unit system associated with x and y. See grconvertX() for acceptable units in base graphics and unit() for acceptable units in grid graphics.

draw

A logical value indicating whether graphics output should be produced.

Value

Nothing returned.

Details

tikzAnnotate is intended to allow the insertion of arbitrary TikZ commands into the output stream of a graphic. For LaTeX commands that reference specific locations in an R plot, coordinates must be specified in "device units" which for tikz output are TeX points relative to the lower left corner of the device canvas. Functions such as grconvertX() and gridToDevice() can help make the necessary conversions for base and grid graphics. The tikzNode and tikzCoord functions automatically perform unit conversions acording the the value of their units parameters.

tikzNode is a wrapper for tikzAnnotate that inserts TikZ \node or \coordinates commands into the output. The difference between a node and a coordinate is the presence of a content section that can contain arbitrary LaTeX text. This is useful for adding textual annotations at specific locations in a TikZ graphic. The tikzCoord function is a wrapper for tikzNode that simplifies the task of inserting named coordinates.

Additionally, the tikzAnnotateGrob, tikzNodeGrob and tikzCoordGrob functions are supplied for creating grid objects or "grob()s" that can be used in Grid graphics. High level wrapper functions grid.tikzAnnotate, grid.tikzNode and grid.tikzCoord are also supplied which creat and render a grob in one step.

See the TikZ Device vignette for more information and examples and the TikZ manual for the definitive reference on what is possible with nodes.

See Also

grconvertX() grconvertY() gridToDevice() unit() tikz()

Examples

# NOT RUN {
# }
# NOT RUN {
### Example 1: Annotations in Base Graphics
# Load some additional TikZ libraries
tikz("annotation.tex",width=4,height=4,
  packages = c(getOption('tikzLatexPackages'),
    "\\usetikzlibrary{decorations.pathreplacing}",
    "\\usetikzlibrary{positioning}",
    "\\usetikzlibrary{shapes.arrows,shapes.symbols}")
)

p <- rgamma (300 ,1)
outliers <- which( p > quantile(p,.75)+1.5*IQR(p) )
boxplot(p)

# Add named coordinates that other TikZ commands can hook onto
tikzCoord(1, min(p[outliers]), 'min outlier')
tikzCoord(1, max(p[outliers]), 'max outlier')

# Use tikzAnnotate to insert arbitrary code, such as drawing a
# fancy path between min outlier and max outlier.
tikzAnnotate(c("\\draw[very thick,red,",
  # Turn the path into a brace.
  'decorate,decoration={brace,amplitude=12pt},',
  # Shift it 1em to the left of the coordinates
  'transform canvas={xshift=-1em}]',
  '(min outlier) --',
  # Add a node with some text in the middle of the path
  'node[single arrow,anchor=tip,fill=white,draw=green,',
  'left=14pt,text width=0.70in,align=center]',
  '{Holy Outliers Batman!}', '(max outlier);'))

# tikzNode can be used to place nodes with customized options and content
tikzNode(
  opts='starburst,fill=green,draw=blue,very thick,right=of max outlier',
  content='Wow!'
)

dev.off()


### Example 2: Annotations in Grid Graphics
library(grid)

tikz("grid_annotation.tex",width=4,height=4,
  packages = c(getOption('tikzLatexPackages'),
    "\\usetikzlibrary{shapes.callouts}")
)

pushViewport(plotViewport())
pushViewport(dataViewport(1:10, 1:10))

grid.rect()
grid.xaxis()
grid.yaxis()
grid.points(1:10, 1:10)

for ( i in seq(2,8,2) ){
  grid.tikzNode(i,i,opts='ellipse callout,draw,anchor=pointer',content=i)
}

dev.off()

# }
# NOT RUN {

# }