| Title: | Post-Process 'ggplot2' Plots with 'TikZ' Code Using Plot Coordinates |
|---|---|
| Description: | Annotation of 'ggplot2' plots with arbitrary 'TikZ' code, using absolute data or relative plot coordinates. |
| Authors: | Oliver Thomas [aut, cre] |
| Maintainer: | Oliver Thomas <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.3 |
| Built: | 2025-02-12 05:12:26 UTC |
| Source: | https://github.com/osthomas/ggtikz |
The replacement values correspond to the edges of the available coordinate space
discretize(coord_values, xrange, yrange)discretize(coord_values, xrange, yrange)
coord_values |
numeric. The coordinate x and y values, potentially containing Inf or -Inf |
xrange |
Numeric vector of length 2, minimum and maximum values in the x direction |
yrange |
Numeric vector of length 2, minimum and maximum values in the y direction |
To prevent overlap with panel borders or axis lines, annotations are clipped to a viewport that is reduced in size by the width of these lines. They depend on the current plot theme.
get_padding_from_elements( gg_plot, elements_t, elements_r, elements_b, elements_l )get_padding_from_elements( gg_plot, elements_t, elements_r, elements_b, elements_l )
gg_plot |
A ggplot2 object. |
elements_t |
character vector with names of elements to consider for padding at the top |
elements_r |
character vector with names of elements to consider for padding on the right |
elements_b |
character vector with names of elements to consider for padding at the bottom |
elements_l |
character vector with names of elements to consider for padding on the left |
A vector grid::units of paddings for t, r, b, l (in pt)
uninfinite_coord for construction of the complete
replaced coordinate.
Convert data coordinates to npc coordinates.
## S3 method for class 'ggtikzCanvas' gg_to_npc(self, coord, panelx, panely, ...)## S3 method for class 'ggtikzCanvas' gg_to_npc(self, coord, panelx, panely, ...)
self |
a |
coord |
A numeric vector of length 2, with the x coordinate to convert
at |
panelx |
X position (column) of the panel holding the data |
panely |
X position (row) of the panel holding the data |
... |
unused |
The input coordinates from coord converted to npc coordinates in
the form of a numeric vector of length 2. (0,0) corresponds to the lower
left corner of the viewport containing the ggplot panel specified by
panelx and panely, and (1,1) corresponds to the upper right corner.
This is a helper function for quick one-step annotations. It creates a ggtikzCanvas from a ggplot, adds one annotation to it, and optionally draws the plot and the annotations.
ggtikz(gg_plot, ..., draw = TRUE)ggtikz(gg_plot, ..., draw = TRUE)
gg_plot |
A ggplot object on which annotations should be made. |
... |
Passed to |
draw |
TRUE or FALSE. Should gg_plot and the resulting annotation be drawn immediately? A tikz device needs to be open. |
For finer control, see ggtikzCanvas() and ggtikzAnnotation().
A ggtikzCanvas object with one
ggtikzAnnotation (specified in ...) already added. If
draw = TRUE, the gg_plot and the annotations are drawn to the currently
active device. This must be a tikzDevice, or an error will be raised.
ggtikzCanvas for creating a canvas which can store
multiple annotations.
ggtikzAnnotation for creating an annotation, which can
then be added to a canvas.
## Not run: library(ggplot2) library(tikzDevice) library(ggtikz) p <- ggplot(mtcars, aes(disp, mpg)) + geom_point() out <- tempfile(fileext = ".tikz") tikz(out) # Add a red circle in the middle of the plot. ggtikz(p, "\\fill[red] (0.5,0.5) circle (2mm);", xy="plot") dev.off() ## End(Not run)## Not run: library(ggplot2) library(tikzDevice) library(ggtikz) p <- ggplot(mtcars, aes(disp, mpg)) + geom_point() out <- tempfile(fileext = ".tikz") tikz(out) # Add a red circle in the middle of the plot. ggtikz(p, "\\fill[red] (0.5,0.5) circle (2mm);", xy="plot") dev.off() ## End(Not run)
ggtikzAnnotation objects are meant to be added to a ggtikzCanvas object.
ggtikzAnnotation( tikz_code, x = c("data", "panel"), y = c("data", "panel"), xy = NULL, panelx = NULL, panely = NULL, transform = TRUE, replace_inf = TRUE, clip = "on" )ggtikzAnnotation( tikz_code, x = c("data", "panel"), y = c("data", "panel"), xy = NULL, panelx = NULL, panely = NULL, transform = TRUE, replace_inf = TRUE, clip = "on" )
tikz_code |
The tikz code to use for annotation. Backslashes must be escaped! |
x |
Reference frame for the x coordinates. Either "data" or "panel". |
y |
Reference frame for the y coordinates. Either "data" or "panel". |
xy |
Reference frame for both x and y coordinates. Trumps |
panelx |
x position of the panel to use as coordinate reference, starting from the left, 1-based. |
panely |
y position of the panel to use as coordinate reference, starting from the top, 1-based. |
transform |
Should TikZ coordinates be transformed according to the
scale transformation? If |
replace_inf |
Should annotation coordinates containing 'Inf' or '-Inf'
be adjusted so these values correspond to the edge of the available space?
This is analogous to the behavior of ggplot when infinite values are
encountered.
See also |
clip |
Should annotations be clipped to the panel boundaries?
See the |
This function prepares TikZ annotations in a form understandable to a ggtikzCanvas object. An annotation can be added to multiple ggtikzCanvas objects, provided that each underlying ggplot object has the necessary panels to know what to do with this information.
A ggtikzAnnotation object, which can be added to a ggtikzCanvas object.
grid.tikzAnnotate for annotation of base graphics
ggtikz for a helper function for quick one-step annotations.
ggtikzCanvas for information about initiating the annotation process.
Annotations can be made relative to the whole plot, to a panel, or to data coordinates (of individual panels).
ggtikzCanvas(gg_plot)ggtikzCanvas(gg_plot)
gg_plot |
A ggplot object on which annotations should be made. |
This function provides a canvas for TikZ annotations, and does not draw anything by itself. Its purpose is to provide information about the underlying ggplot object for coordinate calculations.
A ggtikzCanvas object, to which annotations can be added.
grid.tikzAnnotate for annotation of base
graphics.
ggtikz for a helper function for quick one-step
annotations.
ggtikzAnnotation for more information about creating
and adding ggtikz annotations.
## Not run: library(ggplot2) library(tikzDevice) library(ggtikz) p <- ggplot(mtcars, aes(disp, mpg)) + geom_point() # Create a TikZ canvas on the plot canvas <- ggtikzCanvas(p) # Create annotations to add to the canvas # Circle in the center of the plot annotation1 <- ggtikzAnnotation( "\\fill[red] (0.5,0.5) circle (2mm);", xy = "plot") # Arrow to data coordinate (400,20) annotation2 <- ggtikzAnnotation( "\\draw[<-] (400,20) -- ++(0,2.5);", xy = "data", panelx = 1, panely = 1) out <- tempfile(fileext = ".tikz") tikz(out) # First, draw the original plot p # Then, add the annotations to the canvas and draw it canvas + annotation1 + annotation2 dev.off() ## End(Not run)## Not run: library(ggplot2) library(tikzDevice) library(ggtikz) p <- ggplot(mtcars, aes(disp, mpg)) + geom_point() # Create a TikZ canvas on the plot canvas <- ggtikzCanvas(p) # Create annotations to add to the canvas # Circle in the center of the plot annotation1 <- ggtikzAnnotation( "\\fill[red] (0.5,0.5) circle (2mm);", xy = "plot") # Arrow to data coordinate (400,20) annotation2 <- ggtikzAnnotation( "\\draw[<-] (400,20) -- ++(0,2.5);", xy = "data", panelx = 1, panely = 1) out <- tempfile(fileext = ".tikz") tikz(out) # First, draw the original plot p # Then, add the annotations to the canvas and draw it canvas + annotation1 + annotation2 dev.off() ## End(Not run)
ggtikzTransform extracts coordinates definitions in an annotation's TikZ code and transforms them with the transformer functions stored in the underlying plot's x or y scales, respectively.
ggtikzTransform(ggtikzCanvas, ggtikzAnnotation)ggtikzTransform(ggtikzCanvas, ggtikzAnnotation)
ggtikzCanvas |
A |
ggtikzAnnotation |
A |
This function does not have to called directly. It is automatically called
when annotations are added to a canvas, if transform = TRUE in the
ggtikzAnnotation construction call.
Coordinates components with physical lengths are not changed. For a plot with a linear x scale and a log10-transformed y scale,
the TikZ coordinate (10,10) becomes (10,1),
the TikZ coordinate (10cm,10) becomes (10cm,1),
the TikZ coordinate (10,10cm) becomes (10,10cm)
the TikZ coordinate (0,0) will raise an error.
A link{ggtikzAnnotation} object, with transformations applied
to the coordinates in the TikZ code.
Infinite values in TiKZ coordinate specifications are replaced by values corresponding to the edge of the available coordinate space. This allows placement of annotations at the very edge of a panel without knowing its precise coordinates. This is useful for annotations which extend to the panel boundaries, but also make use of specific coordinates.
ggtikzUninfinite(ggtikzCanvas, ggtikzAnnotation)ggtikzUninfinite(ggtikzCanvas, ggtikzAnnotation)
ggtikzCanvas |
A |
ggtikzAnnotation |
A |
A link{ggtikzAnnotation} object, with Infinites in coordinates
replaced by finite values.
tikzDevice.By default, plots produced with the tikzDevice are clipped to the plot area, which also clips ggtikzAnnotations extending beyond the plot boundaries. This function removes the 'clip' and 'use as bounding box' options in a tikz file.
set_ggtikz_unclip_hook() unset_ggtikz_unclip_hook()set_ggtikz_unclip_hook() unset_ggtikz_unclip_hook()
Called for side effects - the unclip knitr hook is set or unset,
respectively.
unclip, the hook that is being set.
Split a TikZ coordinate.
split_coord(coord)split_coord(coord)
coord |
Coordinate string of the form "(x,y)" |
A character vector of length 2: The x and y components of the coordinate. These may contain spaces.
Construct a regex pattern for possible tikzDevice extensions.
tikz_exts_pattern(options)tikz_exts_pattern(options)
options |
A list of |
A regex pattern to match file extensions of tikz figures
Note that the chunk options unclip = TRUE and external = FALSEmust be set
for the hook to come into effect!
unclip(before, options)unclip(before, options)
before |
see |
options |
see |
Called for side effect. The files containing tikz plots are edited and overwritten.
set_ggtikz_unclip_hook to set the knitr hook.
unclip_tikz, the workhorse function for this hook.
tikzDevice.By default, plots produced with the tikzDevice are clipped to the plot area, which also clips ggtikzAnnotations extending beyond the plot boundaries. This function removes the 'clip' and 'use as bounding box' options in a tikz file.
unclip_tikz(fpath)unclip_tikz(fpath)
fpath |
Path to the tikz file |
This function can be used for manual post-processing, however,
see set_ggtikz_unclip_hook to set the corresponding knitr hook.
Called for side effect.
The file at fpath is edited and overwritten.
set_ggtikz_unclip_hook to set the knitr hook.
Infinite values are replaced with the minimum or maximum value of the padding in the x or y direction, respectively. Additionally, the adjusted coordinate is padded so that it lies just next to the panel borders and axis lines without overlap.
uninfinite_coord(coord, xrange, yrange) uninfinite_tikz(tikz_code, xrange, yrange)uninfinite_coord(coord, xrange, yrange) uninfinite_tikz(tikz_code, xrange, yrange)
coord |
TikZ coordinate |
xrange |
Numeric vector of length 2, minimum and maximum values in the x direction |
yrange |
Numeric vector of length 2, minimum and maximum values in the y direction |
tikz_code |
The TikZ code to replace Infinite values in. |
The adjusted TikZ coordinate with padding, as a string.